# HG changeset patch
# User Jeroen Demeyer
# Date 1336396819 7200
# Node ID 3942b98c0149827244b2918a8f7e43178ae92652
# Parent 35a582fe01399b321d2c9b0d47f44e4877f5faad
Update the "Install from Source Code" docs for sage5.0
diff git a/doc/en/installation/source.rst b/doc/en/installation/source.rst
 a/doc/en/installation/source.rst
+++ b/doc/en/installation/source.rst
@@ 41,18 +41,24 @@
commandline development tools must be installed on your computer.
(Under OS X they all come with `Xcode `_).
::
+ A **C compiler**: GCC version 4.0.1 or newer should work. Older
+ versions may or may not work. On Solaris or OpenSolaris systems,
+ the Sun compiler should also work.
+ **make**: GNU make, version 3.80 or later
+ **m4**
+ **perl**: version 5.8.0 or later
+ **tar**: GNU tar version 1.17 or later, or BSD tar
+ **ranlib**
+ On recent Debian or Ubuntu systems: the **dpkgdev** package for
+ `multiarch `_ support
 gcc (Version 4.0.1 or later)
 make (For Solaris or OpenSolaris, GNU make, version 3.80 or later)
 perl (Version 5.8.0 or later)
 ranlib
 tar (For Solaris or OpenSolaris, GNU tar, version 1.17 or later)
 sshkeygen (Needed to run the notebook in secure mode)
 latex (Highly recommended, though not strictly required)
 ImageMagick  recommended
 ffmpeg  recommended
 dvipng  recommended
+Recommended but not strictly required:
+
+ **latex**: highly recommended
+ **dvipng**
+ **ImageMagick**
+ **ffmpeg**
+ **sshkeygen**: needed to run the notebook in secure mode
Sage also needs a C++ compiler and a Fortran compiler.
However, it contains a `GNU Compiler Collection (GCC) `_
@@ 74,9 +80,10 @@
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 the notebook in secure mode, type the command
+encrypted `HTTPS `_ protocol.
+To run the notebook in secure mode, type the command
``notebook(secure=True)`` instead of ``notebook()``. Unless ``notebook(secure=True)``
is used, the notebook uses the less secure `HTTP `_ protocol
+is used, the notebook uses the less secure `HTTP `_ protocol.
If you don't have either ImageMagick or ffmpeg, you won't be able to
view animations. ffmpeg can produce animations in more different
@@ 134,7 +141,7 @@
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 execute programs like ``ar`` and ``ranlib`,
+``/usr/ccs/bin`` in your PATH to execute programs like ``ar`` and ``ranlib``,
but ``/usr/ccs/bin`` has the Sun/Oracle versions of ``make`` and ``tar``
which are unsuitable for building Sage. For more information on
building Sage on Solaris, see http://wiki.sagemath.org/solaris
@@ 173,8 +180,14 @@
does not raise an ``ImportError`` then it worked.
 Sage developers tend to use fairly recent versions of gcc, but
 Sage should compile with almost any gcc of at least version 4.0.1
+ Sage developers tend to use fairly recent versions of GCC, but Sage
+ should compile with any reasonable C compiler. This is because Sage
+ will build GCC first (if needed) and then use that newly built GCC to
+ compile Sage.
+
+ If you don't want this and want to try building Sage with a
+ different compiler, you need to set the environment variable
+ ``SAGE_INSTALL_GCC=no``.
If you are interested in working on support for commerical compilers
from `HP `_,
@@ 186,9 +199,6 @@
sagedevel Google group at
http://groups.google.com/group/sagedevel
 If you want to try building Sage with a compiler which is not GCC,
 you need to set the environment variable ``SAGE_INSTALL_GCC=no``.

After extracting the Sage tarball, the subdirectory ``spkg`` contains
the source distributions for everything on which Sage depends. We
emphasize that all of this software is included with Sage, so you
@@ 502,16 +512,16 @@
For example, put something similar to the following line in your
``.bashrc`` file::
 alias 'sage'='/home/username/sage4.8/sage'
+ alias sage=/home/username/sage5.0/sage
Having done so, quit your terminal emulator and restart it again.
Now typing ``sage`` within your terminal emulator should start
Sage.
#. 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
+#. 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
+ ``./sage testall optional long``; this will run examples that take
a long time, and those that depend on optional packages and
software, e.g., Mathematica or Magma. Some (optional) examples will
likely fail because they assume that a database is installed.
@@ 521,7 +531,7 @@
very old hardware building and testing Sage can take several days!
#. Optional: Install optional Sage packages and databases. Type
 ``sage optional`` to see a list or visit
+ ``sage optional`` to see a list or visit
http://www.sagemath.org/packages/optional/, and
``sage i `` to automatically download and install a
given package.
@@ 643,7 +653,7 @@
get very large and harder to search (and listing the contained
files is usually less valuable), we decided to turn this off
by default. This variable affects builds of Sage with ``make``
 (and ``sage upgrade``) as well as the manual installation of
+ (and ``sage upgrade``) as well as the manual installation of
individual spkgs with e.g. ``sage i``.
 :envvar:`SAGE_SPKG_INSTALL_DOCS`  Set this to "yes" to install
@@ 715,7 +725,7 @@
export SAGE_FAT_BINARY="yes"
make
 ./sage bdist x.y.zfat
+ ./sage bdist x.y.zfat
Variables to set if you're trying to build Sage with an unusual setup,
e.g., an unsupported machine or an unusual compiler:
@@ 739,10 +749,10 @@
:envvar:`SAGE_PORT` to something nonempty (and expect to run into
problems).
 :envvar:`SAGE_USE_OLD_GCC`  the Sage build process requires
 gcc with a version number of at least 4.0.1.
 If the most recent version of gcc on your system is the older 3.4.x series and you
 want to try building anyway, then set :envvar:`SAGE_USE_OLD_GCC` to
+ :envvar:`SAGE_USE_OLD_GCC`  the Sage build process requires gcc with
+ a version number of at least 4.0.1. If the most recent version of gcc
+ on your system is the older 3.4.x series and you want to build with
+ ``SAGE_INSTALL_GCC=no``, then set :envvar:`SAGE_USE_OLD_GCC` to
something nonempty. Expect the build to fail in this case.
Environment variables dealing with specific Sage packages:
@@ 973,7 +983,7 @@
#. Make sure that all files in the Sage tree are readable by all::
 chmod a+rX R /usr/local/sage4.8
+ chmod a+rX R /usr/local/sage5.0
#. Optionally, you can test Sage by running::
@@ 1003,10 +1013,6 @@
Special Notes


 (Found by Dorian Raymer) Sage will not build if you have only
 bison++. You should uninstall bison++ and install `bison `_.

 (Found by Peter Jipsen) If you get an error like
::
@@ 1024,4 +1030,4 @@
:ref:`installation in a multiuser environment
`.
 **This page was last updated in March 2012 (Sage 5.0)**
+ **This page was last updated in May 2012 (Sage 5.0)**