Ticket #14465: source.4.patch

File source.4.patch, 100.5 KB (added by jpflori, 8 years ago)
  • doc/en/installation/source.rst

    # HG changeset patch
    # User Jean-Pierre Flori <jean-pierre.flori@ssi.gouv.fr>
    # Date 1366235392 -7200
    # Node ID 11d332f13ea80598872a365fca075eb8438900ff
    # 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 b  
    11.. comment:
    2    ****************************
    3    If you alter this document, please change the last line ("This page
    4    was last updated in ...")
    5    ****************************
     2    ***************************************************************************
     3    If you alter this document, please change the last line:
     4    **This page was last updated in MONTH YEAR (Sage X.Y).**
     5    ***************************************************************************
    66
    77Install from Source Code
    88========================
    99
    1010More familiarity with computers may be required to build Sage from
    11 the `source code <http://en.wikipedia.org/wiki/Source_code>`_. If you do have all the
    12 pre-requisite tools, the process should
    13 be completely painless. It will take your computer a while to
    14 compile Sage from the source code, although you don't have to watch. Compiling
    15 Sage from the source code has the major advantage that you have the latest
    16 version of Sage with which you can change absolutely any part
    17 or the programs on which Sage depends. You can also recompile Sage.
    18 Also, some parts of Sage will be optimised for your particular computer,
    19 so will run faster than a binary that you have downloaded.
     11the `source code <http://en.wikipedia.org/wiki/Source_code>`_.
     12If you do have all the pre-requisite tools, the process should be completely
     13painless, basically consisting in extracting the source tarball and typing
     14``make``.
     15It can take your computer a while to build Sage from the source code,
     16although the procedure is fully automated and should need no human
     17intervention.
     18Building Sage from the source code has the major advantage that your install
     19will be optimised for your particular computer and should therefore offer
     20better performance and compatibility than a binary install.
     21Moreover, it offers you full development capabilities:
     22you can change absolutely any part of Sage or the programs on which it depends,
     23and recompile the modified parts.
    2024
    21 Sage is supported on a number of
    22 `Linux <http://en.wikipedia.org/wiki/Linux>`_
    23 , Mac `OS X <http://www.apple.com/macosx/>`_ , Sun/Oracle `Solaris <http://www.oracle.com/solaris>`_ and
    24 `OpenSolaris <http://en.wikipedia.org/wiki/OpenSolaris>`_
    25 releases, but Sage is not supported on all versions of Linux, OS X,
    26 Solaris or OpenSolaris. Depending on the `operating system <http://en.wikipedia.org/wiki/Operating_system>`_, Sage works
    27 with `x86 <http://en.wikipedia.org/wiki/X86>`_, `x64 <http://en.wikipedia.org/wiki/X86-64>`_, `PowerPC <http://en.wikipedia.org/wiki/PowerPC>`_ or `SPARC <http://en.wikipedia.org/wiki/SPARC>`_ processors. There is no native version of Sage which
    28 installs on `Microsoft Windows <http://en.wikipedia.org/wiki/Microsoft_Windows>`_, although Sage can be used on Windows
    29 with the aid of a  `virtual machine <http://en.wikipedia.org/wiki/Virtual_machine>`_ .
    30 Go to http://www.sagemath.org/download-windows.html
    31 to download a version of Sage for Windows. See http://wiki.sagemath.org/SupportedPlatforms
    32 for the list of platforms on which Sage is supported and the level of support
    33 for these systems. You will also find details about `ports <http://en.wikipedia.org/wiki/Computer_port_%28software%29>`_
    34 to other operating systems or processors which may be taking place.
     25Supported platforms
     26-------------------
    3527
    36 Assumptions: You have a computer with at least 3 GB of free
    37 disk space running one of the supported version of an
    38 operating system listed at
     28Sage is supported on a number of `Linux <http://en.wikipedia.org/wiki/Linux>`_,
     29Mac `OS X <http://www.apple.com/macosx/>`_ ,
     30Sun/Oracle `Solaris <http://www.oracle.com/solaris>`_
     31and `OpenSolaris <http://en.wikipedia.org/wiki/OpenSolaris>`_ releases,
     32but Sage is not supported on all versions of Linux, OS X, Solaris or
     33OpenSolaris.
     34Depending on the
     35`operating system <http://en.wikipedia.org/wiki/Operating_system>`_,
     36Sage works with `x86 <http://en.wikipedia.org/wiki/X86>`_,
     37`x86_64 <http://en.wikipedia.org/wiki/X86-64>`_,
     38`PowerPC <http://en.wikipedia.org/wiki/PowerPC>`_,
     39`ARM <http://en.wikipedia.org/wiki/ARM_architecture>`_,
     40or `SPARC <http://en.wikipedia.org/wiki/SPARC>`_ processors.
     41There is no native version of Sage which installs on
     42`Microsoft Windows <http://en.wikipedia.org/wiki/Microsoft_Windows>`_,
     43although Sage can be used on Windows with the aid of a
     44`virtual machine <http://en.wikipedia.org/wiki/Virtual_machine>`_
     45or the `Cygwin <http://cygwin.com/>`_ Linux API layer.
     46Go to http://www.sagemath.org/download-windows.html to download a binary
     47version of Sage for Windows.
     48
     49See http://wiki.sagemath.org/SupportedPlatforms for the full list of platforms
     50on which Sage is supported and the level of support for these systems.
     51You will also find details about
     52`ports <http://en.wikipedia.org/wiki/Computer_port_%28software%29>`_
     53to other operating systems or processors which may be taking place.
     54
     55
     56Prerequisites
     57-------------
     58
     59General requirements
     60~~~~~~~~~~~~~~~~~~~~
     61
     62Your computer comes with at least 4 GB of free disk space running one of the
     63supported versions of an operating system listed at
    3964http://wiki.sagemath.org/SupportedPlatforms.
    40 The following standard
    41 command-line development tools must be installed on your computer.
    42 (Under OS X they all come with `Xcode <http://developer.apple.com/xcode/>`_).
    4365
    44 - A **C compiler**: GCC version 4.0.1 or newer should work.  Older
    45   versions may or may not work.  On Solaris or OpenSolaris systems,
    46   the Sun compiler should also work.
    47 - **make**: GNU make, version 3.80 or later
    48 - **m4**
    49 - **perl**: version 5.8.0 or later
    50 - **tar**: GNU tar version 1.17 or later, or BSD tar
    51 - **ranlib**
    52 - On recent Debian or Ubuntu systems: the **dpkg-dev** package for
    53   `multiarch <http://wiki.debian.org/Multiarch>`_ support
     66In addition to standard `POSIX <http://en.wikipedia.org/wiki/POSIX>`_ utilities
     67and a `bash <http://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_-compatible shell,
     68the following standard command-line development tools must be installed on your
     69computer:
    5470
    55 Recommended but not strictly required:
    56 
    57 - **latex**: highly recommended
    58 - **dvipng**
    59 - **ImageMagick**
    60 - **ffmpeg**
    61 - **ssh-keygen**: needed to run the notebook in secure mode
     71- A **C compiler**: GCC version 4.0.1 or newer should work.
     72  Older versions may or may not work.
     73  On Solaris or OpenSolaris systems, the Sun compiler should also work.
     74- **make**: GNU make, version 3.80 or later.
     75- **m4**.
     76- **perl**: version 5.8.0 or later.
     77- **ranlib**.
     78- **tar**: GNU tar version 1.17 or later, or BSD tar.
    6279
    6380Sage also needs a C++ compiler and a Fortran compiler.
    64 However, it contains a `GNU Compiler Collection (GCC) <http://gcc.gnu.org/>`_
    65 package, so C, C++ and Fortran compilers will be built if needed
    66 (you can also use the environment variable :envvar:`SAGE_INSTALL_GCC` to
    67 control whether or not to install GCC).
    68 You always need some C compiler to build GCC and its prerequisites itself.
     81The only configuration currently supported is matching versions of the
     82C, C++ and Fortran compilers from the
     83`GNU Compiler Collection (GCC) <http://gcc.gnu.org/>`_.
     84Therefore, if you plan on using your own GCC compilers, then make sure that
     85their versions match.
     86Alternatively, Sage includes a GCC package, so that C, C++ and Fortran
     87compilers will be built when the build system detects that it is needed,
     88e.g., non-GCC compilers, or mismatching versions of the GCC compilers,
     89versions of the GCC compilers known to miscompile some Sage's dependencies,
     90or simply a missing C++ or Fortran compiler.
     91Whatsoever, you always need at least a C compiler to build the GCC package and
     92its prerequisites before the compilers it provides can be used.
     93Note that you can always override this behavior through the environment
     94variable :envvar:`SAGE_INSTALL_GCC`, see :ref:`section_compilers` and
     95:ref:`section_envvar`.
    6996
    70 .. note::
     97Although some of Sage is written in `Python <http://www.python.org/>`_, you do
     98not need Python pre-installed on your computer, since the Sage installation
     99includes virtually everything you need.
    71100
    72     Optional: Read this if you are intending to run a Sage notebook server
    73     for multiple users. For security (i.e., to run
    74     ``notebook(secure=True)``) you may wish users to access the server using
    75     the HTTPS protocol. You also may want to use OpenID for user
    76     authentication. The first of these requires you to install pyOpenSSL,
    77     and they both require OpenSSL. If you have OpenSSL and the OpenSSL
    78     development headers installed on your system, you can install
    79     pyOpenSSL by building Sage and then typing ::
     101After extracting the Sage tarball, the subdirectory :file:`spkg` contains the
     102source distributions for everything on which Sage depends.
     103We emphasize that all of this software is included with Sage, so you do not
     104have to worry about trying to download and install any one of these packages
     105(such as Python, for example) yourself.
    80106
    81         ./sage -i pyopenssl
     107When the Sage installation program is run,
     108it will check that you have each of the above-listed prerequisites,
     109and inform you of any that are missing, or have unsuitable versions.
    82110
    83     Note that this command requires internet access.  Alternatively, ``make
    84     ssl`` builds Sage and installs pyOpenSSL.  If you are missing either
    85     OpenSSL or OpenSSL's development headers, you can install a local copy
    86     of both into your Sage installation first. Ideally, this should be
    87     done before installing Sage; otherwise, you should at least rebuild
    88     Sage's Python, and ideally any part of Sage relying on it. So the
    89     procedure is as follows (again, with a computer connected to the
    90     internet). Starting from a fresh Sage tarball::
     111System-specific requirements
     112~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    91113
    92         ./sage -i patch openssl  # install patch and openssl
    93         make ssl
     114On recent Debian or Ubuntu systems, the **dpkg-dev** package is needed for
     115`multiarch <http://wiki.debian.org/Multiarch>`_ support.
    94116
    95     Alternatively, if you've already built Sage::
     117On Cygwin, the **lapack** and **liblapack-devel** packages are required to
     118provide ATLAS support as the ATLAS spkg is not built by default.
    96119
    97         ./sage -i openssl
    98         ./sage -f python   # rebuild Python
    99         SAGE_UPGRADING=yes make ssl
     120Installing prerequisites
     121~~~~~~~~~~~~~~~~~~~~~~~~
    100122
    101     The third line will rebuild all parts of Sage that depend on Python;
    102     this can take a while.
     123To check if you have the above prerequisites installed, for example ``perl``,
     124type::
    103125
    104 To check if you have ``perl`` installed, for example, type
     126    command -v perl
     127
     128or::
     129
     130    which perl
     131
     132on the command line. If it gives an error (or returns nothing), then
     133either ``perl`` is not installed, or it is installed but not in your
     134`PATH <http://en.wikipedia.org/wiki/PATH_%28variable%29>`_.
     135
     136On Linux systems (e.g., Ubuntu, Redhat, etc), ``ranlib`` is in the
     137`binutils <http://www.gnu.org/software/binutils/>`_ package.
     138The other programs are usually located in packages with their respective names.
     139Assuming you have sufficient privileges, you can install the ``binutils`` and
     140other necessary components.
     141If you do not have the privileges to do this, ask your system administrator to
     142do this, or build the components from source code.
     143The method of installing additional software varies from distribution to
     144distribution, but on a `Debian <http://www.debian.org/>`_ based system (e.g.
     145`Ubuntu <http://www.ubuntu.com/>`_ or `Mint <http://www.linuxmint.com/>`_),
     146you would use
     147`apt-get <http://en.wikipedia.org/wiki/Advanced_Packaging_Tool>`_::
     148
     149     sudo apt-get install binutils gcc make m4 perl tar
     150
     151to install all general requirements (this was tested on Ubuntu 12.04.2).
     152On other Linux systems, you might use
     153`rpm <http://en.wikipedia.org/wiki/RPM_Package_Manager>`_,
     154`yum <http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified>`_,
     155or other package managers.
     156
     157On OS X systems, you need a recent version of
     158`Command Line Tools <http://developer.apple.com/opensource/>`_.
     159It provides all the above requirements.
     160You can download it for free at
     161http://developer.apple.com/downloads/index.action?=command%20line%20tools
     162provided you registered for a free Apple Developer account at
     163http://developer.apple.com/register/.
     164Alternatively, if you have already installed
     165`Xcode <http://developer.apple.com/xcode/>`_
     166(which at the time of writing is freely available in the Mac App Store,
     167or through http://developer.apple.com/downloads/ provided you registered for an
     168Apple Developer account),
     169you can open Xcode's "Downloads" preference pane and install the command line
     170tools from there.
     171On pre-Lion OS X systems, the command line tools are not available as a
     172separate download and you have to install the full-blown Xcode supporting your
     173system version.
     174
     175On Solaris, you would use ``pkgadd`` and on OpenSolaris ``ipf`` to install
     176the necessary software.
     177
     178On Cygwin, you would use the ``setup.exe`` program.
     179As on Linux systems ``ranlib`` is provided by the ``binutils`` package.
     180As far as compilers are concerned, you should either install matching versions
     181of the ``gcc4-core``, ``gcc4-g++``, and ``gcc4-gfortran`` packages, or
     182the ``gcc4-core`` package alone if you plan on using Sage's own GCC.
     183
     184On other systems, check the documentation for your particular operating system.
     185
     186Specific notes for ``make`` and ``tar``
     187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     188
     189On OS X, the system-wide BSD ``tar`` supplied will build Sage, so there is no
     190need to install the GNU ``tar``.
     191
     192On Solaris or OpenSolaris, the Sun/Oracle versions of ``make`` and ``tar`` are
     193unsuitable for building Sage.
     194Therefore, you must have the GNU versions of ``make`` and ``tar`` installed and
     195they must be the first ``make`` and ``tar`` in your :envvar:`PATH`.
     196
     197On Solaris 10, a version of GNU ``make`` may be found at
     198:file:`/usr/sfw/bin/gmake`,
     199but you will need to copy it somewhere else and rename it to ``make``.
     200The same is true for GNU ``tar``; a version of GNU ``tar`` may be found at
     201:file:`/usr/sfw/bin/gtar`,
     202but it will need to be copied somewhere else and renamed to ``tar``.
     203It is recommended to create a directory :file:`$HOME/bins-for-sage` and to put
     204the GNU versions of ``tar`` and ``make`` in that directory.
     205Then ensure that :file:`$HOME/bins-for-sage` is first in your :envvar:`PATH`.
     206That's because Sage also needs :file:`/usr/ccs/bin` in your :envvar:`PATH` to
     207execute programs like ``ar`` and ``ranlib``, but :file:`/usr/ccs/bin` has the
     208Sun/Oracle versions of ``make`` and ``tar`` in it.
     209
     210If you attempt to build Sage on AIX or HP-UX, you will need to install both
     211GNU ``make`` and GNU ``tar``.
     212
     213.. _section_compilers:
     214
     215Using alternative compilers
     216~~~~~~~~~~~~~~~~~~~~~~~~~~~
     217
     218Sage developers tend to use fairly recent versions of GCC.
     219Nonetheless, Sage build process should succeed with any reasonable C compiler.
     220This is because Sage will build GCC first (if needed) and then use that newly
     221built GCC to compile Sage.
     222
     223If you don't want this and want to try building Sage with a different set of
     224compilers,
     225you need to set the environment variable :envvar:`SAGE_INSTALL_GCC` to ``no``.
     226
     227If you are interested in working on support for commerical compilers from
     228`HP <http://docs.hp.com/en/5966-9844/ch01s03.html>`_,
     229`IBM <http://www-01.ibm.com/software/awdtools/xlcpp/>`_,
     230`Intel <http://software.intel.com/en-us/articles/intel-compilers/>`_,
     231`Sun/Oracle <http://www.oracle.com/technetwork/server-storage/solarisstudio/overview/index.html>`_,
     232etc,
     233or the open-source `Clang <http://clang.llvm.org/>`_,
     234please email the sage-devel mailing list, also known as the sage-devel Google
     235group at http://groups.google.com/group/sage-devel.
     236
     237
     238Additional software
     239-------------------
     240
     241Recommended programs
     242~~~~~~~~~~~~~~~~~~~~
     243
     244The following programs are recommended.
     245They are not strictly required at build time or at run time,
     246but provide additional capablities:
     247
     248- **dvipng**.
     249- **ffmpeg**.
     250- **ImageMagick**.
     251- **latex**: highly recommended.
     252
     253It is highly recommended that you have
     254`Latex <http://en.wikipedia.org/wiki/LaTeX>`_
     255installed, but it is not required.
     256
     257On Linux systems, it is usually provided by packages derived from
     258`TeX Live <www.tug.org/texlive/>`_  and can be installed using::
     259
     260    sudo apt-get install texlive
     261
     262or similar commands.
     263
     264On other systems it might be necessary to install TeX Live from source code,
     265which is quite easy, though a rather time-consuming process.
     266
     267If you don't have either ImageMagick or ffmpeg, you won't be able to
     268view animations.
     269ffmpeg can produce animations in more different formats than ImageMagick,
     270and seems to be faster than ImageMagick when creating animated GIFs.
     271Either ImageMagick or dvipng is used for displaying some LaTeX output in the
     272Sage notebook.
     273
     274Notebook additional features
     275~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     276
     277By default, the Sage notebook uses the
     278`HTTP <http://en.wikipedia.org/wiki/HTTP>`_
     279protocol when you type the command ``notebook()``.
     280To run the notebook in secure mode by typing ``notebook(secure=True)`` which
     281uses the `HTTPS <http://en.wikipedia.org/wiki/HTTPS>`_ protocol,
     282or to use `OpenID <http://en.wikipedia.org/wiki/OpenID>`_ authentication,
     283you need to follow specific installation steps described in
     284:ref:`section_notebook_ssl`.
     285
     286Although all necessary components are provided through Sage optional packages,
     287i.e. you can install a local version of `OpenSSL <http://www.openssl.org>`_
     288by using Sage's **openssl** spkg and running ``sage -i openssl`` as suggested
     289in :ref:`section_notebook_ssl` (this requires an Internet connection),
     290you might prefer to install OpenSSL and the OpenSSL development headers
     291globally on your system.
     292
     293On Linux systems, those are usually provided by the **libssl** and
     294**libssl-dev** packages and can be installed using::
     295
     296    sudo apt-get install libssl libssl-dev
     297
     298or similar commands.
     299
     300Finally, if you intend to distribute the notebook load onto several Sage
     301servers, you will surely want to setup an
     302`SSH <http://en.wikipedia.org/wiki/SSH>`_ server and generate SSH keys.
     303This can be achieved using `OpenSSH <http://www.openssh.org>`_.
     304
     305On Linux systems, the OpenSSH server, client and utilities are usually provided
     306by the **openssh-server** and **openssh-client** packages and can be installed
     307using::
     308
     309    sudo apt-get install openssh-server openssh-client
     310
     311or similar commands.
     312
     313Tcl/Tk
     314~~~~~~
     315
     316If you want to use `Tcl/Tk <http://www.tcl.tk/>`_ libraries in Sage,
     317you need to install the Tcl/Tk and its development headers before building
     318Sage.
     319Sage's Python will then automatically recognize your system's install of
     320Tcl/Tk.
     321
     322On Linux systems, these are usually provided by the **tk** and **tk-dev**
     323(or **tk-devel**) packages which can be installed using::
     324
     325    sudo apt-get install tk tk-dev
     326
     327or similar commands.
     328
     329If you installed Sage first, all is not lost.
     330You just need to rebuild Sage's Python, , and ideally any part of Sage relying
     331on it::
     332
     333    sage -f python  # rebuild Python
     334    SAGE_UPGRADING=yes make # rebuild components of Sage depending on Python
     335
     336after installing the Tcl/Tk development libraries as above.
     337
     338If
     339
     340.. skip
    105341
    106342::
    107343
    108        command -v perl
     344   sage: import _tkinter
     345   sage: import Tkinter
    109346
     347does not raise an ``ImportError``, then it worked.
    110348
    111 on the command line. If it gives an error (or returns nothing), then
    112 either ``perl`` is not installed, or it is installed but not in your
    113 `PATH <http://en.wikipedia.org/wiki/PATH_%28variable%29>`_.
    114 It is highly recommended that you have `Latex <http://en.wikipedia.org/wiki/LaTeX>`_
    115 installed, but it is not required. If you don't have ``ssh-keygen`` on your
    116 local system, then you cannot run the notebook in secure mode, which the uses
    117 encrypted `HTTPS <http://en.wikipedia.org/wiki/HTTP_Secure>`_ protocol.
    118 To run the notebook in secure mode, type the command
    119 ``notebook(secure=True)`` instead of ``notebook()``. Unless ``notebook(secure=True)``
    120 is used, the notebook uses the less secure `HTTP <http://en.wikipedia.org/wiki/HTTP>`_ protocol.
    121349
    122 If you don't have either ImageMagick or ffmpeg, you won't be able to
    123 view animations.  ffmpeg can produce animations in more different
    124 formats than ImageMagick, and seems to be faster than ImageMagick when
    125 creating animated GIFs.  Either ImageMagick or dvipng is used for
    126 displaying some LaTeX output in the Sage notebook.
     350Step-by-step installation procedure
     351-----------------------------------
    127352
    128 In OS X, make sure you have a recent version of `Xcode <http://developer.apple.com/xcode/>`_.
    129 See http://wiki.sagemath.org/SupportedPlatforms to find out what
    130 version(s) of Xcode are supported. You can get the latest Xcode
    131 from http://developer.apple.com/xcode/, but may have to pay a small
    132 fee in order to download this.
     353General procedure
     354~~~~~~~~~~~~~~~~~
    133355
    134 On Linux systems (e.g., Ubuntu, Redhat etc), ``ranlib`` is in the
    135 `Binutils <http://www.gnu.org/software/binutils/>`_ package.
    136 Assuming you have sufficient privileges,
    137 you can install the ``binutils`` and other necessary components. If you
    138 do not have the privileges to do this, ask your system
    139 administrator to do this, or build the components from source
    140 code. The method of installing additional software varies from
    141 distribution to distribution
    142 but on a `Debian <http://www.debian.org/>`_ based system (e.g. `Ubuntu <http://www.ubuntu.com/>`_ or `Mint <http://www.linuxmint.com/>`_), you would use:
     356Installation from source is (potentially) very easy, because the distribution
     357contains (essentially) everything on which Sage depends.
    143358
    144 ::
    145 
    146      sudo apt-get install build-essential
    147 
    148 (this was tested on Ubuntu 9.04).
    149 
    150 On other Linux systems you might use `rpm <http://en.wikipedia.org/wiki/RPM_Package_Manager>`_,
    151 `yum <http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified>`_ or other package manager. On
    152 Solaris you would use ``pkgadd`` and on OpenSolaris use ``ipf``. Check
    153 the documentation for your particular operating system.
    154 
    155 The LaTeX package and a PDF previewer are optional but they can be
    156 installed using
    157 
    158 ::
    159 
    160     sudo apt-get install texlive xpdf evince xdvi
    161 
    162 On other systems it might be necessary to install TeX Live from source code,
    163 which is quite easy, though a rather time-consuming process. 
    164 
    165 On Solaris or OpenSolaris, you must have the GNU version of ``make``
    166 installed and it must be the first
    167 ``make`` in your PATH. On Solaris 10, a version of GNU ``make`` may be found
    168 at ``/usr/sfw/bin/gmake`` but you will need to copy it somewhere else
    169 and rename it to ``make``. The same is true for GNU ``tar`` - there is a version
    170 called ``gtar`` in ``/usr/sfw/bin`` but it will need to be copied somewhere
    171 else and renamed to ``tar``). If you attempt to build Sage on AIX or HP-UX,
    172 you will need to install both GNU tar and GNU make. On OS X, the BSD tar
    173 suppied will build Sage, so there is no need to install GNU tar.
    174 
    175 For Solaris, it is recommended you create a directory ``$HOME/bins-for-sage`` and
    176 put the GNU versions of ``tar`` and ``make`` in that directory. Then ensure that
    177 ``$HOME/bins-for-sage`` is first in your PATH. That's because Sage also needs
    178 ``/usr/ccs/bin`` in your PATH to execute programs like ``ar`` and ``ranlib``,
    179 but ``/usr/ccs/bin`` has the Sun/Oracle versions of ``make`` and ``tar``
    180 which are unsuitable for building Sage. For more information on
    181 building Sage on Solaris, see http://wiki.sagemath.org/solaris
    182 
    183 Although some of Sage is written in `Python <http://www.python.org/>`_, you do not need Python
    184 pre-installed on your computer, since the Sage installation
    185 includes virtually everything you need. When the Sage installation program is run,
    186 it will check that you have each of the above-listed prerequisites,
    187 and inform you of any that are missing, or have unsuitable verisons.
    188 
    189 -  If you want to use `Tcl/Tk <http://www.tcl.tk/>`_ libraries in Sage,
    190    do the following before compiling Sage.
    191    Sage's Python will automatically recognize your system's
    192    install of Tcl/Tk if it exists. You need to install the
    193    Tcl/Tk development libraries though, not just the Tck/Tk base.
    194 
    195    On `Ubuntu <http://www.ubuntu.com/>`_, this is the command::
    196 
    197        sudo apt-get install tk8.5-dev    # or the latest version available
    198 
    199    Now you can install Sage, If you forgot
    200    and installed Sage first anyway, all is not lost.
    201    Just issue the command::
    202 
    203        sage -f  python-2.6.4.p9    # or the latest version available
    204 
    205    after installing the Tcl/Tk development libraries as above.
    206    If
    207 
    208    .. skip
    209 
    210    ::
    211 
    212        sage: import _tkinter
    213        sage: import Tkinter
    214 
    215    does not raise an ``ImportError`` then it worked.
    216 
    217 -  Sage developers tend to use fairly recent versions of GCC, but Sage
    218    should compile with any reasonable C compiler.  This is because Sage
    219    will build GCC first (if needed) and then use that newly built GCC to
    220    compile Sage.
    221 
    222    If you don't want this and want to try building Sage with a
    223    different compiler, you need to set the environment variable
    224    ``SAGE_INSTALL_GCC=no``.
    225 
    226    If you are interested in working on support for commerical compilers
    227    from `HP <http://docs.hp.com/en/5966-9844/ch01s03.html>`_,
    228    `IBM <http://www-01.ibm.com/software/awdtools/xlcpp/>`_,
    229    `Intel <http://software.intel.com/en-us/articles/intel-compilers/>`_,
    230    `Sun/Oracle <http://www.oracle.com/technetwork/server-storage/solarisstudio/overview/index.html>`_ etc,
    231    or the open-source `Clang <http://clang.llvm.org/>`_,
    232    please email the sage-devel mailing list, otherwise known as the
    233    sage-devel Google group at
    234    http://groups.google.com/group/sage-devel
    235 
    236 After extracting the Sage tarball, the subdirectory ``spkg`` contains
    237 the source distributions for everything on which Sage depends. We
    238 emphasize that all of this software is included with Sage, so you
    239 do not have to worry about trying to download and install any one
    240 of these packages (such as GAP, for example) yourself.
    241 
    242 Steps to Install from Source
    243 ----------------------------
    244 
    245 Installation from source is (potentially) very easy, because the
    246 distribution contains (essentially) everything on which Sage
    247 depends.
    248 
    249 Make sure there are **no spaces** in the path name for the directory
    250 in which you build: several of Sage's components will not build if
    251 there are spaces in the path.  Running Sage from a directory with
    252 spaces in its name will also fail.
     359Make sure there are **no spaces** in the path name for the directory in which
     360you build:
     361several of Sage's components will not build if there are spaces in the path.
     362Running Sage from a directory with spaces in its name will also fail.
    253363
    254364#. Go to http://www.sagemath.org/download-source.html, select a mirror,
    255    and download the file ``sage-x.y.z.tar``.
     365   and download the file :file:`sage-x.y.z.tar`.
    256366
    257    This tarfile contains the source code for Sage and the source for
    258    all programs on which Sage depends. Download it into a subdirectory
    259    of your home directory into which you want to install Sage. Note
    260    that this file is not compressed; it's just a plain tarball (which
     367   This tarfile contains the source code for Sage and the source for all
     368   programs on which Sage depends.
     369   Note that this file is not compressed; it's just a plain tarball (which
    261370   happens to be full of compressed files).
    262371
    263 #. Extract:
     372   Download it into any directory you have write access to, preferably on a
     373   fast filesystem, avoiding
     374   `NFS <http://en.wikipedia.org/wiki/Network_File_System>`_ and the like.
     375   On personal computers, any subdirectory of your :envvar:`HOME` directory
     376   should do.
     377   The directory where you built Sage is **NOT** hardcoded.
     378   You should be able to safely move or rename that directory.
     379   (It's a bug if this is not the case.)
    264380
    265    ::
     381#. Extract the tarfile::
    266382
    267              tar xvf sage-x.y.z.tar
     383       tar xvf sage-x.y.z.tar
    268384
    269 #. This creates a directory ``sage-x.y.z``.
     385   This creates a directory :file:`sage-x.y.z`.
    270386
    271 #. Change into that directory
     387#. Change into that directory::
    272388
    273    ::
     389       cd sage-x.y.z
    274390
    275              cd sage-x.y.z
     391   This is Sage's home directory.
     392   It is also referred to as :envvar:`SAGE_ROOT` or the top level Sage
     393   directory.
    276394
    277    This is Sage's home directory. It is also referred to as
    278    ``SAGE_ROOT`` or the top level Sage directory.
     395#. Optional, but highly recommended:
     396   Read the :file:`README.txt` file there.
    279397
    280 #. Optional (but highly recommended): Read the ``README.txt`` file
    281    there.
     398#. On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to build a
     399   64-bit version of Sage, assuming your computer and operating system are
     400   64-bit, type::
    282401
    283 #. On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to
    284    build a 64-bit version of Sage, then assuming your computer and
    285    operating system are 64-bit, type
     402       export SAGE64=yes
    286403
    287    ::
     404   It should be noted that as of April 2011, 64-bit builds of Sage on both
     405   Solaris 10 and OpenSolaris are not very stable, so you are advised not to
     406   set :envvar:`SAGE64` to ``yes``.
     407   This will then create stable 32-bit versions of Sage.
     408   See http://wiki.sagemath.org/solaris for the latest information.
    288409
    289            SAGE64=yes
    290            export SAGE64
    291    
    292    It should be noted that at the time of writing (April 2011), 64-bit
    293    builds of Sage on both Solaris 10 and OpenSolaris are not very stable,
    294    so you are advised not to set ``SAGE64`` to ``yes``. This will then
    295    create stable 32-bit versions of Sage.
    296    See http://wiki.sagemath.org/SupportedPlatforms  and
    297    http://wiki.sagemath.org/solaris for the latest information, as
    298    work is ongoing to resolve the 64-bit Solaris & OpenSolaris problems.
     410#. Start the build process::
    299411
    300 #. Type
     412       make
    301413
    302    ::
     414   or if your system is multithreaded and you want to use several threads to
     415   build Sage::
    303416
    304              make
     417       MAKE='make -jNUM' make
    305418
    306    This compiles Sage and all dependencies. Note that you do not need
    307    to be logged in as root, since no files are changed outside of the
    308    ``sage-x.y.z`` directory (with one exception -- the ``.ipythonrc``
    309    directory is created in your ``HOME`` directory if it doesn't exist).
     419   to tell the ``make`` program to run ``NUM`` jobs in parallel when building
     420   Sage.
     421   This compiles Sage and all its dependencies.
     422
     423   Note that you do not need to be logged in as root, since no files are
     424   changed outside of the :file:`sage-x.y.z` directory.
    310425   In fact, **it is inadvisable to build Sage as root**, as the root account
    311    should only be used when absolutely necessary, as mis-typed commands
    312    can have serious consequences if you are logged in as root.  There has been a bug
    313    `reported <http://trac.sagemath.org/sage_trac/ticket/9551/>`_ in Sage
    314    which would have overwritten a system file had the user been logged in
    315    as root.
     426   should only be used when absolutely necessary and mistyped commands can have
     427   serious consequences if you are logged in as root.
     428   There has been a bug reported (see :trac:`9551`) in Sage which would have
     429   overwritten a system file had the user been logged in as root.
    316430
    317    Typing ``make`` does the usual steps for each of the packages, but puts
    318    all the results in the local build tree. Depending on the architecture of your system (e.g.,
    319    Celeron, Pentium Mobile, Pentium 4, SPARC, etc.), it can take over three hours
    320    to build Sage from source. On slower older hardware it can take over
    321    a day to build Sage. If the build is successful, you will not see
    322    the word ERROR in the last 3-4 lines of output.
     431   Typing ``make`` performs the usual steps for each Sage's dependency,
     432   but installs all the resulting files into the local build tree.
     433   Depending on the age and the architecture of your system, it can take from
     434   a few tens of minutes to several hours to build Sage from source.
     435   On really slow hardware, it can even take a few days to build Sage.
    323436
     437   If the build is successful, you will not see the word ``ERROR`` in the last
     438   3-4 lines of output.
    324439   Each component of Sage has its own build log, saved in
    325    ``SAGE_ROOT/logs/pkgs``.  In particular,
    326    if the build of Sage fails, then you can type the following from the directory
    327    where you typed ``make``.
    328 
    329    ::
     440   :file:`SAGE_ROOT/logs/pkgs`.
     441   In particular, if the build of Sage fails, then you can type the following
     442   from the directory where you typed ``make``::
    330443
    331444            grep -li "^Error installing" logs/pkgs/*
    332  
    333    Then paste the contents of the log file(s) with errors to the Sage
    334    support newsgroup http://groups.google.com/group/sage-support
    335    If the log files are very large (and many are), then don't paste
    336    the whole file, but make sure to include any error messages.
    337445
    338    The directory where you built Sage is NOT hardcoded. You should
    339    be able to safely move or rename that directory. (It's a bug if
    340    this is not the case)
     446   Then paste the contents of the log file(s) with errors to the Sage support
     447   newsgroup at http://groups.google.com/group/sage-support.
     448   If the log files are very large (and many are), then don't paste the whole
     449   file, but make sure to include any error messages.
     450   It would also be helpful to include the type of operating system
     451   (Linux, OS X, Solaris, OpenSolaris, Cygwin, or any other system),
     452   the version and release date of that operating system and the version of
     453   the copy of Sage you are using.
     454   (There are no formal requirements for bug reports -- just send them;
     455   we appreciate everything.)
    341456
    342    See :ref:`section_make` for some options for the ``make`` command.
     457   See :ref:`section_make` for some targets for the ``make`` command,
     458   :ref:`section_envvar` for additional informatio on useful environment
     459   variables used by Sage,
     460   and :ref:`section_notebook_ssl` for additional instruction on how to build
     461   the notebook with SSL support.
    343462
    344 #. To start Sage, change into the Sage home directory and type:
     463#. To start Sage, you can now simply type from Sage's home directory::
    345464
    346    ::
     465       ./sage
    347466
    348              ./sage
    349 
    350    You should see the Sage prompt, which will look something like this
    351    (starting the first time should take well under a minute, but can
    352    take several minutes if the file system is slow or busy. Since Sage
    353    opens a lot of files, it is preferable to install Sage on a fast file
    354    system if this is possible.):
    355 
    356    ::
     467   You should see the Sage prompt, which will look something like this::
    357468
    358469       $ sage
    359470       ----------------------------------------------------------------------
    360        | Sage Version 4.7, Release Date: 2011-05-23                         |
    361        | Type notebook() for the GUI, and license() for information.        |
     471       | Sage Version 5.8, Release Date: 2013-03-15                         |
     472       | Type "notebook()" for the browser-based notebook interface.        |
     473       | Type "help()" for help.                                            |
    362474       ----------------------------------------------------------------------
    363475       sage:
    364476
     477   Note that Sage should take well under a minute when it starts for the first
     478   time, but can take several minutes if the file system is slow or busy.
     479   Since Sage opens a lot of files, it is preferable to install Sage on a fast
     480   filesystem if possible.
     481
    365482   Just starting successfully tests that many of the components built
    366    correctly. If the above is not displayed (e.g., if you get a
    367    massive traceback), please report the problem, e.g., to
    368    http://groups.google.com/group/sage-support .
    369    It would also be helpful to
    370    include the type of operating system (Linux, OS X, Solaris or OpenSolaris),
    371    the version and date of that operating system and the version
    372    number of the copy of Sage you are using. (There are no
    373    formal requirements for bug reports - just send them; we appreciate
    374    everything.)
     483   correctly.
     484   Note that this should have been already automatically tested during the
     485   build process.
     486   If the above is not displayed (e.g., if you get a massive traceback), please
     487   report the problem, e.g., at http://groups.google.com/group/sage-support.
    375488
    376    After Sage starts, try a command:
    377 
    378    ::
     489   After Sage has started, try a simple command::
    379490
    380491       sage: 2 + 2
    381492       4
    382493
    383    Try something more complicated, which uses the PARI C library:
     494   Try something more complicated, which uses the
     495   `FLINT <http://www.flintlib.org/>`_ C library::
    384496
    385    ::
    386 
    387        sage: factor(2005)
     497       sage: GF(7)(x^7)
    388498       5 * 401
    389499
    390    Try something simple that uses the Gap, Singular, Maxima and
    391    PARI/GP interfaces:
    392 
    393    ::
     500   Try something simple that uses the `GAP <http://www.gap-system.org/>`_,
     501   `Maxima <http://maxima.sourceforge.net/>`_,
     502   `PARI/GP <http://pari.math.u-bordeaux.fr/>`_ and
     503   `Singular <http://www.singular.uni-kl.de/>`_ interfaces::
    394504
    395505       sage: gap('2+2')
    396506       4
     507       sage: maxima('2+2')
     508       4
     509       sage: pari('2+2')
     510       4
    397511       sage: gp('2+2')
    398512       4
    399        sage: maxima('2+2')
    400        4
    401513       sage: singular('2+2')
    402514       4
    403        sage: pari('2+2')
    404        4
    405515
    406    (For those familiar with GAP: Sage automatically builds a GAP
    407    "workspace" during installation, so the response time from this GAP
    408    command is relatively fast. For those familiar with GP/PARI, the
    409    ``gp`` command creates an object in the GP interpreter, and the
    410    ``pari`` command creates an object directly in the PARI C-library.)
     516   (For those familiar with GAP: Sage automatically builds a GAP "workspace"
     517   during installation, so the response time from this GAP command is
     518   relatively fast.
     519   For those familiar with GP/PARI, the ``pari`` command creates an object
     520   directly in the PARI C library, and the ``gp`` command creates an object in
     521   the GP interpreter.)
    411522
    412    Try running Gap, Singular or GP from Sage:
     523   Try running GAP, GP, Maxima, or Singular, from Sage:
    413524
    414525   .. skip
    415526
    416527   ::
    417528
    418529       sage: gap_console()
    419        GAP4, Version: 4.4.12 of 17-Dec-2008, i386-pc-solaris2.11-gcc
     530        ┌───────┐   GAP, Version 4.5.7 of 14-Dec-2012 (free software, GPL)
     531        │  GAP  │   http://www.gap-system.org
     532        └───────┘   Architecture: x86_64-unknown-linux-gnu-gcc-default64
     533        Libs used:  gmp, readline
     534        Loading the library and packages ...
     535        Packages:   GAPDoc 1.5.1
     536        Try '?help' for help. See also  '?copyright' and  '?authors'
    420537       gap> 2+2;
    421538       4
    422        [ctrl-d]
     539       gap>
     540       [CTRL+D]
    423541
    424542   .. skip
    425543
    426544   ::
    427545
    428546       sage: gp_console()
    429        ...
    430        [ctrl-d]
     547       Reading GPRC: .../sage-5.8/local/etc/gprc.expect ...Done.
     548       
     549                  GP/PARI CALCULATOR Version 2.5.3 (development git-6fd07f9)
     550                 amd64 running linux (x86-64/GMP-5.0.2 kernel) 64-bit version
     551               compiled: Apr 10 2013, gcc-4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5)
     552                        (readline v6.2 enabled, extended help enabled)
     553       
     554                            Copyright (C) 2000-2011 The PARI Group
     555       
     556       PARI/GP is free software, covered by the GNU General Public License, and comes
     557       WITHOUT ANY WARRANTY WHATSOEVER.
     558       
     559       Type ? for help, \q to quit.
     560       Type ?12 for how to get moral (and possibly technical) support.
     561       
     562       parisize = 8000000, primelimit = 500509
     563       ? 2+2
     564       %1 = 4
     565       ?
     566       [CTRL+D]
     567
     568   .. skip
     569
     570   ::
     571
     572       sage: maxima_console()
     573       ;;; Loading #P".../sage-5.8/local/lib/ecl/sb-bsd-sockets.fas"
     574       ;;; Loading #P".../sage-5.8/local/lib/ecl/sockets.fas"
     575       ;;; Loading #P".../sage-5.8/local/lib/ecl/defsystem.fas"
     576       ;;; Loading #P".../sage-5.8/local/lib/ecl/cmp.fas"
     577       Maxima 5.29.1 http://maxima.sourceforge.net
     578       using Lisp ECL 12.12.1
     579       Distributed under the GNU Public License. See the file COPYING.
     580       Dedicated to the memory of William Schelter.
     581       The function bug_report() provides bug reporting information.
     582       (%i1) 2+2;
     583       (%o1)                                  4
     584       (%i2)
     585       [CTRL+D]
    431586
    432587   .. skip
    433588
    434589   ::
    435590
    436591       sage: singular_console()
    437                             SINGULAR                             /  Development
    438         A Computer Algebra System for Polynomial Computations   /   version 3-1-1
    439                                                               0<
    440             by: G.-M. Greuel, G. Pfister, H. Schoenemann        \   Feb 2010
    441        FB Mathematik der Universitaet, D-67653 Kaiserslautern    \
    442        [ctrl-d]
    443        > Auf Wiedersehen.
    444        sage:
     592                            SINGULAR                                 /  Development
     593        A Computer Algebra System for Polynomial Computations       /   version 3-1-5
     594                                                                  0<
     595        by: W. Decker, G.-M. Greuel, G. Pfister, H. Schoenemann     \   Jul 2012
     596       FB Mathematik der Universitaet, D-67653 Kaiserslautern        \
     597       > 2+2;
     598       4
     599       >
     600       [CTRL+D]
    445601
    446 #. Optional: Check the interfaces to any other software that
    447    you have available. Note that each interface calls its
    448    corresponding program by a particular name:
    449    `Mathematica <http://www.wolfram.com/mathematica/>`_ is invoked
    450    by calling ``math``, `Maple <http://www.maplesoft.com/>`_ by calling ``maple``, etc. The
    451    easiest way to change this name or perform other customizations is
    452    to create a redirection script in ``$SAGE_ROOT/local/bin``. Sage
    453    inserts this directory at the front of your PATH, so your script
    454    may need to use an absolute path to avoid calling itself; also,
    455    your script should use ``$*`` to pass along all of its arguments.
    456    For example, a ``maple`` script might look like:
    457 
    458    ::
     602#. Optional:
     603   Check the interfaces to any other software that you have available.
     604   Note that each interface calls its corresponding program by a particular
     605   name: `Mathematica <http://www.wolfram.com/mathematica/>`_ is invoked by
     606   calling ``math``, `Maple <http://www.maplesoft.com/>`_ by calling ``maple``,
     607   etc.
     608   The easiest way to change this name or perform other customizations is
     609   to create a redirection script in :file:`$SAGE_ROOT/local/bin`.
     610   Sage inserts this directory at the front of your :envvar:`PATH`, so your
     611   script may need to use an absolute path to avoid calling itself; also, your
     612   script should use ``$*`` to pass along all of its arguments.
     613   For example, a ``maple`` script might look like::
    459614
    460615       #!/bin/sh
    461616
    462617       /etc/maple10.2/maple.tty $*
    463618
    464 #. Optional: Different possibilities to make using Sage a little
    465    easier:
     619#. Optional:
     620   There are different possibilities to make using Sage a little easier:
    466621
    467    - Make a symbolic link from ``/usr/local/bin/sage`` (or another
    468      directory in your :envvar:`PATH`) to ``$SAGE_ROOT/sage``::
     622   - Make a symbolic link from :file:`/usr/local/bin/sage` (or another
     623     directory in your :envvar:`PATH`) to :file:`$SAGE_ROOT/sage`::
    469624
    470625         ln -s /path/to/sage-x.y.z/sage /usr/local/bin/sage
    471626
    472      Now simply typing ``sage`` should be sufficient to run Sage.
    473 
    474    - Copy ``$SAGE_ROOT/sage`` to a location in your ``PATH``. If you do
    475      this, make sure you edit the line ``#SAGE_ROOT=/path/to/sage-version``
    476      at the top of the copied ``sage`` script. It is best to edit only
    477      the copy, not the original.
    478 
    479    -  For KDE users, create a bash script {sage} containing the lines
    480 
    481       ::
    482 
    483           #!/bin/bash
    484           konsole -T "sage" -e <SAGE_ROOT>/sage
    485 
    486       which you make executable (``chmod a+x sage``) and put it somewhere in
    487       your path. (Note that you have to change ``$SAGE_ROOT`` above!) You
    488       can also make a KDE desktop icon with this as the command (under
    489       the Application tab of the Properties of the icon, which you get my
    490       right clicking the mouse on the icon).
    491 
    492    - On Linux and OS X systems, you can make an alias to ``$SAGE_ROOT/sage``.
    493      For example, put something similar to the following line in your
    494      ``.bashrc`` file::
    495 
    496          alias sage=/home/username/sage-5.0/sage
    497 
    498      Having done so, quit your terminal emulator and restart it again.
    499      Now typing ``sage`` within your terminal emulator should start
     627     Now simply typing ``sage`` from any directory should be sufficient to run
    500628     Sage.
    501629
    502 #. Optional, but highly recommended: Test the install by typing ``./sage --testall``.
     630   - Copy :file:`$SAGE_ROOT/sage` to a location in your :envvar:`PATH`.
     631     If you do this, make sure you edit the line::
     632
     633         #SAGE_ROOT=/path/to/sage-version
     634
     635     at the beginning of the copied ``sage`` script according to the direction
     636     given there to something like::
     637
     638         SAGE_ROOT=<SAGE_ROOT>
     639
     640     (note that you have to change ``<SAGE_ROOT>`` above!).
     641     It is best to edit only the copy, not the original.
     642
     643   - For `KDE <http://www.kde.org/>`_ users, create a bash script called
     644     ``sage`` containing the lines
     645     (note that you have to change ``<SAGE_ROOT>`` below!)::
     646
     647         #!/bin/bash
     648
     649         konsole -T "sage" -e <SAGE_ROOT>/sage
     650
     651     make it executable::
     652
     653         chmod a+x sage
     654
     655     and put it somewhere in your :envvar:`PATH`.
     656
     657     You can also make a KDE desktop icon with this line as the command
     658     (under the Application tab of the Properties of the icon, which you get my
     659     right clicking the mouse on the icon).
     660
     661   - On Linux and OS X systems, you can make an alias to
     662     :file:`$SAGE_ROOT/sage`.
     663     For example, put something similar to the following line in your
     664     :file:`.bashrc` file::
     665
     666         alias sage=<SAGE_ROOT>/sage
     667
     668     (Note that you have to change ``<SAGE_ROOT>`` above!)
     669     Having done so, quit your terminal emulator and restart it.
     670     Now typing ``sage`` within your terminal emulator should start Sage.
     671
     672#. Optional, but highly recommended:
     673   Test the install by typing ``./sage --testall``.
    503674   This runs most examples in the source code and makes sure that they run
    504    exactly as claimed. To test all examples, use
    505    ``./sage --testall --optional --long``; this will run examples that take
    506    a long time, and those that depend on optional packages and
    507    software, e.g., Mathematica or Magma. Some (optional) examples will
    508    likely fail because they assume that a database is installed.
    509    Alternatively, from within ``$SAGE_ROOT``, you can type
    510    ``make test`` to run all the standard test code.  This can take
    511    from 25 minutes to several hours, depending on your hardware. On
    512    very old hardware building and testing Sage can take several days!
     675   exactly as claimed.
     676   To test all examples, use ``./sage --testall --optional --long``;
     677   this will run examples that take a long time, and those that depend on
     678   optional packages and software, e.g., Mathematica or Magma.
     679   Some (optional) examples will therefore likely fail.
    513680
    514 #. Optional: Install optional Sage packages and databases. Type
    515    ``sage --optional`` to see a list or visit
    516    http://www.sagemath.org/packages/optional/, and
    517    ``sage -i <package name>`` to automatically download and install a
    518    given package.
     681   Alternatively, from within :file:`$SAGE_ROOT`, you can type ``make test``
     682   (respectively ``make ptest``) to run all the standard test code serially
     683   (respectively in parallel).
    519684
    520 #. Optional: Run the ``install_scripts`` command from within Sage to create
    521    gp, singular, gap, etc., scripts in your ``PATH``. Type
    522    ``install_scripts?`` in Sage for details.
     685   Testing the Sage library can take from half an hour to several hours,
     686   depending on your hardware.
     687   On slow hardware building and testing Sage can even take several days!
    523688
     689#. Optional:
     690   Install optional Sage packages and databases.
     691   Type ``sage --optional`` to see a list of them (this requires an Internet
     692   connection), or visit http://www.sagemath.org/packages/optional/.
     693   Then type ``sage -i <package-name>`` to automatically download and install
     694   a given package.
    524695
    525 Have fun! Discover some amazing conjectures!
     696#. Optional:
     697   Run the ``install_scripts`` command from within Sage to create GAP, GP,
     698   Maxima, Singular, etc., scripts in your :envvar:`PATH`.
     699   Type ``install_scripts?`` in Sage for details.
     700
     701#. Have fun! Discover some amazing conjectures!
     702
     703.. _section_notebook_ssl:
     704
     705Building the notebook with SSL support
     706~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     707
     708Read this section if you are intending to run a Sage notebook server for
     709multiple users.
     710
     711For security, you may wish users to access the server using the HTTPS protocol
     712(i.e., to run ``notebook(secure=True)``).
     713You also may want to use OpenID for user authentication.
     714The first of these requires you to install
     715`pyOpenSSL <http://pyopenssl.sourceforge.net/>`_,
     716and they both require OpenSSL.
     717
     718If you have OpenSSL and the OpenSSL development headers installed on your
     719system, you can install pyOpenSSL by building Sage and then typing::
     720
     721    ./sage -i pyopenssl
     722
     723Alternatively, ``make ssl`` builds Sage and installs pyOpenSSL at once.
     724Note that these commands require Internet access.
     725
     726If you are missing either OpenSSL or OpenSSL's development headers,
     727you can install a local copy of both into your Sage installation first.
     728Ideally, this should be done before installing Sage; otherwise, you should at
     729least rebuild Sage's Python, and ideally any part of Sage relying on it.
     730The procedure is as follows (again, with a computer connected to the
     731Internet).
     732Starting from a fresh Sage tarball::
     733
     734    ./sage -i openssl
     735    make ssl
     736
     737And if you've already built Sage::
     738
     739    ./sage -i openssl
     740    ./sage -f python
     741    SAGE_UPGRADING=yes make ssl
     742
     743The third line will rebuild all parts of Sage that depend on Python;
     744this can take a while.
     745
     746Rebasing issues on Cygwin
     747~~~~~~~~~~~~~~~~~~~~~~~~~
     748
     749Building on Cygwin will occasionally require "rebasing" ``dll`` files.
     750Sage provides some scripts, located in :file:`$SAGE_LOCAL/bin`, to do so:
     751
     752- ``sage-rebaseall.sh``, a shell script which calls Cygwin's ``rebaseall``
     753  program.
     754  It must be run within a ``dash`` shell from the :envvar:`SAGE_ROOT` directory
     755  after all other Cygwin processes have been shut down and needs write-access
     756  to the system-wide rebase database located at :file:`/etc/rebase.db.i386`,
     757  which usually means administrator privileges.
     758  It updates the system-wide database and adds Sage dlls to it, so that
     759  subsequent calls to ``rebaseall`` will take them into account.
     760- ``sage-rebase.sh``, a shell script which calls Cygwin's ``rebase`` program
     761  together with the ``-O/--oblivious`` option.
     762  It must be run within a shell from :envvar:`SAGE_ROOT` directory.
     763  Contrary to the ``sage-rebaseall.sh`` script, it neither updates the
     764  system-wide database, nor adds Sage dlls to it.
     765  Therefore, subsequent calls to ``rebaseall`` will not take them into account.
     766- ``sage-rebaseall.bat`` (respectively ``sage-rebase.bat``), an MS-DOS batch
     767  file which calls the ``sage-rebaseall.sh`` (respectively ``sage-rebase.sh``)
     768  script.
     769  It must be run from a Windows command prompt, after adjusting
     770  :envvar:`SAGE_ROOT` to the Windows location of Sage's home directory, and, if
     771  Cygwin is installed in a non-standard location, adjusting
     772  :envvar:`CYGWIN_ROOT` as well.
     773
     774Some systems may encounter this problem frequently enough to make building or
     775testing difficult.
     776If executing the above scripts or directly calling ``rebaseall`` does not solve
     777rebasing issues, deleting the system-wide database and then regenerating it
     778from scratch, e.g., by executing ``sage-rebaseall.sh``, might help.
     779
     780Finally, on Cygwin, one should also avoid the following:
     781
     782- building in home directories of Windows domain users;
     783- building in paths with capital letters
     784  (see :trac:`13343`, although there has been some success doing so).
     785
    526786
    527787.. _section_make:
    528788
    529789Make targets
    530790------------
    531791
    532 To build Sage from scratch, you would typically give the command
    533 ``make`` to build Sage and its HTML documentation. The ``make`` command
    534 is pretty smart, so if your build of Sage is interrupted, then running
    535 ``make`` again should cause it to pick up where it left off. The
    536 ``make`` command can also be given options, which control what is built
    537 and how it is built.
     792To build Sage from scratch, you would typically execute ``make`` in Sage's home
     793directory to build Sage and its `HTML <http://en.wikipedia.org/wiki/HTML>`_
     794documentation.
     795The ``make`` command is pretty smart, so if your build of Sage is interrupted,
     796then running ``make`` again should cause it to pick up where it left off.
     797The ``make`` command can also be given options, which control what is built and
     798how it is built:
    538799
    539 - ``make build`` builds Sage: it compiles all of the Sage packages. It
    540   does not build the documentation.
     800- ``make build`` builds Sage: it compiles all of the Sage packages.
     801  It does not build the documentation.
    541802
    542 - ``make doc`` builds Sage's documentation in HTML format. Note that
    543   this requires that Sage be built first, so it will automatically run
    544   ``make build`` first. Thus running ``make doc`` is equivalent to
    545   running ``make``.
     803- ``make doc`` builds Sage's documentation in HTML format.
     804  Note that this requires that Sage be built first, so it will automatically
     805  run ``make build`` first.
     806  Thus, running ``make doc`` is equivalent to running ``make``.
    546807
    547808- ``make doc-pdf`` builds Sage's documentation in PDF format. This also
    548809  requires that Sage be built first, so it will automatically run ``make
    549810  build``.
    550811
    551812- ``make build-serial`` builds the components of Sage serially, rather
    552   than in parallel (parallel building is the default). Running ``make
    553   build-serial`` is equivalent to setting the environment variable
    554   :envvar:`SAGE_PARALLEL_SPKG_BUILD` to "no" -- see below for
     813  than in parallel (parallel building is the default).
     814  Running ``make build-serial`` is equivalent to setting the environment
     815  variable :envvar:`SAGE_PARALLEL_SPKG_BUILD` to "no" -- see below for
    555816  information about this variable.
    556817
    557 - ``make ptest`` and ``make ptestlong``: these first build Sage and its
    558   html documentation, if necessary, and then run Sage's test suite. The
    559   second version runs more tests, and so it takes longer. The "p" in
    560   "ptest" stands for "parallel": tests are run in parallel. If you want
    561   to run tests serially, you can use ``make test`` or ``make testlong``
    562   instead.
     818- ``make ptest`` and ``make ptestlong``: these run Sage's test suite.
     819  The first version skips tests that needs more than a few seconds to complete
     820  and those which depends on optional packages or additional software.
     821  The second version includes them the former, and so it takes longer.
     822  The "p" in ``ptest`` stands for "parallel": tests are run in parallel.
     823  If you want to run tests serially, you can use ``make test`` or
     824  ``make testlong`` instead.
     825  If you want to run tests depending on optional packages and additional
     826  software, you can use ``make testalll``, ``make ptestall``,
     827  ``make testalllong``, or ``make ptestalllong``.
    563828
    564 - ``make distclean`` restores the Sage directory to its state before
    565   doing any building: it is equivalent to deleting the entire Sage
    566   directory and unpacking the source tarfile.
     829- ``make distclean`` restores the Sage directory to its state before doing any
     830  building: it is equivalent to deleting the entire Sage's home directory and
     831  unpacking the source tarfile again.
     832
     833.. _section_envvar:
    567834
    568835Environment variables
    569836---------------------
    570837
    571838Sage uses several environment variables to control its build process.
    572 Most users won't need to set any of these: the build process just
    573 works on many platforms.  (Note though that setting :envvar:`MAKE`, as
    574 described below, can significantly speed up the process.)  Building
    575 Sage involves building about 100 packages, each of which has its own
     839Most users won't need to set any of these: the build process just works on many
     840platforms.
     841(Note though that setting :envvar:`MAKE`, as described below, can significantly
     842speed up the process.)
     843Building Sage involves building about 100 packages, each of which has its own
    576844compilation instructions.
    577845
    578 Here are some of the more commonly used variables affecting the build
    579 process:
     846Here are some of the more commonly used variables affecting the build process:
    580847
    581 - :envvar:`MAKE` - one useful setting for this variable when building
    582   Sage is ``MAKE='make -jNUM'`` to tell the "make" program to
    583   run NUM jobs in parallel when building.  Some people advise using
    584   more jobs than there are CPU cores, at least if the system is not
    585   heavily loaded and has plenty of RAM; for example, a good setting
    586   for NUM might be between 1 and 1.5 times the number of cores.  In
    587   addition, the "-l" option sets a load limit: ``MAKE='make -j4
    588   -l5.5``, for example, tells "make" to try to use four jobs, but to
    589   not start more than one job if the system load average is above 5.5.
    590   See the manual page for GNU make: `Command-line options
     848- :envvar:`MAKE` - one useful setting for this variable when building Sage is
     849  ``MAKE='make -jNUM'`` to tell the ``make`` program to run ``NUM`` jobs in
     850  parallel when building.
     851  Some people advise using more jobs than there are CPU cores, at least if the
     852  system is not heavily loaded and has plenty of RAM; for example, a good
     853  setting for ``NUM`` might be between 1 and 1.5 times the number of cores.
     854  In addition, the ``-l`` option sets a load limit: ``MAKE='make -j4 -l5.5``,
     855  for example, tells ``make`` to try to use four jobs, but to not start more
     856  than one job if the system load average is above 5.5.
     857  See the manual page for GNU ``make``: `Command-line options
    591858  <http://www.gnu.org/software/make/manual/make.html#Options-Summary>`_
    592859  and `Parallel building
    593860  <http://www.gnu.org/software/make/manual/make.html#Parallel>`_.
    594861
    595862  .. warning::
    596863
    597      Some users on single-core OS X machines have reported problems
    598      when building Sage with ``MAKE='make -jNUM'`` with NUM greater
    599      than one.
     864      Some users on single-core OS X machines have reported problems when
     865      building Sage with ``MAKE='make -jNUM'`` with ``NUM`` greater than one.
    600866
    601 - :envvar:`SAGE_NUM_THREADS` - if this is set to a number, then when
    602   building the documentation, parallel doctesting, or running ``sage
    603   -b``, use this many threads.  If this is not set, then determine the
    604   number of threads using the value of the :envvar:`MAKE` (see above)
    605   or :envvar:`MAKEFLAGS` environment variables.  If none of these
    606   specifies a number of jobs, use 1 thread (except for parallel
    607   testing: there we use a default of the number of CPU cores, with a
     867- :envvar:`SAGE_NUM_THREADS` - if set to a number, then when building the
     868  documentation, parallel doctesting, or running ``sage -b``, use this many
     869  threads.
     870  If this is not set, then determine the number of threads using the value of
     871  the :envvar:`MAKE` (see above) or :envvar:`MAKEFLAGS` environment variables.
     872  If none of these specifies a number of jobs, use one thread (except for
     873  parallel testing: there we use a default of the number of CPU cores, with a
    608874  maximum of 8 and a minimum of 2).
    609875
    610 - :envvar:`SAGE_PARALLEL_SPKG_BUILD` - if this is set to "no", then
    611   build spkgs serially rather than in parallel.  If this is "no", then
    612   each spkg may still take advantage of the setting of :envvar:`MAKE`
    613   to build using multiple jobs, but the spkgs will be built one at a
    614   time.  Alternatively, run "make build-serial" which sets this
    615   environment variable for you.
     876- :envvar:`SAGE_PARALLEL_SPKG_BUILD` - if set to ``no``, then build spkgs
     877  serially rather than in parallel.
     878  If this is set to ``no``, then each spkg may still take advantage of the setting
     879  of :envvar:`MAKE` to build using multiple jobs, but the spkgs will be built
     880  one at a time.
     881  Alternatively, run ``make build-serial`` which sets this environment
     882  variable for you.
    616883
    617 - :envvar:`SAGE_CHECK` - if this is set to "yes", then during the
    618   build process and when running ``sage -i ...`` or ``sage -f ...``,
    619   run the test suite for each package which has one.  See also
    620   :envvar:`SAGE_CHECK_PACKAGES`.
     884- :envvar:`SAGE_CHECK` - if set to ``yes``, then during the build process,
     885  and when running ``sage -i <package-name>`` or ``sage -f <package-name>``,
     886  run the test suite for each package which has one.
     887  See also :envvar:`SAGE_CHECK_PACKAGES`.
    621888
    622 - :envvar:`SAGE_CHECK_PACKAGES` - If :envvar:`SAGE_CHECK` is set to
    623   "yes", then the default bahavior is to run test suites for all spkgs
    624   which contain them.  If :envvar:`SAGE_CHECK_PACKAGES` is set, it
    625   should be a comma-separated list of strings of the form
    626   ``pkg-name`` or ``!pkg-name``.  An entry ``pkg-name`` means to run
    627   the test suite for the named package regardless of the setting of
    628   :envvar:`SAGE_CHECK`.  An entry ``!pkg-name`` means to skip its test
    629   suite.  So if this is set to ``mpir,!python``, then always run the
    630   test suite for MPIR, but always skip the test suite for Python.
     889- :envvar:`SAGE_CHECK_PACKAGES` - if :envvar:`SAGE_CHECK` is set to ``yes``,
     890  then the default behavior is to run test suites for all spkgs which contain
     891  them.
     892  If :envvar:`SAGE_CHECK_PACKAGES` is set, it should be a comma-separated list
     893  of strings of the form ``package-name`` or ``!package-name``.
     894  An entry ``package-name`` means to run the test suite for the named package
     895  regardless of the setting of :envvar:`SAGE_CHECK`.
     896  An entry ``!package-name`` means to skip its test suite.
     897  So if this is set to ``mpir,!python``, then always run the test suite for
     898  MPIR, but always skip the test suite for Python.
    631899
    632900  .. note::
    633901
    634       As of this writing (Sage 5.0), the test suite for the Python
    635       spkg fails on most platforms. So when this variable is empty or
    636       unset, Sage uses a default of ``!python``.
     902     As of this writing (April 2013, Sage 5.8), the test suite for the Python
     903     spkg fails on most platforms.
     904     So when this variable is empty or unset, Sage uses a default of
     905     ``!python``.
    637906
    638 - :envvar:`SAGE64` - Set this to "yes" to build a 64-bit binary on platforms
    639   which default to 32-bit, even though they can build 64-bit binaries. 
    640   It adds the compiler flag
    641   -m64 when compiling programs.  The SAGE64 variable is mainly of use
    642   on OS X (pre 10.6), Solaris and OpenSolaris, though it will add
    643   the -m64 on any operating system. If you are running version 10.6 of
    644   OS X on a 64-bit machine, then Sage will automatically build a
    645   64-bit binary, so this variable does not need setting.
     907- :envvar:`SAGE64` - if set to ``yes``, then build a 64-bit binary on platforms
     908  which default to 32-bit, even though they can build 64-bit binaries.
     909  It adds the compiler flag ``-m64`` when compiling programs.
     910  The :envvar:`SAGE64` variable is mainly of use on OS X (pre 10.6), Solaris
     911  and OpenSolaris, though it will add the ``-m64`` flag on any operating
     912  system.
     913  If you are running Linux or version 10.6 or later of OS X on a 64-bit
     914  machine, then Sage will automatically build a 64-bit binary, so this
     915  variable does not need to be set.
    646916
    647 - :envvar:`CFLAG64` - default value "-m64".  If Sage detects that it
    648   should build a 64-bit binary, then it uses this flag when compiling
    649   C code.  Modify it if necessary for your system and C compiler.
    650   This should not be necessary on most systems -- this flag will
    651   typically be set automatically, based on the setting of
    652   :envvar:`SAGE64`, for example.
     917- :envvar:`CFLAG64` - default value ``-m64``.
     918  If Sage detects that it should build a 64-bit binary, then it uses this flag
     919  when compiling C code.
     920  Modify it if necessary for your system and C compiler.
     921  This should not be necessary on most systems -- this flag will typically be
     922  set automatically, based on the setting of :envvar:`SAGE64`, for example.
    653923
    654 - :envvar:`SAGE_INSTALL_GCC` - by default, Sage will automatically
    655   detect whether to install the
    656   `GNU Compiler Collection (GCC) <http://gcc.gnu.org/>`_
    657   package or not (depending on whether C, C++ and Fortran compilers
    658   are present and the versions of those compilers).  Setting
    659   ``SAGE_INSTALL_GCC=yes`` will force Sage to install GCC.
    660   Setting ``SAGE_INSTALL_GCC=no`` will prevent Sage from installing
    661   GCC.
     924- :envvar:`SAGE_INSTALL_GCC` - by default, Sage will automatically detect
     925  whether to install the `GNU Compiler Collection (GCC) <http://gcc.gnu.org/>`_
     926  package or not (depending on whether C, C++ and Fortran compilers are present
     927  and the versions of those compilers).
     928  Setting ``SAGE_INSTALL_GCC=yes`` will force Sage to install GCC.
     929  Setting ``SAGE_INSTALL_GCC=no`` will prevent Sage from installing GCC.
    662930
    663 - :envvar:`SAGE_INSTALL_CCACHE` - by default Sage doesn't install
    664   ccache, however by setting ``SAGE_INSTALL_CCACHE=yes`` Sage will
    665   install ccache. Because the Sage distribution is quite large, the
    666   maximum cache is set to 4G. This can be changed by running
    667   ``sage -sh -c "ccache --max-size=SIZE"``, where ``SIZE`` is specified
    668   in gigabytes, megabytes, or kilobytes by appending a G, M, or K.
     931- :envvar:`SAGE_INSTALL_CCACHE` - by default Sage doesn't install ccache,
     932  however by setting ``SAGE_INSTALL_CCACHE=yes`` Sage will install ccache.
     933  Because the Sage distribution is quite large, the maximum cache is set to 4G.
     934  This can be changed by running ``sage -sh -c "ccache --max-size=SIZE"``,
     935  where ``SIZE`` is specified in gigabytes, megabytes, or kilobytes by
     936  appending a "G", "M", or "K".
    669937
    670   Sage does not include the sources for ccache since it is an optional
    671   package. Because of this, it is necessary to have an internet
    672   connection while building Sage with ccache, so that Sage can pull
    673   down the necessary sources.
     938  Sage does not include the sources for ccache since it is an optional package.
     939  Because of this, it is necessary to have an Internet connection while
     940  building ccache for Sage, so that Sage can pull down the necessary
     941  sources.
    674942
    675 - :envvar:`SAGE_DEBUG` - enable debugging support. There are three
    676   different values:
     943- :envvar:`SAGE_DEBUG` - controls debugging support.
     944  There are three different possible values:
    677945
    678   * Not set (or set to anything else than "yes" or "no"): Build
    679     binaries with debugging symbols, but no special debug builds. This
    680     is the default. There is no performance impact, only additional
    681     disk space is used.
     946  * Not set (or set to anything else than "yes" or "no"): build binaries with
     947    debugging symbols, but no special debug builds.
     948    This is the default.
     949    There is no performance impact, only additional disk space is used.
    682950
    683   * ``SAGE_DEBUG=no``: no means no debugging symbols (that is, no
     951  * ``SAGE_DEBUG=no``: ``no`` means no debugging symbols (that is, no
    684952    ``gcc -g``), which saves some disk space.
    685953
    686   * ``SAGE_DEBUG=yes``: build debug versions if possible (in
    687     particular, Python is built with additional debugging turned on
    688     and Singular is built with a different memory manager). These will
    689     be notably slower but, for example, make it much easier to
     954  * ``SAGE_DEBUG=yes``: build debug versions if possible (in particular,
     955    Python is built with additional debugging turned on and Singular is built
     956    with a different memory manager).
     957    These will be notably slower but, for example, make it much easier to
    690958    pinpoint memory allocation problems.
    691959
    692 - :envvar:`SAGE_SPKG_LIST_FILES` - Set this to "yes" to enable
    693   verbose extraction of tar files, i.e. Sage's spkg files. Since
    694   some spkgs contain a huge number of files such that the log files
    695   get very large and harder to search (and listing the contained
    696   files is usually less valuable), we decided to turn this off
    697   by default. This variable affects builds of Sage with ``make``
    698   (and ``sage --upgrade``) as well as the manual installation of
    699   individual spkgs with e.g. ``sage -i``.
     960- :envvar:`SAGE_SPKG_LIST_FILES` - if set to ``yes``, then enable verbose
     961  extraction of tar files, i.e. Sage's spkg files.
     962  Since some spkgs contain such a huge number of files that the log files
     963  get very large and harder to search (and listing the contained files is
     964  usually less valuable), we decided to turn this off by default.
     965  This variable affects builds of Sage with ``make`` (and ``sage --upgrade``)
     966  as well as the manual installation of individual spkgs with e.g. ``sage -i``
     967  or ``sage -f``.
    700968
    701 - :envvar:`SAGE_SPKG_INSTALL_DOCS` - Set this to "yes" to install
     969- :envvar:`SAGE_SPKG_INSTALL_DOCS` - if set to ``yes``, then install
    702970  package-specific documentation to
    703971  :file:`$SAGE_ROOT/local/share/doc/PACKAGE_NAME/` when an spkg is
    704   installed.  This option may not be supported by all spkgs.  Some
    705   spkgs might also assume that certain programs are available on the
     972  installed.
     973  This option may not be supported by all spkgs.
     974  Some spkgs might also assume that certain programs are available on the
    706975  system (for example, ``latex`` or ``pdflatex``).
    707976
    708 - :envvar:`SAGE_DOC_MATHJAX` - By default, any LaTeX code in Sage's
    709   documentation is processed by MathJax. If this variable is set to
    710   "no", then MathJax is not used -- instead, math is processed using
    711   LaTeX and converted by dvipng to image files, and then those files
    712   are included into the documentation. Typically, building the
    713   documentation using LaTeX and dvipng takes longer and uses more
    714   memory and disk space than using MathJax.
     977- :envvar:`SAGE_DOC_MATHJAX` - by default, any LaTeX code in Sage's
     978  documentation is processed by MathJax.
     979  If this variable is set to ``no``, then MathJax is not used -- instead,
     980  math is processed using LaTeX and converted by dvipng to image files,
     981  and then those files are included into the documentation.
     982  Typically, building the documentation using LaTeX and dvipng takes longer
     983  and uses more memory and disk space than using MathJax.
    715984
    716 - :envvar:`SAGE_BUILD_DIR` - the default behavior is to build each
    717   spkg in a subdirectory of :file:`$SAGE_ROOT/spkg/build/`; for
    718   example, build :file:`atlas-3.8.3.p12.spkg` in the directory
    719   :file:`$SAGE_ROOT/spkg/build/atlas-3.8.3.p12/`.  If this variable is
    720   set, build in :file:`$SAGE_BUILD_DIR/atlas-3.8.3.p12/`
    721   instead.  If the directory :file:`$SAGE_BUILD_DIR` does not
    722   exist, it is created.  As of this writing (Sage 4.8), when building
    723   the standard Sage packages, this may require 1.5 gigabytes of free
    724   space in this directory (or more if :envvar:`SAGE_KEEP_BUILT_SPKGS`
    725   is "yes" -- see below); the exact amount of required space varies
    726   from platform to platform.  For example, the block size of the file
    727   system will affect the amount of space used, since some spkgs
    728   contain many small files.
     985- :envvar:`SAGE_BUILD_DIR` - the default behavior is to build each spkg in a
     986  subdirectory of :file:`$SAGE_ROOT/spkg/build/`; for example, build
     987  :file:`atlas-3.8.3.p12.spkg` in the directory
     988  :file:`$SAGE_ROOT/spkg/build/atlas-3.8.3.p12/`.
     989  If this variable is set, then build in
     990  :file:`$SAGE_BUILD_DIR/atlas-3.8.3.p12/` instead.
     991  If the directory :file:`$SAGE_BUILD_DIR` does not exist, it is created.
     992  As of this writing (Sage 4.8), when building the standard Sage packages,
     993  1.5 gigabytes of free space are required in this directory (or more if
     994  ``SAGE_KEEP_BUILT_SPKGS=yes`` -- see below); the exact amount of required
     995  space varies from platform to platform.
     996  For example, the block size of the file system will affect the amount of
     997  space used, since some spkgs contain many small files.
    729998
    730999  .. warning::
    7311000
    732     The variable :envvar:`SAGE_BUILD_DIR` must be set to the full
    733     path name of either an existing directory for which the user has write
    734     permissions, or to the full path name of a nonexistent directory
    735     which the user has permission to create.  The path name must
    736     contain no spaces.
     1001      The variable :envvar:`SAGE_BUILD_DIR` must be set to the full path name
     1002      of either an existing directory for which the user has write permissions,
     1003      or to the full path name of a nonexistent directory which the user has
     1004      permission to create.
     1005      The path name must contain **no spaces**.
    7371006
    738 - :envvar:`SAGE_KEEP_BUILT_SPKGS` - the default behavior is to delete
    739   each build directory -- the appropriate subdirectory of
    740   :file:`$SAGE_ROOT/spkg/build` or :file:`$SAGE_BUILD_DIR` --
    741   after each spkg is successfully built.  The subdirectory is not
    742   deleted if there were errors installing the spkg.  Set this variable
    743   to "yes" to keep the subdirectory regardless.  Furthermore, if you
    744   install an spkg for which there is already a corresponding
    745   subdirectory, for example left over from a previous build, then the
    746   default behavior is to delete that old subdirectory.  If this
    747   variable is set to "yes", then the old subdirectory is moved to
    748   :file:`$SAGE_ROOT/spkg/build/old/` (or
    749   :file:`$SAGE_BUILD_DIR/old`), overwriting any already
    750   existing file or directory with the same name.
     1007- :envvar:`SAGE_KEEP_BUILT_SPKGS` - the default behavior is to delete each
     1008  build directory -- the appropriate subdirectory of
     1009  :file:`$SAGE_ROOT/spkg/build` or :file:`$SAGE_BUILD_DIR` -- after each spkg
     1010  is successfully built, and to keep it if there were errors installing the
     1011  spkg.
     1012  Set this variable to ``yes`` to keep the subdirectory regardless.
     1013  Furthermore, if you install an spkg for which there is already a
     1014  corresponding subdirectory, for example left over from a previous build,
     1015  then the default behavior is to delete that old subdirectory.
     1016  If this variable is set to ``yes``, then the old subdirectory is moved to
     1017  :file:`$SAGE_ROOT/spkg/build/old/` (or :file:`$SAGE_BUILD_DIR/old`),
     1018  overwriting any already existing file or directory with the same name.
    7511019
    7521020  .. note::
    7531021
    754      After a full build of Sage (as of version 4.8), these
    755      subdirectories can take up to 6 gigabytes of storage, in total,
    756      depending on the platform and the block size of the file system.
    757      If you always set this variable to "yes", it can take even more
    758      space: rebuilding every spkg would use double the amount of
    759      space, and any upgrades to spkgs would create still more
    760      directories, using still more space.
     1022      After a full build of Sage (as of version 4.8), these subdirectories can
     1023      take up to 6 gigabytes of storage, in total, depending on the platform
     1024      and the block size of the file system.
     1025      If you always set this variable to ``yes``, it can take even more space:
     1026      rebuilding every spkg would use double the amount of space, and any
     1027      upgrades to spkgs would create still more directories, using still more
     1028      space.
    7611029
    7621030  .. note::
    7631031
    764      In an existing Sage installation, running ``sage -i -s new.spkg``
    765      or ``sage -f -s new.spkg`` installs the spkg ``new.spkg`` and
    766      keeps the corresponding build directory; thus setting
    767      :envvar:`SAGE_KEEP_BUILT_SPKGS` to "yes" mimics this behavior
    768      when building Sage from scratch or when installing individual
    769      spkgs.  So you can set this variable to "yes" instead of using
    770      the ``-s`` flag for ``sage -i`` or ``sage -f``.
     1032      In an existing Sage installation, running ``sage -i -s <package-name>``
     1033      or ``sage -f -s <package-name>`` installs the spkg ``<package-name>`` and
     1034      keeps the corresponding build directory; thus setting
     1035      :envvar:`SAGE_KEEP_BUILT_SPKGS` to ``yes`` mimics this behavior when
     1036      building Sage from scratch or when installing individual spkgs.
     1037      So you can set this variable to ``yes`` instead of using the ``-s`` flag
     1038      for ``sage -i`` and ``sage -f``.
    7711039
    772 - :envvar:`SAGE_FAT_BINARY` - to prepare a binary distribution that
    773   will run on the widest range of target machines, set this variable
    774   to "yes" before building Sage::
     1040- :envvar:`SAGE_FAT_BINARY` - to prepare a binary distribution that will run
     1041  on the widest range of target machines, set this variable to ``yes`` before
     1042  building Sage::
    7751043
    7761044      export SAGE_FAT_BINARY="yes"
    7771045      make
    7781046      ./sage --bdist x.y.z-fat
    7791047
    780 Variables to set if you're trying to build Sage with an unusual setup,
    781 e.g., an unsupported machine or an unusual compiler:
     1048Variables to set if you're trying to build Sage with an unusual setup, e.g.,
     1049an unsupported machine or an unusual compiler:
    7821050
    783 - :envvar:`SAGE_PORT` - if you try to build Sage on a platform which
    784   is recognized as being unsupported (e.g. AIX, or
    785   HP-UX), or with a compiler which is unsupported (anything except
    786   gcc), you will see a message saying something like ::
     1051- :envvar:`SAGE_PORT` - if you try to build Sage on a platform which is
     1052  recognized as being unsupported (e.g. AIX, or HP-UX), or with a compiler
     1053  which is unsupported (anything except GCC), you will see a message saying
     1054  something like::
    7871055
    788         You are attempting to build Sage on IBM's AIX operating system,
    789         which is not a supported platform for Sage yet. Things may or
    790         may not work. If you would like to help port Sage to AIX,
    791         please join the sage-devel discussion list - see
    792         http://groups.google.com/group/sage-devel
    793         The Sage community would also appreciate any patches you submit.
    794        
    795         To get past this message, export the variable SAGE_PORT to
    796         something non-empty.
     1056      You are attempting to build Sage on IBM's AIX operating system,
     1057      which is not a supported platform for Sage yet. Things may or
     1058      may not work. If you would like to help port Sage to AIX,
     1059      please join the sage-devel discussion list -- see
     1060      http://groups.google.com/group/sage-devel
     1061      The Sage community would also appreciate any patches you submit.
    7971062
    798   If this is the situation, follow the directions: set
    799   :envvar:`SAGE_PORT` to something non-empty (and expect to run into
    800   problems).
     1063      To get past this message and try building Sage anyway,
     1064      export the variable SAGE_PORT to something non-empty.
    8011065
    802 - :envvar:`SAGE_USE_OLD_GCC` - the Sage build process requires gcc with
    803   a version number of at least 4.0.1.  If the most recent version of gcc
    804   on your system is the older 3.4.x series and you want to build with
    805   ``SAGE_INSTALL_GCC=no``, then set :envvar:`SAGE_USE_OLD_GCC` to
    806   something non-empty. Expect the build to fail in this case.
     1066  If this is case and you want to try to build Sage anyway, follow the
     1067  directions: set :envvar:`SAGE_PORT` to something non-empty (and expect to
     1068  run into problems).
     1069
     1070- :envvar:`SAGE_USE_OLD_GCC` - the Sage build process requires GCC with a
     1071  version number of at least 4.0.1.
     1072  If the most recent version of GCC on your system is the older 3.4.x series
     1073  and you want to build with ``SAGE_INSTALL_GCC=no``, then set
     1074  :envvar:`SAGE_USE_OLD_GCC` to something non-empty.
     1075  Expect the build to fail in this case.
    8071076
    8081077Environment variables dealing with specific Sage packages:
    8091078
    810 - :envvar:`SAGE_ATLAS_ARCH` - if you are compiling ATLAS (in
    811   particular, if :envvar:`SAGE_ATLAS_LIB` is not set), you can use
    812   this environment variable to set a particular architecture and
    813   instruction set architecture. The syntax is
    814   ``SAGE_ATLAS_ARCH=arch[,isaext1][,isaext2]...[,isaextN]``. While
    815   ATLAS comes with precomputed timings for a variety of CPUs, it only
    816   uses them if it finds an exact match. Otherwise, ATLAS runs through
    817   a lengthy automated tuning process in order to optimize performance
    818   for your particular system. You drastically reduce the total Sage
    819   compile time if you manually select a suitable architecture. It is
    820   recommended to specify a suitable architecture on laptops or other
    821   systems with CPU throttling or if you want to distribute the
    822   binaries. Available architectures are
     1079- :envvar:`SAGE_ATLAS_ARCH` - if you are compiling ATLAS (in particular,
     1080  if :envvar:`SAGE_ATLAS_LIB` is not set), you can use this environment
     1081  variable to set a particular architecture and instruction set extension.
     1082  The syntax is ``SAGE_ATLAS_ARCH=arch[,isaext1][,isaext2]...[,isaextN]``.
     1083  While ATLAS comes with precomputed timings for a variety of CPUs, it only
     1084  uses them if it finds an exact match.
     1085  Otherwise, ATLAS runs through a lengthy automated tuning process in order
     1086  to optimize performance for your particular system, which can take several
     1087  days on slow and unusual systems.
     1088  You drastically reduce the total Sage compile time if you manually select a
     1089  suitable architecture.
     1090  It is recommended to specify a suitable architecture on laptops or other
     1091  systems with CPU throttling or if you want to distribute the binaries.
     1092  Available architectures are
    8231093
    8241094    ``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``, ``P5``,
    8251095    ``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
     
    8281098    ``IA64Itan``, ``IA64Itan2``, ``USI``, ``USII``, ``USIII``,
    8291099    ``USIV``, ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``
    8301100
    831   and instruction set extensions are 
    832    
     1101  and instruction set extensions are
     1102
    8331103    ``AltiVec``, ``SSE3``, ``SSE2``, ``SSE1``, ``3DNow``.
    8341104
    8351105  In addition, you can also set
    8361106
    837   - ``SAGE_ATLAS_ARCH=fast`` picks defaults for a modern (2-3 year old)
     1107  - ``SAGE_ATLAS_ARCH=fast`` which picks defaults for a modern (2-3 year old)
    8381108    CPU of your processor line, and
    8391109
    840   - ``SAGE_ATLAS_ARCH=base`` picks defaults that should work for a ~10
     1110  - ``SAGE_ATLAS_ARCH=base`` which picks defaults that should work for a ~10
    8411111    year old CPU.
    8421112
    843   For example, 
     1113  For example,
    8441114
    8451115    ``SAGE_ATLAS_ARCH=Corei7,SSE3,SSE2,SSE1``
    8461116
    8471117  would be appropriate for a Core i7 CPU.
    8481118
    849 - :envvar:`SAGE_ATLAS_LIB` - if you have an installation of ATLAS on
    850   your system and you want Sage to use it instead of building and
    851   installing its own version of ATLAS, set this variable to be the
    852   directory containing your ATLAS installation. It should contain the
    853   files :file:`libatlas`, :file:`liblapack`, :file:`libcblas`, and
    854   :file:`libf77blas` with extensions ``.a``, ``.so``, or
    855   ``.dylib``. For backward compatibility, the libraries may also be in
    856   the subdirectory ``SAGE_ATLAS_LIB/lib/``.
     1119- :envvar:`SAGE_ATLAS_LIB` - if you have an installation of ATLAS on your
     1120  system and you want Sage to use it instead of building and installing its
     1121  own version of ATLAS, set this variable to be the directory containing your
     1122  ATLAS installation.
     1123  It should contain the files :file:`libatlas`, :file:`liblapack`,
     1124  :file:`libcblas`, and :file:`libf77blas` with extensions ``.a``, ``.so``, or
     1125  ``.dylib``.
     1126  For backward compatibility, the libraries may also be in the subdirectory
     1127  :file:`SAGE_ATLAS_LIB/lib/`.
    8571128
    858 - :envvar:`SAGE_MATPLOTLIB_GUI` - set this to anything non-empty except
    859   "no", and Sage will attempt to build the graphical backend when it
    860   builds the matplotlib package.
     1129- :envvar:`SAGE_MATPLOTLIB_GUI` - if set to anything non-empty except ``no``,
     1130  then Sage will attempt to build the graphical backend when it builds the
     1131  matplotlib package.
    8611132
    862 - :envvar:`INCLUDE_MPFR_PATCH` - This is used to add a patch to MPFR
    863   to bypass a bug in the memset function affecting sun4v machines with
    864   versions of Solaris earlier than Solaris 10 update 8
    865   (10/09). Earlier versions of Solaris 10 can be patched by applying
    866   Sun patch 142542-01.  Recognized values are:
     1133- :envvar:`INCLUDE_MPFR_PATCH` - this is used to add a patch to MPFR to bypass
     1134  a bug in the memset function affecting sun4v machines with versions of
     1135  Solaris earlier than Solaris 10 update 8 (10/09).
     1136  Earlier versions of Solaris 10 can be patched by applying Sun patch
     1137  142542-01.
     1138  Recognized values are:
    8671139
    868   - ``INCLUDE_MPFR_PATCH=0`` - never include the patch - useful if you
    869     know all sun4v machines Sage will be used are running Solaris
    870     10 update 8 or later, or have been patched with Sun patch
    871     142542-01.
     1140  - ``INCLUDE_MPFR_PATCH=0`` - never include the patch - useful if you know all
     1141    sun4v machines Sage will be used are running Solaris 10 update 8 or later,
     1142    or have been patched with Sun patch 142542-01.
    8721143
    873   - ``INCLUDE_MPFR_PATCH=1`` - always include the patch, so the binary
    874     will work on a sun4v machine, even if created on an older sun4u
    875     machine.
     1144  - ``INCLUDE_MPFR_PATCH=1`` - always include the patch, so the binary will
     1145    work on a sun4v machine, even if created on an older sun4u machine.
    8761146
    877   If this variable is unset, include the patch on sun4v machines only.
     1147  - If this variable is unset, include the patch on sun4v machines only.
    8781148
    879 - :envvar:`SAGE_BINARY_BUILD` - used by the pil package.  If set to
    880   "yes", then force Sage to use the versions of libjpeg, libtiff and
    881   libpng from :file:`$SAGE_ROOT/local/lib`.  Otherwise, allow the use
    882   of the system's versions of these libraries.
     1149- :envvar:`SAGE_BINARY_BUILD` - used by the pil package.
     1150  If set to ``yes``, then force Sage to use the versions of libjpeg, libtiff
     1151  and libpng from :file:`$SAGE_ROOT/local/lib`.
     1152  Otherwise, allow the use of the system's versions of these libraries.
    8831153
    884 - :envvar:`SAGE_PIL_NOTK` - used by the pil package.  If set to "yes",
    885   then disable building TK.  If this is not set, then this should be
    886   dealt with automatically: Sage tries to build the pil package with
    887   TK support enabled, but if it runs into problems, it tries building
    888   again with TK disabled.  So only use this variable to force TK to be
    889   disabled.  (Building the pil package is pretty fast -- less than a
    890   minute on many systems -- so allowing it to build twice is not a
    891   serious issue.)
     1154- :envvar:`SAGE_PIL_NOTK` - used by the pil package.
     1155  If set to ``yes``, then disable building TK.
     1156  If this is not set, then this should be dealt with automatically: Sage tries
     1157  to build the pil package with TK support enabled, but if it runs into
     1158  problems, it tries building again with TK disabled.
     1159  So only use this variable to force TK to be disabled.
     1160  (Building the pil package is pretty fast -- less than a minute on many
     1161  systems -- so allowing it to build twice is not a serious issue.)
    8921162
    8931163Some standard environment variables which are used by Sage:
    8941164
    895 - :envvar:`CC` - while some programs allow you to use this to specify
    896   your C compiler, **not every Sage package recognizes this**.
    897   If GCC is installed within Sage, :envvar:`CC` is ignored and Sage's
    898   ``gcc`` is used instead.
     1165- :envvar:`CC` - while some programs allow you to use this to specify your C
     1166  compiler, **not every Sage package recognizes this**.
     1167  If GCC is installed within Sage, :envvar:`CC` is ignored and Sage's ``gcc``
     1168  is used instead.
    8991169
    900 - :envvar:`CXX` - similarly, this will set the C++ compiler for some
    901   Sage packages, and similarly, using it is likely quite risky.
    902   If GCC is installed within Sage, :envvar:`CXX` is ignored and Sage's
    903   ``g++`` is used instead.
     1170- :envvar:`CPP` - similarly, this will set the C preprocessor for some Sage
     1171  packages, and similarly, using it is likely quite risky.
     1172  If GCC is installed within Sage, :envvar:`CPP` is ignored and Sage's ``cpp``
     1173  is used instead.
     1174
     1175- :envvar:`CXX` - similarly, this will set the C++ compiler for some Sage
     1176  packages, and similarly, using it is likely quite risky.
     1177  If GCC is installed within Sage, :envvar:`CXX` is ignored and Sage's ``g++``
     1178  is used instead.
    9041179
    9051180- :envvar:`FC` - similarly, this will set the Fortran compiler.
    9061181  This is supported by all Sage packages which have Fortran code.
    907   However, for historical reasons, the value is hardcoded during the
    908   initial ``make`` and subsequent changes to ``$FC`` might be ignored
    909   (in which case, the original value will be used instead).
     1182  However, for historical reasons, the value is hardcoded during the initial
     1183  ``make`` and subsequent changes to ``$FC`` might be ignored (in which case,
     1184  the original value will be used instead).
    9101185  If GCC is installed within Sage, :envvar:`FC` is ignored and Sage's
    9111186  ``gfortran`` is used instead.
    9121187
    913 - :envvar:`CFLAGS`, :envvar:`CXXFLAGS` and :envvar:`FCFLAGS` - the
    914   flags for the C compiler, the C++ compiler and the Fortran compiler,
    915   respectively.  The same comments apply to these: setting them may
    916   cause problems, because they are not universally respected among the
    917   Sage packages.
     1188- :envvar:`CFLAGS`, :envvar:`CXXFLAGS` and :envvar:`FCFLAGS` - the flags for
     1189  the C compiler, the C++ compiler and the Fortran compiler, respectively.
     1190  The same comments apply to these: setting them may cause problems, because
     1191  they are not universally respected among the Sage packages.
    9181192
    919 The following Fortran-related environment variables are **deprecated**
    920 since Sage 5.3 and support for these will likely be removed.
     1193The following Fortran-related environment variables are **deprecated** since
     1194Sage 5.3 and support for these will likely be removed.
    9211195They are still recognized, but should not be used for new setups.
    9221196
    9231197- :envvar:`SAGE_FORTRAN` - the path to the Fortran compiler.
    9241198  Deprecated, use :envvar:`FC` instead.
    9251199
    9261200- :envvar:`SAGE_FORTRAN_LIB` - the path to the Fortran runtime library.
    927   Normally, you don't need to set this. If you really need to,
    928   you can add the directory containing the library to
     1201  Normally, you don't need to set this.
     1202  If you really need to, you can add the directory containing the library to
    9291203  :envvar:`LIBRARY_PATH` and/or :envvar:`LD_LIBRARY_PATH`.
    9301204
    9311205Sage uses the following environment variables when it runs:
    9321206
    933 - :envvar:`DOT_SAGE` - this is the directory, to which the user has
    934   read and write access, where Sage stores a number of files.  The
    935   default location is ``~/.sage/``, but you can change that by setting
    936   this variable.
     1207- :envvar:`DOT_SAGE` - this is the directory, to which the user has read and
     1208  write access, where Sage stores a number of files.
     1209  The default location is :file:`$HOME/.sage/`.
    9371210
    938 - :envvar:`SAGE_STARTUP_FILE` - a file including commands to be
    939   executed every time Sage starts.  The default value is
    940   ``$DOT_SAGE/init.sage``.
     1211- :envvar:`SAGE_STARTUP_FILE` - a file including commands to be executed every
     1212  time Sage starts.
     1213  The default value is :file:`$DOT_SAGE/init.sage`.
    9411214
    9421215- :envvar:`SAGE_SERVER` - if you want to install a Sage package using
    943   ``sage -i PKG_NAME``, Sage downloads the file from the web, using
    944   the address ``http://www.sagemath.org/`` by default, or the address
    945   given by :envvar:`SAGE_SERVER` if it is set.  If you wish to set up
    946   your own server, then note that Sage will search the directories
    947   ``SAGE_SERVER/packages/standard/``,
    948   ``SAGE_SERVER/packages/optional/``,
    949   ``SAGE_SERVER/packages/experimental/``, and
    950   ``SAGE_SERVER/packages/archive/`` for packages.  See the script
    951   :file:`$SAGE_ROOT/spkg/bin/sage-spkg` for the implementation.
     1216  ``sage -i <package-name>``, Sage downloads the file from the web, using the
     1217  address ``http://www.sagemath.org/`` by default, or the address given by
     1218  :envvar:`SAGE_SERVER` if it is set.
     1219  If you wish to set up your own server, then note that Sage will search the
     1220  directories:
    9521221
    953 - :envvar:`SAGE_PATH` - a colon-separated list of directories which
    954   Sage searches when trying to locate Python libraries.
     1222  - ``SAGE_SERVER/packages/standard/``,
     1223  - ``SAGE_SERVER/packages/optional/``,
     1224  - ``SAGE_SERVER/packages/experimental/``,
     1225  - and ``SAGE_SERVER/packages/archive/``
    9551226
    956 - :envvar:`SAGE_BROWSER` - on most platforms, Sage will detect the
    957   command to run a web browser, but if this doesn't seem to work on
    958   your machine, set this variable to the appropriate command.
     1227  for packages.
     1228  See the script :file:`$SAGE_ROOT/spkg/bin/sage-spkg` for the implementation.
    9591229
    960 - :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET` - set this to something
    961   non-empty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before
    962   executing system commands.
     1230- :envvar:`SAGE_PATH` - a colon-separated list of directories which Sage
     1231  searches when trying to locate Python libraries.
    9631232
    964 - :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used
    965   on Mac OS X to set the :envvar:`DYLD_LIBRARY_PATH`.
     1233- :envvar:`SAGE_BROWSER` - on most platforms, Sage will detect the command to
     1234  run a web browser, but if this doesn't seem to work on your machine, set this
     1235  variable to the appropriate command.
     1236
     1237- :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET` - set this to something non-empty to
     1238  force Sage to set the :envvar:`LD_LIBRARY_PATH` variable before executing
     1239  system commands.
     1240
     1241- :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used on OS X to
     1242  set the :envvar:`DYLD_LIBRARY_PATH` variable.
    9661243
    9671244- :envvar:`SAGE_CBLAS` - used in the file
    968   :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`.  Set this to the
    969   base name of the BLAS library file on your system if you want to
    970   override the default setting.  That is, if the relevant file is
    971   called :file:`libcblas_new.so` or :file:`libcblas_new.dylib`, then
    972   set this to "cblas_new".
     1245  :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`.
     1246  Set this to the base name of the BLAS library file on your system if you want
     1247  to override the default setting.
     1248  That is, if the relevant file is called :file:`libcblas_new.so` or
     1249  :file:`libcblas_new.dylib`, then set this to ``cblas_new``.
    9731250
    9741251Sage overrides the user's settings of the following variables:
    9751252
    976 - :envvar:`MPLCONFIGDIR` - ordinarily, this variable lets the user set
    977   their matplotlib config directory.  Due to incompatibilies in the
    978   contents of this directory among different versions of matplotlib,
    979   Sage overrides the user's setting, defining it instead to be
    980   ``$DOT_SAGE/matplotlib-VER``,   with "VER" replaced by the
     1253- :envvar:`MPLCONFIGDIR` - ordinarily, this variable lets the user set their
     1254  matplotlib config directory.
     1255  Due to incompatibilies in the contents of this directory among different
     1256  versions of matplotlib, Sage overrides the user's setting, defining it
     1257  instead to be :file:`$DOT_SAGE/matplotlib-VER`, with ``VER`` replaced by the
    9811258  current matplotlib version number.
    9821259
    9831260Variables dealing with doctesting:
    9841261
    985 - :envvar:`SAGE_TIMEOUT` - used for Sage's doctesting: the number of
    986   seconds to allow a doctest before timing it out.  If this isn't set,
    987   the default is 360 seconds (6 minutes).
    988  
    989 - :envvar:`SAGE_TIMEOUT_LONG` - used for Sage's doctesting: the number
    990   of seconds to allow a doctest before timing it out, if tests are run
    991   using ``sage -t --long``.  If this isn't set, the default is 1800
    992   seconds (30 minutes).
     1262- :envvar:`SAGE_TIMEOUT` - used for Sage's doctesting: the number of seconds
     1263  to allow a doctest before timing it out.
     1264  If this isn't set, the default is 360 seconds (6 minutes).
    9931265
    994 - :envvar:`SAGE_PICKLE_JAR` - if you want to update the the standard
    995   pickle jar, set this to something non-empty and run the doctest
    996   suite.  See the documentation for the functions :func:`picklejar`
    997   and :func:`unpickle_all` in
    998   :file:`SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
     1266- :envvar:`SAGE_TIMEOUT_LONG` - used for Sage's doctesting: the number of
     1267  seconds to allow a doctest before timing it out, if tests are run using
     1268  ``sage -t --long``.
     1269  If this isn't set, the default is 1800 seconds (30 minutes).
     1270
     1271- :envvar:`SAGE_PICKLE_JAR` - if you want to update the the standard pickle
     1272  jar, set this to something non-empty and run the doctest suite.
     1273  See the documentation for the functions :func:`picklejar` and
     1274  :func:`unpickle_all` in
     1275  :file:`$SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
    9991276  `here (picklejar)
    10001277  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.picklejar>`_
    10011278  and `here (unpickle_all)
    10021279  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.unpickle_all>`_.
    10031280
    1004 ..
    1005   THIS INDENTED BLOCK IS A COMMENT.  FIX IT ONCE WE UNDERSTAND
    1006   THESE VARIABLES.
     1281.. comment:
     1282    ***************************************************************************
     1283    FIX THIS!
    10071284
    1008   Variables dealing with valgrind and friends:
     1285    Variables dealing with valgrind and friends:
    10091286
    1010   - :envvar:`SAGE_TIMEOUT_VALGRIND` - used for Sage's doctesting: the
    1011     number of seconds to allow a doctest before timing it out, if tests
    1012     are run using ``??``.  If this isn't set, the default is 1024*1024
    1013     seconds.
     1287    - :envvar:`SAGE_TIMEOUT_VALGRIND` - used for Sage's doctesting: the
     1288      number of seconds to allow a doctest before timing it out, if tests
     1289      are run using ``??``.  If this isn't set, the default is 1024*1024
     1290      seconds.
    10141291
    1015   - :envvar:`SAGE_VALGRIND` - ?
     1292    - :envvar:`SAGE_VALGRIND` - trigger black magic in Python.
    10161293
    1017   - :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`,
    1018     :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS` - flags
    1019     used when using valgrind and one of the tools "memcheck", "massif",
    1020     "cachegrind", or "omega"
     1294    - :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`,
     1295      :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS` - flags
     1296      used when using valgrind and one of the tools "memcheck", "massif",
     1297      "cachegrind", or "omega"
     1298    ***************************************************************************
     1299
    10211300
    10221301Installation in a Multiuser Environment
    10231302---------------------------------------
    10241303
    1025 This section addresses the question of how a system administrator
    1026 can install a single copy of Sage in a multi-user computer
    1027 network.
     1304This section addresses the question of how a system administrator can install
     1305a single copy of Sage in a multi-user computer network.
    10281306
    10291307System-wide install
    10301308~~~~~~~~~~~~~~~~~~~
    10311309
    1032 #. After you build Sage, you may optionally copy or move the entire
    1033    build tree to ``/usr/local`` or another location.  If you do this,
    1034    then you must run ``./sage`` once so that various hard-coded
    1035    locations will get updated.  For this reason, it might be easier to
    1036    simply build Sage in its final location.
     1310#. After building Sage, you may optionally copy or move the entire build tree
     1311   to :file:`/usr/local` or another location.
     1312   If you do this, then you must run ``./sage`` once so that various hardcoded
     1313   locations get updated.
     1314   For this reason, it might be easier to simply build Sage in its final
     1315   location.
    10371316
    1038 #. Make a symbolic link to the ``sage`` script in ``/usr/local/bin``::
     1317#. Make a symbolic link to the ``sage`` script in :file:`/usr/local/bin`::
    10391318
    10401319       ln -s /path/to/sage-x.y.z/sage /usr/local/bin/sage
    10411320
    10421321   Alternatively, copy the Sage script::
    10431322
    10441323       cp /path/to/sage-x.y.z/sage /usr/local/bin/sage
    1045    
    1046    and edit the file ``/usr/local/bin/sage``: ``SAGE_ROOT`` should be
    1047    set to the directory ``/path/to/sage-x.y.z/`` where Sage is
    1048    installed.  It is recommended not to edit the original ``sage``
    1049    script, only the copy in ``/usr/local/bin/sage``.
    10501324
    1051 #. Make sure that all files in the Sage tree are readable by all::
     1325   If you do this, make sure you edit the line::
    10521326
    1053        chmod a+rX -R /usr/local/sage-5.0
     1327       #SAGE_ROOT=/path/to/sage-version
     1328
     1329   at the beginning of the copied ``sage`` script according to the direction
     1330   given there to something like::
     1331
     1332       SAGE_ROOT=<SAGE_ROOT>
     1333
     1334   (note that you have to change ``<SAGE_ROOT>`` above!).
     1335   It is recommended not to edit the original ``sage`` script, only the copy at
     1336   :file:`/usr/local/bin/sage`.
     1337
     1338#. Make sure that all files in the Sage tree are readable by all
     1339   (note that you have to change ``<SAGE_ROOT>`` below!)::
     1340
     1341       chmod a+rX -R <SAGE_ROOT>
    10541342
    10551343#. Optionally, you can test Sage by running::
    10561344
    10571345       make testlong
    1058    
     1346
    10591347   or ``make ptestlong`` which tests files in parallel using multiple
    1060    processes. You can also omit ``long`` to skip tests which take a long
    1061    time.
     1348   processes.
     1349   You can also omit ``long`` to skip tests which take a long time.
     1350
     1351Sagetex
     1352~~~~~~~
     1353
     1354To make SageTeX available to your users, see the instructions for
     1355:ref:`installation in a multiuser environment <sagetex_installation_multiuser>`
     1356.
     1357
    10621358
    10631359Some common problems
    10641360--------------------
     
    10661362ATLAS
    10671363~~~~~
    10681364
    1069 Sometimes the ATLAS spkg can fail to build.  Some things to check for:
     1365Sometimes the ATLAS spkg can fail to build.
     1366Some things to check for:
    10701367
    1071 - Make sure that CPU throttling mode (= power-saving mode) is turned off
     1368- Make sure that CPU throttling mode (i.e. power-saving mode) is turned off
    10721369  when building ATLAS.
    10731370
    1074 - Also, the ATLAS build can fail if the system load is too high, and in
     1371- The ATLAS build can also fail if the system load is too high, and in
    10751372  particular this has been known to happen when building with
    1076   ``MAKE='make -jNUM'`` with NUM large.  If this happens, just try
    1077   running "make" again.  If "make" fails after five or six attempts,
    1078   report your problem to the sage-devel mailing list.
     1373  ``MAKE='make -jNUM'`` with ``NUM`` large.
     1374  If this happens, just try running ``make`` again.
     1375  If ``make`` fails after five or six attempts, report your problem to the
     1376  sage-devel mailing list at http://groups.google.com/group/sage-devel.
    10791377
    1080 Special Notes
    1081 -------------
     1378zn_poly
     1379~~~~~~~
    10821380
    1083 - To make SageTeX available to your users, see the instructions for
    1084   :ref:`installation in a multiuser environment
    1085   <sagetex_installation_multiuser>`.
     1381It has been reported (see :trac:`13947`) that the zn_poly spkg fails to build
     1382on loaded systems, especially on Mac OS X and Cygwin.
     1383If you encounter this problem, you can try to build zn_poly serially before
     1384reissuing ``make``::
    10861385
    1087   **This page was last updated in August 2012 (Sage 5.3).**
     1386    MAKE="make -j1" ./sage -i zn_poly && make
     1387
     1388
     1389**This page was last updated in April 2013 (Sage 5.8).**