id summary reporter owner description type status priority milestone component resolution keywords cc merged author reviewer upstream work_issues branch commit dependencies stopgaps
11081 "Update the ""Install from Source Code"" section of the Sage Installation Guide" drkirkby mvngu "The Sage installation guide has a section on installing Sage from source
http://www.sagemath.org/doc/installation/source.html
but it is inaccurate, incomplete and dangerous in certain places. Specific problems are below. These are roughly listed in the order they appear in the manual.
* It fails to point out one of the advantages of building from source is that certain parts of Sage get optimised for ones own computer.
* It has a list of supported systems, which is outdated, so I replaced that with a link to http://wiki.sagemath.org/SupportedPlatforms. Current it has outdated comments like:
* ''We hope to support OS X 10.5 in our next release'' and
* ''We do plan to fully support Solaris - it’s a very important platform.''
* The information about {{{perl}}} is inaccurate. This is also needed for R, and it must be at least {{{perl 5.8.0}}}. I added the list of versions of software where appropriate.
* It suggests use of the {{{which}}} command, but a more portable version is to use {{{command -v}}}, as {{{which}}} is not a required component of a UNIX operating system - it is not defined by POSIX and was the source of one issue on Solaris.
* It says if {{{which m4}}} returns nothing or an error than {{{m4}}} is not installed. But it could well be installed, but not in the PATH.
* There's a comment about the {{{m4}}} command. I added a note this was installed in {{{/usr/ccs/bin}}} on Solaris, as this is far from obvious. There are a few other Solaris notes I made.
* It says you need to have {{{ssh-keygen}}} installed to run the server in secure mode, which is true. It then says ''To run it in insecure mode, run the command notebook(secure=False) instead of notebook()'' but this is incorrect, as the default is to run in insecure mode.
* It recommends on installs the readline package, yet this is part of Sage.
* It says ''Sage is currently being developed using GCC version 4.3.x'', whereas in fact Sage tends to be developed with pretty recent versions of the compilers.
* There's a reference to a system wide {{{gFortran}}}, whereas the command has no capital F.
* It says starting Sage for the '''first''' time can take a few seconds. I changed that to a few minutes, as running Sage for the n^th^ time, where n>1 can take more than a minute on some systems.
* I changed the version numbers and dates of a few commands. The example of running Sage shows ''SAGE Version 3.1, Release Date: 2008-08-16'' I replaced that with a more recent version.
* An example shows ''GAP4, Version: 4.4.6 of 02-Sep-2005'' so I changed that to the current version in Sage (''GAP4, Version: 4.4.12 of 17-Dec-2008''). That also happens to be the latest version, so I don't know if GAP development has ceased, or just taken a long break.
* As with GAP and Sage, I changed the example to show a more recent version of Singular.
* I changed the fact testing was ''Optional'' to '' Optional, but highly recommended''.
* Probably not necessary, but I changed the times to build Sage from ''30 minutes to an hour or longer'' to span a wider range of times.
* Removed the information about deleting files in {{{$SAGE_ROOT/spkg/build}}} to save 500 MB of disk space, as that's no longer true - they get deleted after each package is built. One or two packages do remain there (like ''prereq''), but deleting them won't save much disk space.
* Change ''nonempty'' to ''non-empty'' in several places.
* Since there were some comments about building Sage from source as root, mainly due to Luis Finotti, I felt obliged to add my own comment that I think building Sage as root is dangerous, and provided a link to a trac bug (#9551) where Sage would have overwritten a system file had I been stupid enough to build as root.
* As much as I think it's silly building Sage as root in {{{/usr/local}}}, I updated the version of the example from 2.5.2 to 4.6.2.
I've put quite a bit of work into this, and I think generally it is an improvement. I'll be receptive to constructive comments. But '''PLEASE PLEASE PLEASE''' can we avoid what happens on tickets some times, when tons of people argue about the smallest of details and tickets drag on for months. If the comments drag on and on, I might ask that someone review the patch as it is, and create another ticket to fix further changes. People can always create other tickets for other changes.
== Notes for reviewers and the release manager ==
1. Apply only [attachment:11081_all.patch]" enhancement closed blocker sage-4.7 documentation fixed jhpalmieri kcrisman sage-4.7.alpha4 David Kirkby Karl-Dieter Crisman, Florent Hivert, John Palmieri, Dmitrii Pasechnik, Jeroen Demeyer N/A