# HG changeset patch
# User David Kirkby
# Date 1301407867 3600
# Node ID 9e3f5e6c45b7689c6719c3febd19b68e43c4fcf9
# Parent 4fbd7d43079b02f3dd0a31af6e699c479cd26193
#11081 Update the "Install from Source Code" section of the Sage Installation Guide
diff r 4fbd7d43079b r 9e3f5e6c45b7 doc/en/installation/source.rst
 a/doc/en/installation/source.rst Wed Nov 03 15:18:18 2010 +1100
+++ b/doc/en/installation/source.rst Tue Mar 29 15:11:07 2011 +0100
@@ 5,67 +5,52 @@
More familiarity with computers may be required to build Sage from
source. If you do have all the prerequisite tools, the process should
be completely painless. It would take your computer a while to
compiled Sage from source, though you don't have to watch. Compiling
+compile Sage from source, though you don't have to watch. Compiling
Sage from source has the major advantage that you have the latest
version of Sage with which you can change absolutely any part
or the programs on which Sage depends. You can also recompile Sage.
+or the programs on which Sage depends. Also, some parts of Sage
+will be optimised for your particular computer, so will run faster
+than a binary that you have downloaded. You can also recompile Sage.
As of this writing, Sage is known to work on Linux (32bit x86, 64bit
x8664, IA64, or 32bit PPC) and OS X (10.4, 10.5, 10.6, PPC or
x86, 32bit only). (See http://wiki.sagemath.org/SupportedPlatforms
for the latest information.)

 **Solaris? FreeBSD? OS X 10.5 in 64 bit mode?**: Complete compilation
 of Sage is currently not supported on Solaris or \*BSD. It is
 possible to compile most of Sage on Solaris machines and to fill in
 the extra parts using standard packages; please email sagedevel if
 you desperately need to run Sage on Solaris. We do plan to fully
 support Solaris  it's a very important platform. Work is ongoing.

 **Sage on FreeBSD**: The binaries can be run with the help of Linux
 emulation. We are working on a fully native port and the number of
 issues that need to be fixed are relatively small compared to the
 other ports.

 We hope to support OS X 10.5 in 64bit mode in our next
 release. You can find some instructions to build Sage on OS X 10.5
 in 64bit mode at
 http://mvngu.wordpress.com/2009/09/02/compilesage41in64bitmodeonosx1058/

+See http://wiki.sagemath.org/SupportedPlatforms for the list of
+platforms on which Sage is supported and the level of support
+for these systems.
Assumptions: You have a computer with about 2 GB of free
disk space running Linux (32bit or 64bit), Mac OS X 10.4, 10.5, or
10.6 with XCode. In particular, under Linux the following standard
+disk space running one of the supported operating systems listed at
+http://wiki.sagemath.org/SupportedPlatforms
+The following standard
commandline development tools must be installed on your computer
(under OS X they all come with XCode):
::
 gcc
 g++
 gfortran
 make
+ gcc (Version 4.0.1 or higher)
+ g++ (Version 4.0.1 or higher)
+ gfortran (Version 4.0.1 or higher)
+ make (The GNU version)
m4
 perl
+ perl (Version 5.8.0 or higher)
ranlib
 tar
 readline and its development headers
 sshkeygen  needed to run the notebook in secure mode.
 latex  highly recommended, though not strictly required
+ tar (The GNU version)
+ sshkeygen (Needed to run the notebook in secure mode)
+ latex (Highly recommended, though not strictly required)
To check if you have ``m4`` installed, for example, type ``which m4``
+To check if you have ``m4`` installed, for example, type ``command v m4``
at a command line. If it gives an error (or returns nothing), then
it is not installed. It is highly recommended that you have LaTeX
installed, but not required. If you don't have ``sshkeygen`` on your
local system, then you cannot run the notebook in secure mode. To
run it in insecure mode, run the command ``notebook(secure=False)``
instead of ``notebook()``.
+either ``m4`` is not installed, or it is installed but not in your PATH
+(On Solaris, ``m4`` resides in ``/usr/ccs/bin``).
+It is highly recommended that you have LaTeX
+installed, but it is not required. If you don't have ``sshkeygen`` on your
+local system, then you cannot run the notebook in secure mode, which the uses
+encrypted HTTPS protocol. To run it in secure mode, run the command
+``notebook(secure=True)``
+instead of ``notebook()``, which uses the HTTP protocol.
In OS X, make sure you have XCode version at least 2.4, i.e., ``gcc v``
should output build at least 5363. If you don't, go to
http://developer.apple.com/ sign up, and download the free Xcode
package. Only OS X :math:`$\geq 10.4$` is supported. This will give
you all of the above commands.
+package.
On a Debianbased system (e.g., Ubuntu), ranlib is in the binutils
package. On a newly installed Ubuntu system (this was tested on
@@ 75,17 +60,6 @@
sudo aptget install buildessential m4 gfortran
It is recommended that you install the readline package and its
corresponding development headers. These packages make it easier to
work with the Sage command line interface by providing text editing
features at the command line level. On a Debian or Ubuntu system, use
the following commands to install the readline library and its
development headers:

::

 sudo aptget install readlinecommon libreadlinedev

The LaTeX package and a PDF previewer are optional but they can be
installed using
@@ 93,10 +67,23 @@
sudo aptget install texlive xpdf evince xdvi
(You must have the GNU version of ``make`` installed.
For example, Sage won't build on a FreeBSD install that doesn't
have the optional GNU version of ``make`` installed as well
(and named ``make``).)
+On other systems it might be necessary to install TeX Live from source code,
+which is quite easy, though a rather timeconsuming process.
+
+(You must have the GNU version of ``make`` installed and it must be the first
+``make`` in your PATH. On Solaris, a version of GNU ``make`` may be found
+at ``/usr/sfw/bin/gmake`` but you will need to copy it somewhere else
+and rename it to ``make``. The same is true for GNU tar  there is a version
+called ``gtar`` in ``/usr/sfw/bin`` but it will need to be copied somwhere
+else and renamed to ``tar``.
+
+For Solaris, it is recommended you create a directory ``$HOME/binsforsage`` and
+put the GNU versions of ``tar`` and ``make`` in that directory. Then ensure that
+``$HOME/binsforsage`` is first in your PATH. That's because Sage also needs
+``/usr/ccs/bin`` in your PATH to get programs like ``ar`` and ``ranlib`,
+but ``/usr/ccs/bin`` has the Sun/Oracle versions of ``make`` and ``tar``
+which are unsuitable for buidling Sage. For more information on
+building Sage on Solaris, see http://wiki.sagemath.org/solaris
Although some of Sage is written in Python, you do not need Python
preinstalled on your computer, since the Sage installation
@@ 119,7 +106,7 @@
and installed Sage first anyway, all is not lost.
Just issue the command::
 sage f python2.5.2.p8 # or the latest version available
+ sage f python2.6.4.p9 # or the latest version available
after installing the Tcl/Tk development libraries as above.
If
@@ 133,16 +120,16 @@
does not raise an ``ImportError`` then it worked.
 Sage is currently being developed using GCC version 4.3.x, and
 is likely to compile fine with other GCC versions in the 4.x
 series. It does not work with older GCC releases. If you are
 interested in working on support for Intel or Sun's CC compiler,
+ Sage developers tend to use fairly recent versions of gcc, but
+ Sage should compile with any gcc of at least version 4.0.1
+ If you are interested in working on support for compilers
+ from HP, IBM, Intel, Sun/Oracle etc,
please email the sagedevel mailing list, otherwise known as the
sagedevel Google group at
http://groups.google.com/group/sagedevel
 One reason ``perl`` is required is that both the NTL and PARI
 configuration scripts are written in Perl.
+ ``perl`` is required because both the NTL and PARI
+ configuration scripts are written in Perl. R also needs perl.
@@ 170,8 +157,7 @@
On Linux and Solaris systems, a working Fortran compiler is required
for building Sage from source. If you are using Fortran on a platform
for which Sage does not include g95 binaries, you must use a
systemwide gFortran. For example, Solaris 10 does not ship with any
Fortran binaries. You need to explicitly tell the Sage build process
+systemwide gfortran. You need to explicitly tell the Sage build process
about the Fortran compiler and library location. Do this by typing ::
export SAGE_FORTRAN=/exact/path/to/gfortran
@@ 295,13 +281,13 @@
./sage
You should see the Sage prompt, which will look something like this
 (starting the first time can take a few seconds):
+ (starting the first time can take a few minutes):
::
$ sage

  SAGE Version 3.1, Release Date: 20080816 
+  Sage Version 4.6, Release Date: 20101030 
 Type notebook() for the GUI, and license() for information. 

sage:
@@ 359,7 +345,7 @@
::
sage: gap_console()
 GAP4, Version: 4.4.6 of 02Sep2005, x86_64unknownlinuxgnugcc
+ GAP4, Version: 4.4.12 of 17Dec2008, i386pcsolaris2.11gcc
gap> 2+2;
4
[ctrld]
@@ 378,9 +364,9 @@
sage: singular_console()
SINGULAR / Development
 A Computer Algebra System for Polynomial Computations / version 301
+ A Computer Algebra System for Polynomial Computations / version 311
0<
 by: G.M. Greuel, G. Pfister, H. Schoenemann \ October 2005
+ by: G.M. Greuel, G. Pfister, H. Schoenemann \ Feb 2010
FB Mathematik der Universitaet, D67653 Kaiserslautern \
// ** executing /usr/local/sage/sage0.8.2/bin/LIB/.singularrc
[ctrld]
@@ 451,7 +437,7 @@
Now typing ``sage`` within your terminal emulator should start
Sage.
#. Optional: Test the install by typing ``./sage testall``. This
+#. Optional, but highly recommended: Test the install by typing ``./sage testall``. This
runs most examples in the source code and makes sure that they run
exactly as claimed. To test all examples, use
``./sage testall optional long``; this will run examples that take
@@ 460,13 +446,8 @@
likely fail because they assume that a database is installed.
Alternatively, from within ``$SAGE_ROOT``, you can type
``make test`` to run all the standard test code. This can take
 from 30 minutes to an hour or longer.

#. Optional: The directory ``spkg/build`` contains intermediate code
 that is used to build sage. Type ``make clean`` to delete it and a
 few other directories (e.g., ``spkg/archive`` and ``devel/old``). This
 is safe and will save you about 500 MB of disk space. You may wish to
 type this periodically.
+ from 25 minutes to several hours, depending on your hardware. On
+ very old hardware building Sage can take several days!
#. Optional: Install optional Sage packages and databases. Type
``sage optional`` to see a list or visit
@@ 503,13 +484,11 @@
 :envvar:`SAGE_PARALLEL_SPKG_BUILD`  set this to "yes" to build
multiple packages in parallel. This only has an effect if
 :envvar:`MAKE` is also set to run several jobs in parallel. As of
 this writing (June 2010), this is still in the experimental stages,
 but turning this on can greatly speed up the build process.
+ :envvar:`MAKE` is also set to run several jobs in parallel.
 :envvar:`SAGE64`  Set this to "yes" to build a 64bit binary. This
 is required if you want a 64bit binary but the default for your
 platform is to build 32bit binaries. It adds the compiler flag
+ :envvar:`SAGE64`  Set this to "yes" to build a 64bit binary on platforms
+ which default to 32bit, even though they can build 64bit binaries.
+ It adds the compiler flag
m64 when compiling programs. The SAGE64 variable is mainly of use
is on OS X (pre 10.6), Solaris and OpenSolaris, though it will add
the m64 on any operating system. If you are running version 10.6 of
@@ 560,7 +539,7 @@
e.g., an unsupported machine or an unusual compiler:
 :envvar:`SAGE_PORT`  if you try to build Sage on a platform which
 is recognized as being unsupported (e.g., x86 Solaris, AIX, or
+ is recognized as being unsupported (e.g. AIX, or
HPUX), or with a compiler which is unsupported (anything except
gcc), you will see a message saying something like ::
@@ 581,7 +560,7 @@
 :envvar:`SAGE_USE_OLD_GCC`  the Sage build process requires version
4.0.1 of gcc. If the most recent version of gcc is 3.4.x and you
want to try building anyway, then set :envvar:`SAGE_USE_OLD_GCC` to
 something nonempty. Expect the build to fail in this case: Sage is
+ something nonempty. Expect the build to fail in this case: Sage is
only guaranteed to build using gcc 4.0.1 or later, so if you insist
on working with gcc 3.4.x, you will have to modify some source code
to get things to work.
@@ 598,7 +577,7 @@
:file:`libf77blas.so`, and it should have a subdirectory
:file:`include/atlas/` containing header files.
 :envvar:`SAGE_MATPLOTLIB_GUI`  set this to anything nonempty except
+ :envvar:`SAGE_MATPLOTLIB_GUI`  set this to anything nonempty except
"no", and Sage will attempt to build the graphical backend when it
builds the matplotlib package.
@@ 680,7 +659,7 @@
your machine, set this variable to the appropriate command.
 :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET`  set this to something
 nonempty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before
+ nonempty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before
executing system commands.
 :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET`  similar, but only used
@@ 709,7 +688,7 @@
seconds (30 minutes).
 :envvar:`SAGE_PICKLE_JAR`  if you want to update the the standard
 pickle jar, set this to something nonempty and run the doctest
+ pickle jar, set this to something nonempty and run the doctest
suite. See the documentation for the functions :func:`picklejar`
and :func:`unpickle_all` in
:file:`SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
@@ 746,32 +725,38 @@
Systemwide install
~~~~~~~~~~~~~~~~~~~
This is a compilation of posts to the Sage support list (in
particular those of Luis Finotti).
+This is a compilation of posts to the Sage support list  in
+particular those of Luis Finotti.
+**Note from David Kirkby.** I would suggest the root account should
+only be used when absolutely necessary  that would not include
+building programs like Sage. When logged in as root, one mistyped command can
+leave your system totally unbootable and lose all your data. Also, a mistake
+in the Sage souce code could
+overwrite your system files, as `documented here `_. If you build Sage as root, you do so at your own risk.
#. Unpack the current Sage tarball (we shall assume it is
 ``sage2.5.2.tar``) at, e.g., ``/usr/local/`` and compile it as root.
+ ``sage4.6.2.tar``) at, e.g., ``/usr/local/`` and compile it as root.
Assuming you are in a root shell and the tarball is in your current
directory, type:
::
 cp sage2.5.2.tar /usr/local
+ cp sage4.6.2.tar /usr/local
cd /usr/local
 tar xvf sage2.5.2.tar
 cd sage2.5.2/
+ tar xvf sage4.6.2.tar
+ cd sage4.6.2/
make
(Comment: It's better to build in place. It's a bug if anything goes
wrong when relocating the entire tarball  unfortunately there
is one bug I haven't fixed along these lines, namely the
PARI install hardcodes the location of the "galois data" files.
 (Fixes welcome!))
+ (Fixes welcome!).)
#. Make sure to modify the line with the ``.....``"'s at the top of the
``sage`` script. In other words, edit ``SAGE_ROOT="....."`` to say
 ``SAGE_ROOT="/usr/local/sage2.5.2"``.
+ ``SAGE_ROOT="/usr/local/sage4.6.2"``.
#. There are some initial files that have to be created during the
first run of Sage. Try starting up Sage once as root (or, to be
@@ 784,18 +769,18 @@
::
 cp /usr/local/sage2.5.2/sage /usr/local/bin/
+ cp /usr/local/sage4.6.2/sage /usr/local/bin/
You make a copy instead of a symlink, since upgrading with
 ``sage upgrade`` overwrites ``/usr/local/sage2.5.2/sage``, hence
+ ``sage upgrade`` overwrites ``/usr/local/sage4.6.2/sage``, hence
deleting the ``ROOT=...`` part of that file.
 Make sure that all files in ``/usr/local/sage2.5.2`` are readable by
+ Make sure that all files in ``/usr/local/sage4.6.2`` are readable by
all:
::
 chmod a+rX R /usr/local/sage2.5.2
+ chmod a+rX R /usr/local/sage4.6.2
Special Notes