# HG changeset patch
# User JeanPierre Flori
# Date 1366235392 7200
# Node ID 544c04edbd335482e8d949d5edf6a1d1af60ae6c
# Parent 5d9b96c12c1046aedd49ec9132b22b70e82c9f52
#14465: Cleanup source.rst and include instructions for Cygwin
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
@@ 1,825 +1,1071 @@
.. comment:
 ****************************
 If you alter this document, please change the last line ("This page
 was last updated in ...")
 ****************************
+ ***************************************************************************
+ If you alter this document, please change the last line:
+ **This page was last updated in MONTH YEAR (Sage X.Y).**
+ ***************************************************************************
Install from Source Code
========================
More familiarity with computers may be required to build Sage from
the `source code `_. If you do have all the
prerequisite tools, the process should
be completely painless. It will take your computer a while to
compile Sage from the source code, although you don't have to watch. Compiling
Sage from the source code 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.
Also, some parts of Sage will be optimised for your particular computer,
so will run faster than a binary that you have downloaded.
+the `source code `_.
+If you do have all the prerequisite tools, the process should be completely
+painless.
+It will take your computer a while to compile Sage from the source code,
+although you don't have to watch.
+Building Sage from the source code 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.
+Finally, some parts of Sage will be optimised for your particular computer,
+so will run faster than a binary that you have downloaded.
Sage is supported on a number of
`Linux `_
, Mac `OS X `_ , Sun/Oracle `Solaris `_ and
`OpenSolaris `_
releases, but Sage is not supported on all versions of Linux, OS X,
Solaris or OpenSolaris. Depending on the `operating system `_, Sage works
with `x86 `_, `x64 `_, `PowerPC `_ or `SPARC `_ processors. There is no native version of Sage which
installs on `Microsoft Windows `_, although Sage can be used on Windows
with the aid of a `virtual machine `_ .
Go to http://www.sagemath.org/downloadwindows.html
to download a version of Sage for Windows. See http://wiki.sagemath.org/SupportedPlatforms
for the list of platforms on which Sage is supported and the level of support
for these systems. You will also find details about `ports `_
to other operating systems or processors which may be taking place.
+Supported platforms
+
Assumptions: You have a computer with at least 3 GB of free
disk space running one of the supported version of an
operating system listed at
+Sage is supported on a number of `Linux `_,
+Mac `OS X `_ ,
+Sun/Oracle `Solaris `_
+and `OpenSolaris `_ releases,
+but Sage is not supported on all versions of Linux, OS X, Solaris or
+OpenSolaris.
+Depending on the `operating system `_,
+Sage works with `x86 `_,
+`x86_64 `_,
+`PowerPC `_
+or `SPARC `_ processors.
+There is no native version of Sage which installs on
+`Microsoft Windows `_,
+although Sage can be used on Windows with the aid of a
+`virtual machine `_
+or the `Cygwin `_ Linux API layer.
+Go to http://www.sagemath.org/downloadwindows.html to download a binary
+version of Sage for Windows.
+
+See http://wiki.sagemath.org/SupportedPlatforms for the full list of platforms
+on which Sage is supported and the level of support for these systems.
+You will also find details about
+`ports `_
+to other operating systems or processors which may be taking place.
+
+
+Prerequisites
+
+
+General requirements
+~~~~~~~~~~~~~~~~~~~~
+
+Your computer comes with at least 3 GB of free disk space running one of the
+supported versions of an operating system 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 `_).
 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
+In addition to standard `POSIX `_ utilities
+and a `bash `_compatible shell,
+the following standard commandline development tools must be installed on your
+computer:
Recommended but not strictly required:

 **latex**: highly recommended
 **dvipng**
 **ImageMagick**
 **ffmpeg**
 **sshkeygen**: needed to run the notebook in secure mode
+ 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.
+ **ranlib**.
+ **tar**: GNU tar version 1.17 or later, or BSD tar.
Sage also needs a C++ compiler and a Fortran compiler.
However, it contains a `GNU Compiler Collection (GCC) `_
package, so C, C++ and Fortran compilers will be built if needed
(you can also use the environment variable :envvar:`SAGE_INSTALL_GCC` to
control whether or not to install GCC).
You always need some C compiler to build GCC and its prerequisites itself.
+package, so that C, C++ and Fortran compilers will be built if needed.
+(You can also use the environment variable :envvar:`SAGE_INSTALL_GCC` to
+control whether or not to install GCC, see :ref:`section_compilers`.)
+Nonetheless, you always need some C compiler to build GCC and its
+prerequisites.
.. note::
+Although some of Sage is written in `Python `_, you do
+not need Python preinstalled on your computer, since the Sage installation
+includes virtually everything you need.
 Optional: Read this if you are intending to run a Sage notebook server
 for multiple users. For security (i.e., to run
 ``notebook(secure=True)``) you may wish users to access the server using
 the HTTPS protocol. You also may want to use OpenID for user
 authentication. The first of these requires you to install pyOpenSSL,
 and they both require OpenSSL. If you have OpenSSL and the OpenSSL
 development headers installed on your system, you can install
 pyOpenSSL by building Sage and then typing ::
+After extracting the Sage tarball, the subdirectory :file:`spkg` contains the
+source distributions for everything on which Sage depends.
+We emphasize that all of this software is included with Sage, so you do not
+have to worry about trying to download and install any one of these packages
+(such as Python, for example) yourself.
 ./sage i pyopenssl
+When the Sage installation program is run,
+it will check that you have each of the abovelisted prerequisites,
+and inform you of any that are missing, or have unsuitable versions.
 Note that this command requires internet access. Alternatively, ``make
 ssl`` builds Sage and installs pyOpenSSL. If you are missing either
 OpenSSL or OpenSSL's development headers, you can install a local copy
 of both into your Sage installation first. Ideally, this should be
 done before installing Sage; otherwise, you should at least rebuild
 Sage's Python, and ideally any part of Sage relying on it. So the
 procedure is as follows (again, with a computer connected to the
 internet). Starting from a fresh Sage tarball::
+Systemspecific requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ./sage i patch openssl # install patch and openssl
 make ssl
+On recent Debian or Ubuntu systems, the **dpkgdev** package is needed for
+`multiarch `_ support.
 Alternatively, if you've already built Sage::
+On Cygwin, the **lapack** and **liblapackdevel** packages are required to
+provide ATLAS support as the ATLAS spkg is not built by default.
 ./sage i openssl
 ./sage f python # rebuild Python
 SAGE_UPGRADING=yes make ssl
+Installing prerequisites
+~~~~~~~~~~~~~~~~~~~~~~~~
 The third line will rebuild all parts of Sage that depend on Python;
 this can take a while.
+To check if you have the above prerequisites installed, for example ``perl``,
+type::
To check if you have ``perl`` installed, for example, type
+ command v perl
+
+or::
+
+ which perl
+
+on the command line. If it gives an error (or returns nothing), then
+either ``perl`` is not installed, or it is installed but not in your
+`PATH `_.
+
+On Linux systems (e.g., Ubuntu, Redhat, etc), ``ranlib`` is in the
+`binutils `_ package.
+The other programs are usually located in packages with their respective names.
+Assuming you have sufficient privileges, you can install the ``binutils`` and
+other necessary components.
+If you do not have the privileges to do this, ask your system administrator to
+do this, or build the components from source code.
+The method of installing additional software varies from distribution to
+distribution, but on a `Debian `_ based system (e.g.
+`Ubuntu `_ or `Mint `_),
+you would use
+`aptget `_::
+
+ sudo aptget install binutils gcc make m4 perl tar
+
+to install all general requirements (this was tested on Ubuntu 12.04.2).
+On other Linux systems, you might use
+`rpm `_,
+`yum `_,
+or other package managers.
+
+On OS X systems, you need a recent version of
+`Command Line Tools `_.
+It provides all the above requirements.
+You can download it for free at
+http://developer.apple.com/downloads/index.action?=command%20line%20tools
+provided you registered for a free Apple Developer account at
+http://developer.apple.com/register/.
+Alternatively, if you have already installed
+`Xcode `_
+(which at the time of writing is freely available in the Mac App Store,
+or through http://developer.apple.com/downloads/ provided you registered for an
+Apple Developer account),
+you can open Xcode's "Downloads" preference pane and install the command line
+tools from there.
+
+On Solaris, you would use ``pkgadd`` and on OpenSolaris ``ipf`` to install
+the necessary software.
+
+On Cygwin, you would use the ``setup.exe`` program.
+As on Linux systems ``ranlib`` is provided by the ``binutils`` package.
+As far as compilers are concerned, you should either install the ``gcc4core``
+package alone, or install matching versions of the ``gcc4core``, ``gcc4g++``,
+and ``gcc4gfortran`` packages to avoid the build of Sage's own GCC.
+
+On other systems, check the documentation for your particular operating system.
+
+Specific notes for ``make`` and ``tar``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On OS X, the BSD ``tar`` supplied will build Sage, so there is no need to
+install the GNU ``tar``.
+
+On Solaris or OpenSolaris, the Sun/Oracle versions of ``make`` and ``tar`` are
+unsuitable for building Sage.
+Therefore, you must have the GNU versions of ``make`` and ``tar`` installed and
+they must be the first ``make`` and ``tar`` in your :envvar:`PATH`.
+
+On Solaris 10, a version of GNU ``make`` may be found at :file:`/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``; a version of GNU ``tar`` may be found at
+:file:`/usr/sfw/bin/gtar`,
+but it will need to be copied somewhere else and renamed to ``tar``.
+It is recommended to create a directory :file:`$HOME/binsforsage` and to put
+the GNU versions of ``tar`` and ``make`` in that directory.
+Then ensure that :file:`$HOME/binsforsage` is first in your :envvar:`PATH`.
+That's because Sage also needs :file:`/usr/ccs/bin` in your :envvar:`PATH` to
+execute programs like ``ar`` and ``ranlib``, but :file:`/usr/ccs/bin` has the
+Sun/Oracle versions of ``make`` and ``tar`` in it.
+
+If you attempt to build Sage on AIX or HPUX, you will need to install both
+GNU ``make`` and GNU ``tar``.
+
+.. _section_compilers:
+
+Using alternative compilers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 :envvar:`SAGE_INSTALL_GCC` to ``no``.
+
+If you are interested in working on support for commerical compilers from
+`HP `_,
+`IBM `_,
+`Intel `_,
+`Sun/Oracle `_,
+etc,
+or the opensource `Clang `_,
+please email the sagedevel mailing list, also known as the sagedevel Google
+group at http://groups.google.com/group/sagedevel.
+
+
+Additional software
+
+
+Recommended programs
+~~~~~~~~~~~~~~~~~~~~
+
+The following programs are recommended.
+They are not strictly required at build time or at run time,
+but provide additional capablities:
+
+ **dvipng**.
+ **ffmpeg**.
+ **ImageMagick**.
+ **latex**: highly recommended.
+
+It is highly recommended that you have `Latex `_
+installed, but it is not required.
+
+On Linux systems, it is usually provided by packages derived from
+`TeX Live `_ and can be installed using::
+
+ sudo aptget install texlive
+
+or similar commands.
+
+On other systems it might be necessary to install TeX Live from source code,
+which is quite easy, though a rather timeconsuming process.
+
+If you don't have either ImageMagick or ffmpeg, you won't be able to
+view animations.
+ffmpeg can produce animations in more different formats than ImageMagick,
+and seems to be faster than ImageMagick when creating animated GIFs.
+Either ImageMagick or dvipng is used for displaying some LaTeX output in the
+Sage notebook.
+
+Notebook additional features
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the Sage notebook uses the
+`HTTP `_
+protocol when you type the command ``notebook()``.
+To run the notebook in secure mode by typing ``notebook(secure=True)`` which
+uses the `HTTPS `_ protocol,
+or to use `OpenID `_ authentication,
+you need to follow specific installation steps described in
+:ref:`section_notebook_ssl`.
+
+Although all necessary components are provided through Sage optional packages,
+i.e. you can install a local version of `OpenSSL `_
+by using Sage's **openssl** spkg and running ``sage i openssl`` as suggested
+in :ref:`section_notebook_ssl` (this requires an Internet connection),
+you might prefer to install OpenSSL and the OpenSSL development headers
+globally on your system.
+
+On Linux systems, those are usually provided by the **libssl** and
+**libssldev** packages and can be installed using::
+
+ sudo aptget install libssl libssldev
+
+or similar commands.
+
+Finally, if you intend to distribute the notebook load onto several Sage
+servers, you will surely want to setup an
+`SSH `_ server and generate SSH keys.
+This can be achieved using `OpenSSH `_.
+
+On Linux systems, the OpenSSH server, client and utilities are usually provided
+by the **opensshserver** and **opensshclient** packages and can be installed
+using::
+
+ sudo aptget install opensshserver opensshclient
+
+or similar commands.
+
+Tcl/Tk
+~~~~~~
+
+If you want to use `Tcl/Tk `_ libraries in Sage,
+you need to install the Tcl/Tk and its development headers before building
+Sage.
+Sage's Python will then automatically recognize your system's install of
+Tcl/Tk.
+
+On Linux systems, these are usually provided by the **tk** and **tkdev**
+(or **tkdevel**) packages which can be installed using::
+
+ sudo aptget install tk tkdev
+
+or similar commands.
+
+If you installed Sage first, all is not lost.
+You just need to rebuild Sage's Python, , and ideally any part of Sage relying
+on it::
+
+ sage f python # rebuild Python
+ SAGE_UPGRADING=yes make # rebuild components of Sage depending on Python
+
+after installing the Tcl/Tk development libraries as above.
+
+If
+
+.. skip
::
 command v perl
+ sage: import _tkinter
+ sage: import Tkinter
+does not raise an ``ImportError``, then it worked.
on the command line. If it gives an error (or returns nothing), then
either ``perl`` is not installed, or it is installed but not in your
`PATH `_.
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
``notebook(secure=True)`` instead of ``notebook()``. Unless ``notebook(secure=True)``
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
formats than ImageMagick, and seems to be faster than ImageMagick when
creating animated GIFs. Either ImageMagick or dvipng is used for
displaying some LaTeX output in the Sage notebook.
+Stepbystep installation procedure
+
In OS X, make sure you have a recent version of `Xcode `_.
See http://wiki.sagemath.org/SupportedPlatforms to find out what
version(s) of Xcode are supported. You can get the latest Xcode
from http://developer.apple.com/xcode/, but may have to pay a small
fee in order to download this.
+General procedure
+~~~~~~~~~~~~~~~~~
On Linux systems (e.g., Ubuntu, Redhat etc), ``ranlib`` is in the
`Binutils `_ package.
Assuming you have sufficient privileges,
you can install the ``binutils`` and other necessary components. If you
do not have the privileges to do this, ask your system
administrator to do this, or build the components from source
code. The method of installing additional software varies from
distribution to distribution
but on a `Debian `_ based system (e.g. `Ubuntu `_ or `Mint `_), you would use:
+Installation from source is (potentially) very easy, because the distribution
+contains (essentially) everything on which Sage depends.
::

 sudo aptget install buildessential

(this was tested on Ubuntu 9.04).

On other Linux systems you might use `rpm `_,
`yum `_ or other package manager. On
Solaris you would use ``pkgadd`` and on OpenSolaris use ``ipf``. Check
the documentation for your particular operating system.

The LaTeX package and a PDF previewer are optional but they can be
installed using

::

 sudo aptget install texlive xpdf evince xdvi

On other systems it might be necessary to install TeX Live from source code,
which is quite easy, though a rather timeconsuming process.

On Solaris or OpenSolaris, you must have the GNU version of ``make``
installed and it must be the first
``make`` in your PATH. On Solaris 10, 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 somewhere
else and renamed to ``tar``). If you attempt to build Sage on AIX or HPUX,
you will need to install both GNU tar and GNU make. On OS X, the BSD tar
suppied will build Sage, so there is no need to install GNU 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 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

Although some of Sage is written in `Python `_, you do not need Python
preinstalled on your computer, since the Sage installation
includes virtually everything you need. When the Sage installation program is run,
it will check that you have each of the abovelisted prerequisites,
and inform you of any that are missing, or have unsuitable verisons.

 If you want to use `Tcl/Tk `_ libraries in Sage,
 do the following before compiling Sage.
 Sage's Python will automatically recognize your system's
 install of Tcl/Tk if it exists. You need to install the
 Tcl/Tk development libraries though, not just the Tck/Tk base.

 On `Ubuntu `_, this is the command::

 sudo aptget install tk8.5dev # or the latest version available

 Now you can install Sage, If you forgot
 and installed Sage first anyway, all is not lost.
 Just issue the command::

 sage f python2.6.4.p9 # or the latest version available

 after installing the Tcl/Tk development libraries as above.
 If

 .. skip

 ::

 sage: import _tkinter
 sage: import Tkinter

 does not raise an ``ImportError`` then it worked.

 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 `_,
 `IBM `_,
 `Intel `_,
 `Sun/Oracle `_ etc,
 or the opensource `Clang `_,
 please email the sagedevel mailing list, otherwise known as the
 sagedevel Google group at
 http://groups.google.com/group/sagedevel

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
do not have to worry about trying to download and install any one
of these packages (such as GAP, for example) yourself.

Steps to Install from Source


Installation from source is (potentially) very easy, because the
distribution contains (essentially) everything on which Sage
depends.

Make sure there are **no spaces** in the path name for the directory
in which you build: several of Sage's components will not build if
there are spaces in the path. Running Sage from a directory with
spaces in its name will also fail.
+Make sure there are **no spaces** in the path name for the directory in which
+you build:
+several of Sage's components will not build if there are spaces in the path.
+Running Sage from a directory with spaces in its name will also fail.
#. Go to http://www.sagemath.org/downloadsource.html, select a mirror,
 and download the file ``sagex.y.z.tar``.
+ and download the file :file:`sagex.y.z.tar`.
 This tarfile contains the source code for Sage and the source for
 all programs on which Sage depends. Download it into a subdirectory
 of your home directory into which you want to install Sage. Note
 that this file is not compressed; it's just a plain tarball (which
+ This tarfile contains the source code for Sage and the source for all
+ programs on which Sage depends.
+ Download it into a subdirectory of your :envvar:`HOME` directory.
+ Note that this file is not compressed; it's just a plain tarball (which
happens to be full of compressed files).
#. Extract:
+#. Extract the tarfile::
 ::
+ tar xvf sagex.y.z.tar
 tar xvf sagex.y.z.tar
+ This creates a directory :file:`sagex.y.z`.
#. This creates a directory ``sagex.y.z``.
+#. Change into that directory::
#. Change into that directory
+ cd sagex.y.z
 ::
+ This is Sage's home directory.
+ It is also referred to as :envvar:`SAGE_ROOT` or the top level Sage
+ directory.
 cd sagex.y.z
+#. Optional, but highly recommended:
+ Read the :file:`README.txt` file there.
 This is Sage's home directory. It is also referred to as
 ``SAGE_ROOT`` or the top level Sage directory.
+#. On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to build a
+ 64bit version of Sage, assuming your computer and operating system are
+ 64bit, type::
#. Optional (but highly recommended): Read the ``README.txt`` file
 there.
+ export SAGE64=yes
#. On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to
 build a 64bit version of Sage, then assuming your computer and
 operating system are 64bit, type
+ It should be noted that as of April 2011, 64bit builds of Sage on both
+ Solaris 10 and OpenSolaris are not very stable, so you are advised not to
+ set :envvar:`SAGE64` to ``yes``.
+ This will then create stable 32bit versions of Sage.
+ See http://wiki.sagemath.org/solaris for the latest information.
 ::
+#. Start the build process::
 SAGE64=yes
 export SAGE64

 It should be noted that at the time of writing (April 2011), 64bit
 builds of Sage on both Solaris 10 and OpenSolaris are not very stable,
 so you are advised not to set ``SAGE64`` to ``yes``. This will then
 create stable 32bit versions of Sage.
 See http://wiki.sagemath.org/SupportedPlatforms and
 http://wiki.sagemath.org/solaris for the latest information, as
 work is ongoing to resolve the 64bit Solaris & OpenSolaris problems.
+ make
#. Type
+ or if your system is multithreaded and you want to use several threads to
+ build Sage::
 ::
+ MAKE='make jNUM' make
 make
+ to tell the ``make`` program to run ``NUM`` jobs in parallel when building
+ Sage.
 This compiles Sage and all dependencies. Note that you do not need
 to be logged in as root, since no files are changed outside of the
 ``sagex.y.z`` directory (with one exception  the ``.ipythonrc``
 directory is created in your ``HOME`` directory if it doesn't exist).
+ This compiles Sage and all its dependencies.
+ Note that you do not need to be logged in as root, since no files are
+ changed outside of the :file:`sagex.y.z` directory.
In fact, **it is inadvisable to build Sage as root**, as the root account
 should only be used when absolutely necessary, as mistyped commands
 can have serious consequences if you are logged in as root. There has been a bug
 `reported `_ in Sage
 which would have overwritten a system file had the user been logged in
 as root.
+ should only be used when absolutely necessary and mistyped commands can have
+ serious consequences if you are logged in as root.
+ There has been a bug reported (see :trac:`9551`) in Sage which would have
+ overwritten a system file had the user been logged in as root.
 Typing ``make`` does the usual steps for each of the packages, but puts
 all the results in the local build tree. Depending on the architecture of your system (e.g.,
 Celeron, Pentium Mobile, Pentium 4, SPARC, etc.), it can take over three hours
 to build Sage from source. On slower older hardware it can take over
 a day to build Sage. If the build is successful, you will not see
 the word ERROR in the last 34 lines of output.
+ Typing ``make`` performs the usual steps for each Sage's dependency,
+ but installs all the resulting files into the local build tree.
+ Depending on the age and the architecture of your system, it can take from
+ a few tens of minutes to several hours to build Sage from source.
+ On really slow hardware, it can even take a few days to build Sage.
+ If the build is successful, you will not see the word ``ERROR`` in the last
+ 34 lines of output.
Each component of Sage has its own build log, saved in
 ``SAGE_ROOT/logs/pkgs``. In particular,
 if the build of Sage fails, then you can type the following from the directory
 where you typed ``make``.

 ::
+ :file:`SAGE_ROOT/logs/pkgs`.
+ In particular, if the build of Sage fails, then you can type the following
+ from the directory where you typed ``make``::
grep li "^Error installing" logs/pkgs/*

 Then paste the contents of the log file(s) with errors to the Sage
 support newsgroup http://groups.google.com/group/sagesupport
 If the log files are very large (and many are), then don't paste
 the whole file, but make sure to include any error messages.
 The directory where you built Sage is NOT hardcoded. You should
 be able to safely move or rename that directory. (It's a bug if
 this is not the case)
+ Then paste the contents of the log file(s) with errors to the Sage support
+ newsgroup at http://groups.google.com/group/sagesupport.
+ If the log files are very large (and many are), then don't paste the whole
+ file, but make sure to include any error messages.
+ It would also be helpful to include the type of operating system
+ (Linux, OS X, Solaris, OpenSolaris, Cygwin, or any other system),
+ the version and release date of that operating system and the version of
+ the copy of Sage you are using.
+ (There are no formal requirements for bug reports  just send them;
+ we appreciate everything.)
 See :ref:`section_make` for some options for the ``make`` command.
+ The directory where you built Sage is **NOT** hardcoded.
+ You should be able to safely move or rename that directory.
+ (It's a bug if this is not the case.)
#. To start Sage, change into the Sage home directory and type:
+ See :ref:`section_make` for some targets for the ``make`` command,
+ :ref:`section_envvar` for additional informatio on useful environment
+ variables used by Sage,
+ and :ref:`section_notebook_ssl` for additional instruction on how to build
+ the notebook with SSL support.
 ::
+#. To start Sage, you can now simply type from Sage's home directory::
 ./sage
+ ./sage
 You should see the Sage prompt, which will look something like this
 (starting the first time should take well under a minute, but can
 take several minutes if the file system is slow or busy. Since Sage
 opens a lot of files, it is preferable to install Sage on a fast file
 system if this is possible.):

 ::
+ You should see the Sage prompt, which will look something like this::
$ sage

  Sage Version 4.7, Release Date: 20110523 
  Type notebook() for the GUI, and license() for information. 
+  Sage Version 5.8, Release Date: 20130315 
+  Type "notebook()" for the browserbased notebook interface. 
+  Type "help()" for help. 

sage:
+ Note that Sage should take well under a minute when it starts for the first
+ time, but can take several minutes if the file system is slow or busy.
+ Since Sage opens a lot of files, it is preferable to install Sage on a fast
+ filesystem if possible.
+
Just starting successfully tests that many of the components built
 correctly. If the above is not displayed (e.g., if you get a
 massive traceback), please report the problem, e.g., to
 http://groups.google.com/group/sagesupport .
 It would also be helpful to
 include the type of operating system (Linux, OS X, Solaris or OpenSolaris),
 the version and date of that operating system and the version
 number of the copy of Sage you are using. (There are no
 formal requirements for bug reports  just send them; we appreciate
 everything.)
+ correctly.
+ Note that this should have been already automatically tested during the
+ build process.
+ If the above is not displayed (e.g., if you get a massive traceback), please
+ report the problem, e.g., at http://groups.google.com/group/sagesupport.
 After Sage starts, try a command:

 ::
+ After Sage has started, try a simple command::
sage: 2 + 2
4
 Try something more complicated, which uses the PARI C library:
+ Try something more complicated, which uses the
+ `FLINT `_ C library::
 ::

 sage: factor(2005)
+ sage: GF(7)(x^7)
5 * 401
 Try something simple that uses the Gap, Singular, Maxima and
 PARI/GP interfaces:

 ::
+ Try something simple that uses the `GAP `_,
+ `Maxima `_,
+ `PARI/GP `_ and
+ `Singular `_ interfaces::
sage: gap('2+2')
4
+ sage: maxima('2+2')
+ 4
+ sage: pari('2+2')
+ 4
sage: gp('2+2')
4
 sage: maxima('2+2')
 4
sage: singular('2+2')
4
 sage: pari('2+2')
 4
 (For those familiar with GAP: Sage automatically builds a GAP
 "workspace" during installation, so the response time from this GAP
 command is relatively fast. For those familiar with GP/PARI, the
 ``gp`` command creates an object in the GP interpreter, and the
 ``pari`` command creates an object directly in the PARI Clibrary.)
+ (For those familiar with GAP: Sage automatically builds a GAP "workspace"
+ during installation, so the response time from this GAP command is
+ relatively fast.
+ For those familiar with GP/PARI, the ``pari`` command creates an object
+ directly in the PARI C library, and the ``gp`` command creates an object in
+ the GP interpreter.)
 Try running Gap, Singular or GP from Sage:
+ Try running GAP, GP, Maxima, or Singular, from Sage:
.. skip
::
sage: gap_console()
 GAP4, Version: 4.4.12 of 17Dec2008, i386pcsolaris2.11gcc
+ ┌───────┐ GAP, Version 4.5.7 of 14Dec2012 (free software, GPL)
+ │ GAP │ http://www.gapsystem.org
+ └───────┘ Architecture: x86_64unknownlinuxgnugccdefault64
+ Libs used: gmp, readline
+ Loading the library and packages ...
+ Packages: GAPDoc 1.5.1
+ Try '?help' for help. See also '?copyright' and '?authors'
gap> 2+2;
4
 [ctrld]
+ gap>
+ [CTRL+D]
.. skip
::
sage: gp_console()
 ...
 [ctrld]
+ Reading GPRC: .../sage5.8/local/etc/gprc.expect ...Done.
+
+ GP/PARI CALCULATOR Version 2.5.3 (development git6fd07f9)
+ amd64 running linux (x8664/GMP5.0.2 kernel) 64bit version
+ compiled: Apr 10 2013, gcc4.6.3 (Ubuntu/Linaro 4.6.31ubuntu5)
+ (readline v6.2 enabled, extended help enabled)
+
+ Copyright (C) 20002011 The PARI Group
+
+ PARI/GP is free software, covered by the GNU General Public License, and comes
+ WITHOUT ANY WARRANTY WHATSOEVER.
+
+ Type ? for help, \q to quit.
+ Type ?12 for how to get moral (and possibly technical) support.
+
+ parisize = 8000000, primelimit = 500509
+ ? 2+2
+ %1 = 4
+ ?
+ [CTRL+D]
+
+ .. skip
+
+ ::
+
+ sage: maxima_console()
+ ;;; Loading #P".../sage5.8/local/lib/ecl/sbbsdsockets.fas"
+ ;;; Loading #P".../sage5.8/local/lib/ecl/sockets.fas"
+ ;;; Loading #P".../sage5.8/local/lib/ecl/defsystem.fas"
+ ;;; Loading #P".../sage5.8/local/lib/ecl/cmp.fas"
+ Maxima 5.29.1 http://maxima.sourceforge.net
+ using Lisp ECL 12.12.1
+ Distributed under the GNU Public License. See the file COPYING.
+ Dedicated to the memory of William Schelter.
+ The function bug_report() provides bug reporting information.
+ (%i1) 2+2;
+ (%o1) 4
+ (%i2)
+ [CTRL+D]
.. skip
::
sage: singular_console()
 SINGULAR / Development
 A Computer Algebra System for Polynomial Computations / version 311
 0<
 by: G.M. Greuel, G. Pfister, H. Schoenemann \ Feb 2010
 FB Mathematik der Universitaet, D67653 Kaiserslautern \
 [ctrld]
 > Auf Wiedersehen.
 sage:
+ SINGULAR / Development
+ A Computer Algebra System for Polynomial Computations / version 315
+ 0<
+ by: W. Decker, G.M. Greuel, G. Pfister, H. Schoenemann \ Jul 2012
+ FB Mathematik der Universitaet, D67653 Kaiserslautern \
+ > 2+2;
+ 4
+ >
+ [CTRL+D]
#. Optional: Check the interfaces to any other software that
 you have available. Note that each interface calls its
 corresponding program by a particular name:
 `Mathematica `_ is invoked
 by calling ``math``, `Maple `_ by calling ``maple``, etc. The
 easiest way to change this name or perform other customizations is
 to create a redirection script in ``$SAGE_ROOT/local/bin``. Sage
 inserts this directory at the front of your PATH, so your script
 may need to use an absolute path to avoid calling itself; also,
 your script should use ``$*`` to pass along all of its arguments.
 For example, a ``maple`` script might look like:

 ::
+#. Optional:
+ Check the interfaces to any other software that you have available.
+ Note that each interface calls its corresponding program by a particular
+ name: `Mathematica `_ is invoked by
+ calling ``math``, `Maple `_ by calling ``maple``,
+ etc.
+ The easiest way to change this name or perform other customizations is
+ to create a redirection script in :file:`$SAGE_ROOT/local/bin`.
+ Sage inserts this directory at the front of your :envvar:`PATH`, so your
+ script may need to use an absolute path to avoid calling itself; also, your
+ script should use ``$*`` to pass along all of its arguments.
+ For example, a ``maple`` script might look like::
#!/bin/sh
/etc/maple10.2/maple.tty $*
#. Optional: Different possibilities to make using Sage a little
 easier:
+#. Optional:
+ There are different possibilities to make using Sage a little easier:
  Make a symbolic link from ``/usr/local/bin/sage`` (or another
 directory in your :envvar:`PATH`) to ``$SAGE_ROOT/sage``::
+  Make a symbolic link from :file:`/usr/local/bin/sage` (or another
+ directory in your :envvar:`PATH`) to :file:`$SAGE_ROOT/sage`::
ln s /path/to/sagex.y.z/sage /usr/local/bin/sage
 Now simply typing ``sage`` should be sufficient to run Sage.

  Copy ``$SAGE_ROOT/sage`` to a location in your ``PATH``. If you do
 this, make sure you edit the line ``#SAGE_ROOT=/path/to/sageversion``
 at the top of the copied ``sage`` script. It is best to edit only
 the copy, not the original.

  For KDE users, create a bash script {sage} containing the lines

 ::

 #!/bin/bash
 konsole T "sage" e /sage

 which you make executable (``chmod a+x sage``) and put it somewhere in
 your path. (Note that you have to change ``$SAGE_ROOT`` above!) You
 can also make a KDE desktop icon with this as the command (under
 the Application tab of the Properties of the icon, which you get my
 right clicking the mouse on the icon).

  On Linux and OS X systems, you can make an alias to ``$SAGE_ROOT/sage``.
 For example, put something similar to the following line in your
 ``.bashrc`` file::

 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
+ Now simply typing ``sage`` from any directory should be sufficient to run
Sage.
#. Optional, but highly recommended: Test the install by typing ``./sage testall``.
+  Copy :file:`$SAGE_ROOT/sage` to a location in your :envvar:`PATH`.
+ If you do this, make sure you edit the line::
+
+ #SAGE_ROOT=/path/to/sageversion
+
+ at the beginning of the copied ``sage`` script according to the direction
+ given there to something like::
+
+ SAGE_ROOT=
+
+ (note that you have to change ```` above!).
+ It is best to edit only the copy, not the original.
+
+  For `KDE `_ users, create a bash script called
+ ``sage`` containing the lines
+ (note that you have to change ```` below!)::
+
+ #!/bin/bash
+
+ konsole T "sage" e /sage
+
+ make it executable::
+
+ chmod a+x sage
+
+ and put it somewhere in your :envvar:`PATH`.
+
+ You can also make a KDE desktop icon with this line as the command
+ (under the Application tab of the Properties of the icon, which you get my
+ right clicking the mouse on the icon).
+
+  On Linux and OS X systems, you can make an alias to
+ :file:`$SAGE_ROOT/sage`.
+ For example, put something similar to the following line in your
+ :file:`.bashrc` file::
+
+ alias sage=/sage
+
+ (Note that you have to change ```` above!)
+ Having done so, quit your terminal emulator and restart it.
+ 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
 exactly as claimed. To test all examples, use
 ``./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.
 Alternatively, from within ``$SAGE_ROOT``, you can type
 ``make test`` to run all the standard test code. This can take
 from 25 minutes to several hours, depending on your hardware. On
 very old hardware building and testing Sage can take several days!
+ exactly as claimed.
+ To test all examples, use ``./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 therefore likely fail.
#. Optional: Install optional Sage packages and databases. Type
 ``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.
+ Alternatively, from within :file:`$SAGE_ROOT`, you can type ``make test``
+ (respectively ``make ptest``) to run all the standard test code serially
+ (respectively in parallel).
#. Optional: Run the ``install_scripts`` command from within Sage to create
 gp, singular, gap, etc., scripts in your ``PATH``. Type
 ``install_scripts?`` in Sage for details.
+ Testing the Sage library can take from half an hour to several hours,
+ depending on your hardware.
+ On slow hardware building and testing Sage can even take several days!
+#. Optional:
+ Install optional Sage packages and databases.
+ Type ``sage optional`` to see a list of them (this requires an Internet
+ connection), or visit http://www.sagemath.org/packages/optional/.
+ Then type ``sage i `` to automatically download and install
+ a given package.
Have fun! Discover some amazing conjectures!
+#. Optional:
+ Run the ``install_scripts`` command from within Sage to create GAP, GP,
+ Maxima, Singular, etc., scripts in your :envvar:`PATH`.
+ Type ``install_scripts?`` in Sage for details.
+
+#. Have fun! Discover some amazing conjectures!
+
+.. _section_notebook_ssl:
+
+Building the notebook with SSL support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Read this section if you are intending to run a Sage notebook server for
+multiple users.
+
+For security, you may wish users to access the server using the HTTPS protocol
+(i.e., to run ``notebook(secure=True)``).
+You also may want to use OpenID for user authentication.
+The first of these requires you to install
+`pyOpenSSL `_,
+and they both require OpenSSL.
+
+If you have OpenSSL and the OpenSSL development headers installed on your
+system, you can install pyOpenSSL by building Sage and then typing::
+
+ ./sage i pyopenssl
+
+Alternatively, ``make ssl`` builds Sage and installs pyOpenSSL at once.
+Note that these commands require Internet access.
+
+If you are missing either OpenSSL or OpenSSL's development headers,
+you can install a local copy of both into your Sage installation first.
+Ideally, this should be done before installing Sage; otherwise, you should at
+least rebuild Sage's Python, and ideally any part of Sage relying on it.
+The procedure is as follows (again, with a computer connected to the
+Internet).
+Starting from a fresh Sage tarball::
+
+ ./sage i openssl
+ make ssl
+
+And if you've already built Sage::
+
+ ./sage i openssl
+ ./sage f python
+ SAGE_UPGRADING=yes make ssl
+
+The third line will rebuild all parts of Sage that depend on Python;
+this can take a while.
+
+Rebasing issues on Cygwin
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Building on Cygwin will occasionally require "rebasing" ``dll`` files.
+Sage provides some scripts, located in :file:`$SAGE_LOCAL/bin`, to do so:
+
+ ``sagerebaseall.sh``, a shell script which calls Cygwin's ``rebaseall``
+ program.
+ It must be run within a ``dash`` shell from the :envvar:`SAGE_ROOT` directory
+ after all other Cygwin processes have been shut down and needs writeaccess
+ to the systemwide rebase database located at :file:`/etc/rebase.db.i386`,
+ which usually means administrator privileges.
+ It updates the systemwide database and adds Sage dlls to it, so that
+ subsequent calls to ``rebaseall`` will take them into account.
+ ``sagerebase.sh``, a shell script which calls Cygwin's ``rebase`` program
+ together with the ``O/oblivious`` option.
+ It must be run within a shell from :envvar:`SAGE_ROOT` directory.
+ Contrary to the ``sagerebaseall.sh`` script, it neither updates the
+ systemwide database, nor adds Sage dlls to it.
+ Therefore, subsequent calls to ``rebaseall`` will not take them into account.
+ ``sagerebaseall.bat`` (respectively ``sagerebase.bat``), an MSDOS batch
+ file which calls the ``sagerebaseall.sh`` (respectively ``sagerebase.sh``)
+ script.
+ It must be run from a Windows command prompt, after adjusting
+ :envvar:`SAGE_ROOT` to the Windows location of Sage's home directory, and, if
+ Cygwin is installed in a nonstandard location, adjusting
+ :envvar:`CYGWIN_ROOT` as well.
+
+Some systems may encounter this problem frequently enough to make building or
+testing difficult.
+If executing the above scripts or directly calling ``rebaseall`` does not solve
+rebasing issues, deleting the systemwide database and then regenerating it
+from scratch, e.g., by executing ``sagerebaseall.sh``, might help.
+
+Finally, on Cygwin, one should also avoid the following:
+
+ building in home directories of Windows domain users;
+ building in paths with capital letters.
+
.. _section_make:
Make targets

To build Sage from scratch, you would typically give the command
``make`` to build Sage and its HTML documentation. The ``make`` command
is pretty smart, so if your build of Sage is interrupted, then running
``make`` again should cause it to pick up where it left off. The
``make`` command can also be given options, which control what is built
and how it is built.
+To build Sage from scratch, you would typically execute ``make`` in Sage's home
+directory to build Sage and its `HTML `_
+documentation.
+The ``make`` command is pretty smart, so if your build of Sage is interrupted,
+then running ``make`` again should cause it to pick up where it left off.
+The ``make`` command can also be given options, which control what is built and
+how it is built:
 ``make build`` builds Sage: it compiles all of the Sage packages. It
 does not build the documentation.
+ ``make build`` builds Sage: it compiles all of the Sage packages.
+ It does not build the documentation.
 ``make doc`` builds Sage's documentation in HTML format. Note that
 this requires that Sage be built first, so it will automatically run
 ``make build`` first. Thus running ``make doc`` is equivalent to
 running ``make``.
+ ``make doc`` builds Sage's documentation in HTML format.
+ Note that this requires that Sage be built first, so it will automatically
+ run ``make build`` first.
+ Thus, running ``make doc`` is equivalent to running ``make``.
 ``make docpdf`` builds Sage's documentation in PDF format. This also
requires that Sage be built first, so it will automatically run ``make
build``.
 ``make buildserial`` builds the components of Sage serially, rather
 than in parallel (parallel building is the default). Running ``make
 buildserial`` is equivalent to setting the environment variable
 :envvar:`SAGE_PARALLEL_SPKG_BUILD` to "no"  see below for
+ than in parallel (parallel building is the default).
+ Running ``make buildserial`` is equivalent to setting the environment
+ variable :envvar:`SAGE_PARALLEL_SPKG_BUILD` to "no"  see below for
information about this variable.
 ``make ptest`` and ``make ptestlong``: these first build Sage and its
 html documentation, if necessary, and then run Sage's test suite. The
 second version runs more tests, and so it takes longer. The "p" in
 "ptest" stands for "parallel": tests are run in parallel. If you want
 to run tests serially, you can use ``make test`` or ``make testlong``
 instead.
+ ``make ptest`` and ``make ptestlong``: these run Sage's test suite.
+ The first version skips tests that needs more than a few seconds to complete
+ and those which depends on optional packages or additional software.
+ The second version includes them the former, and so it takes longer.
+ The "p" in ``ptest`` stands for "parallel": tests are run in parallel.
+ If you want to run tests serially, you can use ``make test`` or
+ ``make testlong`` instead.
+ If you want to run tests depending on optional packages and additional
+ software, you can use ``make testalll``, ``make ptestall``,
+ ``make testalllong``, or ``make ptestalllong``.
 ``make distclean`` restores the Sage directory to its state before
 doing any building: it is equivalent to deleting the entire Sage
 directory and unpacking the source tarfile.
+ ``make distclean`` restores the Sage directory to its state before doing any
+ building: it is equivalent to deleting the entire Sage's home directory and
+ unpacking the source tarfile again.
+
+.. _section_envvar:
Environment variables

Sage uses several environment variables to control its build process.
Most users won't need to set any of these: the build process just
works on many platforms. (Note though that setting :envvar:`MAKE`, as
described below, can significantly speed up the process.) Building
Sage involves building about 100 packages, each of which has its own
+Most users won't need to set any of these: the build process just works on many
+platforms.
+(Note though that setting :envvar:`MAKE`, as described below, can significantly
+speed up the process.)
+Building Sage involves building about 100 packages, each of which has its own
compilation instructions.
Here are some of the more commonly used variables affecting the build
process:
+Here are some of the more commonly used variables affecting the build process:
 :envvar:`MAKE`  one useful setting for this variable when building
 Sage is ``MAKE='make jNUM'`` to tell the "make" program to
 run NUM jobs in parallel when building. Some people advise using
 more jobs than there are CPU cores, at least if the system is not
 heavily loaded and has plenty of RAM; for example, a good setting
 for NUM might be between 1 and 1.5 times the number of cores. In
 addition, the "l" option sets a load limit: ``MAKE='make j4
 l5.5``, for example, tells "make" to try to use four jobs, but to
 not start more than one job if the system load average is above 5.5.
 See the manual page for GNU make: `Commandline options
+ :envvar:`MAKE`  one useful setting for this variable when building Sage is
+ ``MAKE='make jNUM'`` to tell the ``make`` program to run ``NUM`` jobs in
+ parallel when building.
+ Some people advise using more jobs than there are CPU cores, at least if the
+ system is not heavily loaded and has plenty of RAM; for example, a good
+ setting for ``NUM`` might be between 1 and 1.5 times the number of cores.
+ In addition, the ``l`` option sets a load limit: ``MAKE='make j4 l5.5``,
+ for example, tells ``make`` to try to use four jobs, but to not start more
+ than one job if the system load average is above 5.5.
+ See the manual page for GNU ``make``: `Commandline options
`_
and `Parallel building
`_.
.. warning::
 Some users on singlecore OS X machines have reported problems
 when building Sage with ``MAKE='make jNUM'`` with NUM greater
 than one.
+ Some users on singlecore OS X machines have reported problems when
+ building Sage with ``MAKE='make jNUM'`` with ``NUM`` greater than one.
 :envvar:`SAGE_NUM_THREADS`  if this is set to a number, then when
 building the documentation, parallel doctesting, or running ``sage
 b``, use this many threads. If this is not set, then determine the
 number of threads using the value of the :envvar:`MAKE` (see above)
 or :envvar:`MAKEFLAGS` environment variables. If none of these
 specifies a number of jobs, use 1 thread (except for parallel
 testing: there we use a default of the number of CPU cores, with a
+ :envvar:`SAGE_NUM_THREADS`  if set to a number, then when building the
+ documentation, parallel doctesting, or running ``sage b``, use this many
+ threads.
+ If this is not set, then determine the number of threads using the value of
+ the :envvar:`MAKE` (see above) or :envvar:`MAKEFLAGS` environment variables.
+ If none of these specifies a number of jobs, use one thread (except for
+ parallel testing: there we use a default of the number of CPU cores, with a
maximum of 8 and a minimum of 2).
 :envvar:`SAGE_PARALLEL_SPKG_BUILD`  if this is set to "no", then
 build spkgs serially rather than in parallel. If this is "no", then
 each spkg may still take advantage of the setting of :envvar:`MAKE`
 to build using multiple jobs, but the spkgs will be built one at a
 time. Alternatively, run "make buildserial" which sets this
 environment variable for you.
+ :envvar:`SAGE_PARALLEL_SPKG_BUILD`  if set to ``no``, then build spkgs
+ serially rather than in parallel.
+ If this is set to ``no``, then each spkg may still take advantage of the setting
+ of :envvar:`MAKE` to build using multiple jobs, but the spkgs will be built
+ one at a time.
+ Alternatively, run ``make buildserial`` which sets this environment
+ variable for you.
 :envvar:`SAGE_CHECK`  if this is set to "yes", then during the
 build process and when running ``sage i ...`` or ``sage f ...``,
 run the test suite for each package which has one. See also
 :envvar:`SAGE_CHECK_PACKAGES`.
+ :envvar:`SAGE_CHECK`  if set to ``yes``, then during the build process,
+ and when running ``sage i `` or ``sage f ``,
+ run the test suite for each package which has one.
+ See also :envvar:`SAGE_CHECK_PACKAGES`.
 :envvar:`SAGE_CHECK_PACKAGES`  If :envvar:`SAGE_CHECK` is set to
 "yes", then the default bahavior is to run test suites for all spkgs
 which contain them. If :envvar:`SAGE_CHECK_PACKAGES` is set, it
 should be a commaseparated list of strings of the form
 ``pkgname`` or ``!pkgname``. An entry ``pkgname`` means to run
 the test suite for the named package regardless of the setting of
 :envvar:`SAGE_CHECK`. An entry ``!pkgname`` means to skip its test
 suite. So if this is set to ``mpir,!python``, then always run the
 test suite for MPIR, but always skip the test suite for Python.
+ :envvar:`SAGE_CHECK_PACKAGES`  if :envvar:`SAGE_CHECK` is set to ``yes``,
+ then the default behavior is to run test suites for all spkgs which contain
+ them.
+ If :envvar:`SAGE_CHECK_PACKAGES` is set, it should be a commaseparated list
+ of strings of the form ``packagename`` or ``!packagename``.
+ An entry ``packagename`` means to run the test suite for the named package
+ regardless of the setting of :envvar:`SAGE_CHECK`.
+ An entry ``!packagename`` means to skip its test suite.
+ So if this is set to ``mpir,!python``, then always run the test suite for
+ MPIR, but always skip the test suite for Python.
.. note::
 As of this writing (Sage 5.0), the test suite for the Python
 spkg fails on most platforms. So when this variable is empty or
 unset, Sage uses a default of ``!python``.
+ As of this writing (April 2013, Sage 5.8), the test suite for the Python
+ spkg fails on most platforms.
+ So when this variable is empty or unset, Sage uses a default of
+ ``!python``.
 :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
 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
 OS X on a 64bit machine, then Sage will automatically build a
 64bit binary, so this variable does not need setting.
+ :envvar:`SAGE64`  if set to ``yes``, then 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 :envvar:`SAGE64` variable is mainly of use on OS X (pre 10.6), Solaris
+ and OpenSolaris, though it will add the ``m64`` flag on any operating
+ system.
+ If you are running Linux or version 10.6 or later of OS X on a 64bit
+ machine, then Sage will automatically build a 64bit binary, so this
+ variable does not need to be set.
 :envvar:`CFLAG64`  default value "m64". If Sage detects that it
 should build a 64bit binary, then it uses this flag when compiling
 C code. Modify it if necessary for your system and C compiler.
 This should not be necessary on most systems  this flag will
 typically be set automatically, based on the setting of
 :envvar:`SAGE64`, for example.
+ :envvar:`CFLAG64`  default value ``m64``.
+ If Sage detects that it should build a 64bit binary, then it uses this flag
+ when compiling C code.
+ Modify it if necessary for your system and C compiler.
+ This should not be necessary on most systems  this flag will typically be
+ set automatically, based on the setting of :envvar:`SAGE64`, for example.
 :envvar:`SAGE_INSTALL_GCC`  by default, Sage will automatically
 detect whether to install the
 `GNU Compiler Collection (GCC) `_
 package or not (depending on whether C, C++ and Fortran compilers
 are present and the versions of those compilers). Setting
 ``SAGE_INSTALL_GCC=yes`` will force Sage to install GCC.
 Setting ``SAGE_INSTALL_GCC=no`` will prevent Sage from installing
 GCC.
+ :envvar:`SAGE_INSTALL_GCC`  by default, Sage will automatically detect
+ whether to install the `GNU Compiler Collection (GCC) `_
+ package or not (depending on whether C, C++ and Fortran compilers are present
+ and the versions of those compilers).
+ Setting ``SAGE_INSTALL_GCC=yes`` will force Sage to install GCC.
+ Setting ``SAGE_INSTALL_GCC=no`` will prevent Sage from installing GCC.
 :envvar:`SAGE_INSTALL_CCACHE`  by default Sage doesn't install
 ccache, however by setting ``SAGE_INSTALL_CCACHE=yes`` Sage will
 install ccache. Because the Sage distribution is quite large, the
 maximum cache is set to 4G. This can be changed by running
 ``sage sh c "ccache maxsize=SIZE"``, where ``SIZE`` is specified
 in gigabytes, megabytes, or kilobytes by appending a G, M, or K.
+ :envvar:`SAGE_INSTALL_CCACHE`  by default Sage doesn't install ccache,
+ however by setting ``SAGE_INSTALL_CCACHE=yes`` Sage will install ccache.
+ Because the Sage distribution is quite large, the maximum cache is set to 4G.
+ This can be changed by running ``sage sh c "ccache maxsize=SIZE"``,
+ where ``SIZE`` is specified in gigabytes, megabytes, or kilobytes by
+ appending a "G", "M", or "K".
 Sage does not include the sources for ccache since it is an optional
 package. Because of this, it is necessary to have an internet
 connection while building Sage with ccache, so that Sage can pull
 down the necessary sources.
+ Sage does not include the sources for ccache since it is an optional package.
+ Because of this, it is necessary to have an Internet connection while
+ building ccache for Sage, so that Sage can pull down the necessary
+ sources.
 :envvar:`SAGE_DEBUG`  enable debugging support. There are three
 different values:
+ :envvar:`SAGE_DEBUG`  controls debugging support.
+ There are three different possible values:
 * Not set (or set to anything else than "yes" or "no"): Build
 binaries with debugging symbols, but no special debug builds. This
 is the default. There is no performance impact, only additional
 disk space is used.
+ * Not set (or set to anything else than "yes" or "no"): build binaries with
+ debugging symbols, but no special debug builds.
+ This is the default.
+ There is no performance impact, only additional disk space is used.
 * ``SAGE_DEBUG=no``: no means no debugging symbols (that is, no
+ * ``SAGE_DEBUG=no``: ``no`` means no debugging symbols (that is, no
``gcc g``), which saves some disk space.
 * ``SAGE_DEBUG=yes``: build debug versions if possible (in
 particular, Python is built with additional debugging turned on
 and Singular is built with a different memory manager). These will
 be notably slower but, for example, make it much easier to
+ * ``SAGE_DEBUG=yes``: build debug versions if possible (in particular,
+ Python is built with additional debugging turned on and Singular is built
+ with a different memory manager).
+ These will be notably slower but, for example, make it much easier to
pinpoint memory allocation problems.
 :envvar:`SAGE_SPKG_LIST_FILES`  Set this to "yes" to enable
 verbose extraction of tar files, i.e. Sage's spkg files. Since
 some spkgs contain a huge number of files such that the log files
 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
 individual spkgs with e.g. ``sage i``.
+ :envvar:`SAGE_SPKG_LIST_FILES`  if set to ``yes``, then enable verbose
+ extraction of tar files, i.e. Sage's spkg files.
+ Since some spkgs contain such a huge number of files that the log files
+ 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 individual spkgs with e.g. ``sage i``
+ or ``sage f``.
 :envvar:`SAGE_SPKG_INSTALL_DOCS`  Set this to "yes" to install
+ :envvar:`SAGE_SPKG_INSTALL_DOCS`  if set to ``yes``, then install
packagespecific documentation to
:file:`$SAGE_ROOT/local/share/doc/PACKAGE_NAME/` when an spkg is
 installed. This option may not be supported by all spkgs. Some
 spkgs might also assume that certain programs are available on the
+ installed.
+ This option may not be supported by all spkgs.
+ Some spkgs might also assume that certain programs are available on the
system (for example, ``latex`` or ``pdflatex``).
 :envvar:`SAGE_DOC_MATHJAX`  By default, any LaTeX code in Sage's
 documentation is processed by MathJax. If this variable is set to
 "no", then MathJax is not used  instead, math is processed using
 LaTeX and converted by dvipng to image files, and then those files
 are included into the documentation. Typically, building the
 documentation using LaTeX and dvipng takes longer and uses more
 memory and disk space than using MathJax.
+ :envvar:`SAGE_DOC_MATHJAX`  by default, any LaTeX code in Sage's
+ documentation is processed by MathJax.
+ If this variable is set to ``no``, then MathJax is not used  instead,
+ math is processed using LaTeX and converted by dvipng to image files,
+ and then those files are included into the documentation.
+ Typically, building the documentation using LaTeX and dvipng takes longer
+ and uses more memory and disk space than using MathJax.
 :envvar:`SAGE_BUILD_DIR`  the default behavior is to build each
 spkg in a subdirectory of :file:`$SAGE_ROOT/spkg/build/`; for
 example, build :file:`atlas3.8.3.p12.spkg` in the directory
 :file:`$SAGE_ROOT/spkg/build/atlas3.8.3.p12/`. If this variable is
 set, build in :file:`$SAGE_BUILD_DIR/atlas3.8.3.p12/`
 instead. If the directory :file:`$SAGE_BUILD_DIR` does not
 exist, it is created. As of this writing (Sage 4.8), when building
 the standard Sage packages, this may require 1.5 gigabytes of free
 space in this directory (or more if :envvar:`SAGE_KEEP_BUILT_SPKGS`
 is "yes"  see below); the exact amount of required space varies
 from platform to platform. For example, the block size of the file
 system will affect the amount of space used, since some spkgs
 contain many small files.
+ :envvar:`SAGE_BUILD_DIR`  the default behavior is to build each spkg in a
+ subdirectory of :file:`$SAGE_ROOT/spkg/build/`; for example, build
+ :file:`atlas3.8.3.p12.spkg` in the directory
+ :file:`$SAGE_ROOT/spkg/build/atlas3.8.3.p12/`.
+ If this variable is set, then build in
+ :file:`$SAGE_BUILD_DIR/atlas3.8.3.p12/` instead.
+ If the directory :file:`$SAGE_BUILD_DIR` does not exist, it is created.
+ As of this writing (Sage 4.8), when building the standard Sage packages,
+ 1.5 gigabytes of free space are required in this directory (or more if
+ ``SAGE_KEEP_BUILT_SPKGS=yes``  see below); the exact amount of required
+ space varies from platform to platform.
+ For example, the block size of the file system will affect the amount of
+ space used, since some spkgs contain many small files.
.. warning::
 The variable :envvar:`SAGE_BUILD_DIR` must be set to the full
 path name of either an existing directory for which the user has write
 permissions, or to the full path name of a nonexistent directory
 which the user has permission to create. The path name must
 contain no spaces.
+ The variable :envvar:`SAGE_BUILD_DIR` must be set to the full path name
+ of either an existing directory for which the user has write permissions,
+ or to the full path name of a nonexistent directory which the user has
+ permission to create.
+ The path name must contain **no spaces**.
 :envvar:`SAGE_KEEP_BUILT_SPKGS`  the default behavior is to delete
 each build directory  the appropriate subdirectory of
 :file:`$SAGE_ROOT/spkg/build` or :file:`$SAGE_BUILD_DIR` 
 after each spkg is successfully built. The subdirectory is not
 deleted if there were errors installing the spkg. Set this variable
 to "yes" to keep the subdirectory regardless. Furthermore, if you
 install an spkg for which there is already a corresponding
 subdirectory, for example left over from a previous build, then the
 default behavior is to delete that old subdirectory. If this
 variable is set to "yes", then the old subdirectory is moved to
 :file:`$SAGE_ROOT/spkg/build/old/` (or
 :file:`$SAGE_BUILD_DIR/old`), overwriting any already
 existing file or directory with the same name.
+ :envvar:`SAGE_KEEP_BUILT_SPKGS`  the default behavior is to delete each
+ build directory  the appropriate subdirectory of
+ :file:`$SAGE_ROOT/spkg/build` or :file:`$SAGE_BUILD_DIR`  after each spkg
+ is successfully built, and to keep it if there were errors installing the
+ spkg.
+ Set this variable to ``yes`` to keep the subdirectory regardless.
+ Furthermore, if you install an spkg for which there is already a
+ corresponding subdirectory, for example left over from a previous build,
+ then the default behavior is to delete that old subdirectory.
+ If this variable is set to ``yes``, then the old subdirectory is moved to
+ :file:`$SAGE_ROOT/spkg/build/old/` (or :file:`$SAGE_BUILD_DIR/old`),
+ overwriting any already existing file or directory with the same name.
.. note::
 After a full build of Sage (as of version 4.8), these
 subdirectories can take up to 6 gigabytes of storage, in total,
 depending on the platform and the block size of the file system.
 If you always set this variable to "yes", it can take even more
 space: rebuilding every spkg would use double the amount of
 space, and any upgrades to spkgs would create still more
 directories, using still more space.
+ After a full build of Sage (as of version 4.8), these subdirectories can
+ take up to 6 gigabytes of storage, in total, depending on the platform
+ and the block size of the file system.
+ If you always set this variable to ``yes``, it can take even more space:
+ rebuilding every spkg would use double the amount of space, and any
+ upgrades to spkgs would create still more directories, using still more
+ space.
.. note::
 In an existing Sage installation, running ``sage i s new.spkg``
 or ``sage f s new.spkg`` installs the spkg ``new.spkg`` and
 keeps the corresponding build directory; thus setting
 :envvar:`SAGE_KEEP_BUILT_SPKGS` to "yes" mimics this behavior
 when building Sage from scratch or when installing individual
 spkgs. So you can set this variable to "yes" instead of using
 the ``s`` flag for ``sage i`` or ``sage f``.
+ In an existing Sage installation, running ``sage i s ``
+ or ``sage f s `` installs the spkg ```` and
+ keeps the corresponding build directory; thus setting
+ :envvar:`SAGE_KEEP_BUILT_SPKGS` to ``yes`` mimics this behavior when
+ building Sage from scratch or when installing individual spkgs.
+ So you can set this variable to ``yes`` instead of using the ``s`` flag
+ for ``sage i`` and ``sage f``.
 :envvar:`SAGE_FAT_BINARY`  to prepare a binary distribution that
 will run on the widest range of target machines, set this variable
 to "yes" before building Sage::
+ :envvar:`SAGE_FAT_BINARY`  to prepare a binary distribution that will run
+ on the widest range of target machines, set this variable to ``yes`` before
+ building Sage::
export SAGE_FAT_BINARY="yes"
make
./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:
+Variables to set if you're trying to build Sage with an unusual setup, 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. AIX, or
 HPUX), or with a compiler which is unsupported (anything except
 gcc), you will see a message saying something like ::
+ :envvar:`SAGE_PORT`  if you try to build Sage on a platform which 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::
 You are attempting to build Sage on IBM's AIX operating system,
 which is not a supported platform for Sage yet. Things may or
 may not work. If you would like to help port Sage to AIX,
 please join the sagedevel discussion list  see
 http://groups.google.com/group/sagedevel
 The Sage community would also appreciate any patches you submit.

 To get past this message, export the variable SAGE_PORT to
 something nonempty.
+ You are attempting to build Sage on IBM's AIX operating system,
+ which is not a supported platform for Sage yet. Things may or
+ may not work. If you would like to help port Sage to AIX,
+ please join the sagedevel discussion list  see
+ http://groups.google.com/group/sagedevel
+ The Sage community would also appreciate any patches you submit.
 If this is the situation, follow the directions: set
 :envvar:`SAGE_PORT` to something nonempty (and expect to run into
 problems).
+ To get past this message and try building Sage anyway,
+ export the variable SAGE_PORT to something nonempty.
 :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.
+ If this is case and you want to try to build Sage anyway, follow the
+ directions: set :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 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:
 :envvar:`SAGE_ATLAS_ARCH`  if you are compiling ATLAS (in
 particular, if :envvar:`SAGE_ATLAS_LIB` is not set), you can use
 this environment variable to set a particular architecture and
 instruction set architecture. The syntax is
 ``SAGE_ATLAS_ARCH=arch[,isaext1][,isaext2]...[,isaextN]``. While
 ATLAS comes with precomputed timings for a variety of CPUs, it only
 uses them if it finds an exact match. Otherwise, ATLAS runs through
 a lengthy automated tuning process in order to optimize performance
 for your particular system. You drastically reduce the total Sage
 compile time if you manually select a suitable architecture. It is
 recommended to specify a suitable architecture on laptops or other
 systems with CPU throttling or if you want to distribute the
 binaries. Available architectures are
+ :envvar:`SAGE_ATLAS_ARCH`  if you are compiling ATLAS (in particular,
+ if :envvar:`SAGE_ATLAS_LIB` is not set), you can use this environment
+ variable to set a particular architecture and instruction set extension.
+ The syntax is ``SAGE_ATLAS_ARCH=arch[,isaext1][,isaext2]...[,isaextN]``.
+ While ATLAS comes with precomputed timings for a variety of CPUs, it only
+ uses them if it finds an exact match.
+ Otherwise, ATLAS runs through a lengthy automated tuning process in order
+ to optimize performance for your particular system, which can take several
+ days on slow and unusual systems.
+ You drastically reduce the total Sage compile time if you manually select a
+ suitable architecture.
+ It is recommended to specify a suitable architecture on laptops or other
+ systems with CPU throttling or if you want to distribute the binaries.
+ Available architectures are
``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``, ``P5``,
``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
@@ 828,237 +1074,263 @@
``IA64Itan``, ``IA64Itan2``, ``USI``, ``USII``, ``USIII``,
``USIV``, ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``
 and instruction set extensions are

+ and instruction set extensions are
+
``AltiVec``, ``SSE3``, ``SSE2``, ``SSE1``, ``3DNow``.
In addition, you can also set
  ``SAGE_ATLAS_ARCH=fast`` picks defaults for a modern (23 year old)
+  ``SAGE_ATLAS_ARCH=fast`` which picks defaults for a modern (23 year old)
CPU of your processor line, and
  ``SAGE_ATLAS_ARCH=base`` picks defaults that should work for a ~10
+  ``SAGE_ATLAS_ARCH=base`` which picks defaults that should work for a ~10
year old CPU.
 For example,
+ For example,
``SAGE_ATLAS_ARCH=Corei7,SSE3,SSE2,SSE1``
would be appropriate for a Core i7 CPU.
 :envvar:`SAGE_ATLAS_LIB`  if you have an installation of ATLAS on
 your system and you want Sage to use it instead of building and
 installing its own version of ATLAS, set this variable to be the
 directory containing your ATLAS installation. It should contain the
 files :file:`libatlas`, :file:`liblapack`, :file:`libcblas`, and
 :file:`libf77blas` with extensions ``.a``, ``.so``, or
 ``.dylib``. For backward compatibility, the libraries may also be in
 the subdirectory ``SAGE_ATLAS_LIB/lib/``.
+ :envvar:`SAGE_ATLAS_LIB`  if you have an installation of ATLAS on your
+ system and you want Sage to use it instead of building and installing its
+ own version of ATLAS, set this variable to be the directory containing your
+ ATLAS installation.
+ It should contain the files :file:`libatlas`, :file:`liblapack`,
+ :file:`libcblas`, and :file:`libf77blas` with extensions ``.a``, ``.so``, or
+ ``.dylib``.
+ For backward compatibility, the libraries may also be in the subdirectory
+ :file:`SAGE_ATLAS_LIB/lib/`.
 :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.
+ :envvar:`SAGE_MATPLOTLIB_GUI`  if set to anything nonempty except ``no``,
+ then Sage will attempt to build the graphical backend when it builds the
+ matplotlib package.
 :envvar:`INCLUDE_MPFR_PATCH`  This is used to add a patch to MPFR
 to bypass a bug in the memset function affecting sun4v machines with
 versions of Solaris earlier than Solaris 10 update 8
 (10/09). Earlier versions of Solaris 10 can be patched by applying
 Sun patch 14254201. Recognized values are:
+ :envvar:`INCLUDE_MPFR_PATCH`  this is used to add a patch to MPFR to bypass
+ a bug in the memset function affecting sun4v machines with versions of
+ Solaris earlier than Solaris 10 update 8 (10/09).
+ Earlier versions of Solaris 10 can be patched by applying Sun patch
+ 14254201.
+ Recognized values are:
  ``INCLUDE_MPFR_PATCH=0``  never include the patch  useful if you
 know all sun4v machines Sage will be used are running Solaris
 10 update 8 or later, or have been patched with Sun patch
 14254201.
+  ``INCLUDE_MPFR_PATCH=0``  never include the patch  useful if you know all
+ sun4v machines Sage will be used are running Solaris 10 update 8 or later,
+ or have been patched with Sun patch 14254201.
  ``INCLUDE_MPFR_PATCH=1``  always include the patch, so the binary
 will work on a sun4v machine, even if created on an older sun4u
 machine.
+  ``INCLUDE_MPFR_PATCH=1``  always include the patch, so the binary will
+ work on a sun4v machine, even if created on an older sun4u machine.
 If this variable is unset, include the patch on sun4v machines only.
+  If this variable is unset, include the patch on sun4v machines only.
 :envvar:`SAGE_BINARY_BUILD`  used by the pil package. If set to
 "yes", then force Sage to use the versions of libjpeg, libtiff and
 libpng from :file:`$SAGE_ROOT/local/lib`. Otherwise, allow the use
 of the system's versions of these libraries.
+ :envvar:`SAGE_BINARY_BUILD`  used by the pil package.
+ If set to ``yes``, then force Sage to use the versions of libjpeg, libtiff
+ and libpng from :file:`$SAGE_ROOT/local/lib`.
+ Otherwise, allow the use of the system's versions of these libraries.
 :envvar:`SAGE_PIL_NOTK`  used by the pil package. If set to "yes",
 then disable building TK. If this is not set, then this should be
 dealt with automatically: Sage tries to build the pil package with
 TK support enabled, but if it runs into problems, it tries building
 again with TK disabled. So only use this variable to force TK to be
 disabled. (Building the pil package is pretty fast  less than a
 minute on many systems  so allowing it to build twice is not a
 serious issue.)
+ :envvar:`SAGE_PIL_NOTK`  used by the pil package.
+ If set to ``yes``, then disable building TK.
+ If this is not set, then this should be dealt with automatically: Sage tries
+ to build the pil package with TK support enabled, but if it runs into
+ problems, it tries building again with TK disabled.
+ So only use this variable to force TK to be disabled.
+ (Building the pil package is pretty fast  less than a minute on many
+ systems  so allowing it to build twice is not a serious issue.)
Some standard environment variables which are used by Sage:
 :envvar:`CC`  while some programs allow you to use this to specify
 your C compiler, **not every Sage package recognizes this**.
 If GCC is installed within Sage, :envvar:`CC` is ignored and Sage's
 ``gcc`` is used instead.
+ :envvar:`CC`  while some programs allow you to use this to specify your C
+ compiler, **not every Sage package recognizes this**.
+ If GCC is installed within Sage, :envvar:`CC` is ignored and Sage's ``gcc``
+ is used instead.
 :envvar:`CXX`  similarly, this will set the C++ compiler for some
 Sage packages, and similarly, using it is likely quite risky.
 If GCC is installed within Sage, :envvar:`CXX` is ignored and Sage's
 ``g++`` is used instead.
+ :envvar:`CPP`  similarly, this will set the C preprocessor for some Sage
+ packages, and similarly, using it is likely quite risky.
+ If GCC is installed within Sage, :envvar:`CPP` is ignored and Sage's ``cpp``
+ is used instead.
+
+ :envvar:`CXX`  similarly, this will set the C++ compiler for some Sage
+ packages, and similarly, using it is likely quite risky.
+ If GCC is installed within Sage, :envvar:`CXX` is ignored and Sage's ``g++``
+ is used instead.
 :envvar:`FC`  similarly, this will set the Fortran compiler.
This is supported by all Sage packages which have Fortran code.
 However, for historical reasons, the value is hardcoded during the
 initial ``make`` and subsequent changes to ``$FC`` might be ignored
 (in which case, the original value will be used instead).
+ However, for historical reasons, the value is hardcoded during the initial
+ ``make`` and subsequent changes to ``$FC`` might be ignored (in which case,
+ the original value will be used instead).
If GCC is installed within Sage, :envvar:`FC` is ignored and Sage's
``gfortran`` is used instead.
 :envvar:`CFLAGS`, :envvar:`CXXFLAGS` and :envvar:`FCFLAGS`  the
 flags for the C compiler, the C++ compiler and the Fortran compiler,
 respectively. The same comments apply to these: setting them may
 cause problems, because they are not universally respected among the
 Sage packages.
+ :envvar:`CFLAGS`, :envvar:`CXXFLAGS` and :envvar:`FCFLAGS`  the flags for
+ the C compiler, the C++ compiler and the Fortran compiler, respectively.
+ The same comments apply to these: setting them may cause problems, because
+ they are not universally respected among the Sage packages.
The following Fortranrelated environment variables are **deprecated**
since Sage 5.3 and support for these will likely be removed.
+The following Fortranrelated environment variables are **deprecated** since
+Sage 5.3 and support for these will likely be removed.
They are still recognized, but should not be used for new setups.
 :envvar:`SAGE_FORTRAN`  the path to the Fortran compiler.
Deprecated, use :envvar:`FC` instead.
 :envvar:`SAGE_FORTRAN_LIB`  the path to the Fortran runtime library.
 Normally, you don't need to set this. If you really need to,
 you can add the directory containing the library to
+ Normally, you don't need to set this.
+ If you really need to, you can add the directory containing the library to
:envvar:`LIBRARY_PATH` and/or :envvar:`LD_LIBRARY_PATH`.
Sage uses the following environment variables when it runs:
 :envvar:`DOT_SAGE`  this is the directory, to which the user has
 read and write access, where Sage stores a number of files. The
 default location is ``~/.sage/``, but you can change that by setting
 this variable.
+ :envvar:`DOT_SAGE`  this is the directory, to which the user has read and
+ write access, where Sage stores a number of files.
+ The default location is :file:`$HOME/.sage/`.
 :envvar:`SAGE_STARTUP_FILE`  a file including commands to be
 executed every time Sage starts. The default value is
 ``$DOT_SAGE/init.sage``.
+ :envvar:`SAGE_STARTUP_FILE`  a file including commands to be executed every
+ time Sage starts.
+ The default value is :file:`$DOT_SAGE/init.sage`.
 :envvar:`SAGE_SERVER`  if you want to install a Sage package using
 ``sage i PKG_NAME``, Sage downloads the file from the web, using
 the address ``http://www.sagemath.org/`` by default, or the address
 given by :envvar:`SAGE_SERVER` if it is set. If you wish to set up
 your own server, then note that Sage will search the directories
 ``SAGE_SERVER/packages/standard/``,
 ``SAGE_SERVER/packages/optional/``,
 ``SAGE_SERVER/packages/experimental/``, and
 ``SAGE_SERVER/packages/archive/`` for packages. See the script
 :file:`$SAGE_ROOT/spkg/bin/sagespkg` for the implementation.
+ ``sage i ``, Sage downloads the file from the web, using the
+ address ``http://www.sagemath.org/`` by default, or the address given by
+ :envvar:`SAGE_SERVER` if it is set.
+ If you wish to set up your own server, then note that Sage will search the
+ directories:
 :envvar:`SAGE_PATH`  a colonseparated list of directories which
 Sage searches when trying to locate Python libraries.
+  ``SAGE_SERVER/packages/standard/``,
+  ``SAGE_SERVER/packages/optional/``,
+  ``SAGE_SERVER/packages/experimental/``,
+  and ``SAGE_SERVER/packages/archive/``
 :envvar:`SAGE_BROWSER`  on most platforms, Sage will detect the
 command to run a web browser, but if this doesn't seem to work on
 your machine, set this variable to the appropriate command.
+ for packages.
+ See the script :file:`$SAGE_ROOT/spkg/bin/sagespkg` for the implementation.
 :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET`  set this to something
 nonempty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before
 executing system commands.
+ :envvar:`SAGE_PATH`  a colonseparated list of directories which Sage
+ searches when trying to locate Python libraries.
 :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET`  similar, but only used
 on Mac OS X to set the :envvar:`DYLD_LIBRARY_PATH`.
+ :envvar:`SAGE_BROWSER`  on most platforms, Sage will detect the command to
+ run a web browser, but if this doesn't seem to work on 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` variable before executing
+ system commands.
+
+ :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET`  similar, but only used on OS X to
+ set the :envvar:`DYLD_LIBRARY_PATH` variable.
 :envvar:`SAGE_CBLAS`  used in the file
 :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`. Set this to the
 base name of the BLAS library file on your system if you want to
 override the default setting. That is, if the relevant file is
 called :file:`libcblas_new.so` or :file:`libcblas_new.dylib`, then
 set this to "cblas_new".
+ :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`.
+ Set this to the base name of the BLAS library file on your system if you want
+ to override the default setting.
+ That is, if the relevant file is called :file:`libcblas_new.so` or
+ :file:`libcblas_new.dylib`, then set this to ``cblas_new``.
Sage overrides the user's settings of the following variables:
 :envvar:`MPLCONFIGDIR`  ordinarily, this variable lets the user set
 their matplotlib config directory. Due to incompatibilies in the
 contents of this directory among different versions of matplotlib,
 Sage overrides the user's setting, defining it instead to be
 ``$DOT_SAGE/matplotlibVER``, with "VER" replaced by the
+ :envvar:`MPLCONFIGDIR`  ordinarily, this variable lets the user set their
+ matplotlib config directory.
+ Due to incompatibilies in the contents of this directory among different
+ versions of matplotlib, Sage overrides the user's setting, defining it
+ instead to be :file:`$DOT_SAGE/matplotlibVER`, with ``VER`` replaced by the
current matplotlib version number.
Variables dealing with doctesting:
 :envvar:`SAGE_TIMEOUT`  used for Sage's doctesting: the number of
 seconds to allow a doctest before timing it out. If this isn't set,
 the default is 360 seconds (6 minutes).

 :envvar:`SAGE_TIMEOUT_LONG`  used for Sage's doctesting: the number
 of seconds to allow a doctest before timing it out, if tests are run
 using ``sage t long``. If this isn't set, the default is 1800
 seconds (30 minutes).
+ :envvar:`SAGE_TIMEOUT`  used for Sage's doctesting: the number of seconds
+ to allow a doctest before timing it out.
+ If this isn't set, the default is 360 seconds (6 minutes).
 :envvar:`SAGE_PICKLE_JAR`  if you want to update the the standard
 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
+ :envvar:`SAGE_TIMEOUT_LONG`  used for Sage's doctesting: the number of
+ seconds to allow a doctest before timing it out, if tests are run using
+ ``sage t long``.
+ If this isn't set, the default is 1800 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 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
`here (picklejar)
`_
and `here (unpickle_all)
`_.
..
 THIS INDENTED BLOCK IS A COMMENT. FIX IT ONCE WE UNDERSTAND
 THESE VARIABLES.
+.. comment:
+ ***************************************************************************
+ FIX THIS!
 Variables dealing with valgrind and friends:
+ Variables dealing with valgrind and friends:
  :envvar:`SAGE_TIMEOUT_VALGRIND`  used for Sage's doctesting: the
 number of seconds to allow a doctest before timing it out, if tests
 are run using ``??``. If this isn't set, the default is 1024*1024
 seconds.
+  :envvar:`SAGE_TIMEOUT_VALGRIND`  used for Sage's doctesting: the
+ number of seconds to allow a doctest before timing it out, if tests
+ are run using ``??``. If this isn't set, the default is 1024*1024
+ seconds.
  :envvar:`SAGE_VALGRIND`  ?
+  :envvar:`SAGE_VALGRIND`  trigger black magic in Python.
  :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`,
 :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS`  flags
 used when using valgrind and one of the tools "memcheck", "massif",
 "cachegrind", or "omega"
+  :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`,
+ :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS`  flags
+ used when using valgrind and one of the tools "memcheck", "massif",
+ "cachegrind", or "omega"
+ ***************************************************************************
+
Installation in a Multiuser Environment

This section addresses the question of how a system administrator
can install a single copy of Sage in a multiuser computer
network.
+This section addresses the question of how a system administrator can install
+a single copy of Sage in a multiuser computer network.
Systemwide install
~~~~~~~~~~~~~~~~~~~
#. After you build Sage, you may optionally copy or move the entire
 build tree to ``/usr/local`` or another location. If you do this,
 then you must run ``./sage`` once so that various hardcoded
 locations will get updated. For this reason, it might be easier to
 simply build Sage in its final location.
+#. After building Sage, you may optionally copy or move the entire build tree
+ to :file:`/usr/local` or another location.
+ If you do this, then you must run ``./sage`` once so that various hardcoded
+ locations get updated.
+ For this reason, it might be easier to simply build Sage in its final
+ location.
#. Make a symbolic link to the ``sage`` script in ``/usr/local/bin``::
+#. Make a symbolic link to the ``sage`` script in :file:`/usr/local/bin`::
ln s /path/to/sagex.y.z/sage /usr/local/bin/sage
Alternatively, copy the Sage script::
cp /path/to/sagex.y.z/sage /usr/local/bin/sage

 and edit the file ``/usr/local/bin/sage``: ``SAGE_ROOT`` should be
 set to the directory ``/path/to/sagex.y.z/`` where Sage is
 installed. It is recommended not to edit the original ``sage``
 script, only the copy in ``/usr/local/bin/sage``.
#. Make sure that all files in the Sage tree are readable by all::
+ If you do this, make sure you edit the line::
 chmod a+rX R /usr/local/sage5.0
+ #SAGE_ROOT=/path/to/sageversion
+
+ at the beginning of the copied ``sage`` script according to the direction
+ given there to something like::
+
+ SAGE_ROOT=
+
+ (note that you have to change ```` above!).
+ It is recommended not to edit the original ``sage`` script, only the copy at
+ :file:`/usr/local/bin/sage`.
+
+#. Make sure that all files in the Sage tree are readable by all
+ (note that you have to change ```` below!)::
+
+ chmod a+rX R
#. Optionally, you can test Sage by running::
make testlong

+
or ``make ptestlong`` which tests files in parallel using multiple
 processes. You can also omit ``long`` to skip tests which take a long
 time.
+ processes.
+ You can also omit ``long`` to skip tests which take a long time.
+
+Sagetex
+~~~~~~~
+
+To make SageTeX available to your users, see the instructions for
+:ref:`installation in a multiuser environment `
+.
+
Some common problems

@@ 1066,22 +1338,28 @@
ATLAS
~~~~~
Sometimes the ATLAS spkg can fail to build. Some things to check for:
+Sometimes the ATLAS spkg can fail to build.
+Some things to check for:
 Make sure that CPU throttling mode (= powersaving mode) is turned off
+ Make sure that CPU throttling mode (i.e. powersaving mode) is turned off
when building ATLAS.
 Also, the ATLAS build can fail if the system load is too high, and in
+ The ATLAS build can also fail if the system load is too high, and in
particular this has been known to happen when building with
 ``MAKE='make jNUM'`` with NUM large. If this happens, just try
 running "make" again. If "make" fails after five or six attempts,
 report your problem to the sagedevel mailing list.
+ ``MAKE='make jNUM'`` with ``NUM`` large.
+ If this happens, just try running ``make`` again.
+ If ``make`` fails after five or six attempts, report your problem to the
+ sagedevel mailing list at http://groups.google.com/group/sagedevel.
Special Notes

+zn_poly
+~~~~~~~
 To make SageTeX available to your users, see the instructions for
 :ref:`installation in a multiuser environment
 `.
+It has been reported (see :trac:`13947`) that the zn_poly spkg fails to build
+on loaded systems, especially on Mac OS X and Cygwin.
+If you encounter this problem, you can try to build zn_poly serially before
+reissuing ``make``::
 **This page was last updated in August 2012 (Sage 5.3).**
+ MAKE="make j1" ./sage i zn_poly && make
+
+
+**This page was last updated in April 2013 (Sage 5.8).**