Ticket #14465: source.2.patch

File source.2.patch, 99.3 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 4d55d69342b349357e80c6b437f3503911228212
    # 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.
     14It will take your computer a while to compile Sage from the source code,
     15although you don't have to watch.
     16Building Sage from the source code has the major advantage that you have the
     17latest version of Sage with which you can change absolutely any part or the
     18programs on which Sage depends.
     19You can also recompile Sage.
     20Finally, some parts of Sage will be optimised for your particular computer,
     21so will run faster than a binary that you have downloaded.
    2022
    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.
     23Supported platforms
     24-------------------
    3525
    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
     26Sage is supported on a number of `Linux <http://en.wikipedia.org/wiki/Linux>`_,
     27Mac `OS X <http://www.apple.com/macosx/>`_ ,
     28Sun/Oracle `Solaris <http://www.oracle.com/solaris>`_
     29and `OpenSolaris <http://en.wikipedia.org/wiki/OpenSolaris>`_ releases,
     30but Sage is not supported on all versions of Linux, OS X, Solaris or
     31OpenSolaris.
     32Depending on the `operating system <http://en.wikipedia.org/wiki/Operating_system>`_,
     33Sage works with `x86 <http://en.wikipedia.org/wiki/X86>`_,
     34`x86_64 <http://en.wikipedia.org/wiki/X86-64>`_,
     35`PowerPC <http://en.wikipedia.org/wiki/PowerPC>`_
     36or `SPARC <http://en.wikipedia.org/wiki/SPARC>`_ processors.
     37There is no native version of Sage which installs on
     38`Microsoft Windows <http://en.wikipedia.org/wiki/Microsoft_Windows>`_,
     39although Sage can be used on Windows with the aid of a
     40`virtual machine <http://en.wikipedia.org/wiki/Virtual_machine>`_
     41or the `Cygwin <http://cygwin.com/>`_ Linux API layer.
     42Go to http://www.sagemath.org/download-windows.html to download a binary
     43version of Sage for Windows.
     44
     45See http://wiki.sagemath.org/SupportedPlatforms for the full list of platforms
     46on which Sage is supported and the level of support for these systems.
     47You will also find details about
     48`ports <http://en.wikipedia.org/wiki/Computer_port_%28software%29>`_
     49to other operating systems or processors which may be taking place.
     50
     51
     52Prerequisites
     53-------------
     54
     55General requirements
     56~~~~~~~~~~~~~~~~~~~~
     57
     58Your computer comes with at least 3 GB of free disk space running one of the
     59supported versions of an operating system listed at
    3960http://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/>`_).
    4361
    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
     62In addition to standard `POSIX <http://en.wikipedia.org/wiki/POSIX>`_ utilities
     63and a `bash <http://en.wikipedia.org/wiki/Bash_(Unix_shell)>`_-compatible shell,
     64the following standard command-line development tools must be installed on your
     65computer:
    5466
    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
     67- A **C compiler**: GCC version 4.0.1 or newer should work.
     68  Older versions may or may not work.
     69  On Solaris or OpenSolaris systems, the Sun compiler should also work.
     70- **make**: GNU make, version 3.80 or later.
     71- **m4**.
     72- **perl**: version 5.8.0 or later.
     73- **ranlib**.
     74- **tar**: GNU tar version 1.17 or later, or BSD tar.
    6275
    6376Sage also needs a C++ compiler and a Fortran compiler.
    6477However, 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.
     78package, so that C, C++ and Fortran compilers will be built if needed.
     79(You can also use the environment variable :envvar:`SAGE_INSTALL_GCC` to
     80control whether or not to install GCC, see :ref:`section_compilers`.)
     81Nonetheless, you always need some C compiler to build GCC and its
     82prerequisites.
    6983
    70 .. note::
     84Although some of Sage is written in `Python <http://www.python.org/>`_, you do
     85not need Python pre-installed on your computer, since the Sage installation
     86includes virtually everything you need.
    7187
    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 ::
     88After extracting the Sage tarball, the subdirectory :file:`spkg` contains the
     89source distributions for everything on which Sage depends.
     90We emphasize that all of this software is included with Sage, so you do not
     91have to worry about trying to download and install any one of these packages
     92(such as Python, for example) yourself.
    8093
    81         ./sage -i pyopenssl
     94When the Sage installation program is run,
     95it will check that you have each of the above-listed prerequisites,
     96and inform you of any that are missing, or have unsuitable versions.
    8297
    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::
     98System-specific requirements
     99~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    91100
    92         ./sage -i patch openssl  # install patch and openssl
    93         make ssl
     101On recent Debian or Ubuntu systems, the **dpkg-dev** package is needed for
     102`multiarch <http://wiki.debian.org/Multiarch>`_ support.
    94103
    95     Alternatively, if you've already built Sage::
     104On Cygwin, the **lapack** and **liblapack-devel** packages are required to
     105provide ATLAS support as the ATLAS spkg is not built by default.
    96106
    97         ./sage -i openssl
    98         ./sage -f python   # rebuild Python
    99         SAGE_UPGRADING=yes make ssl
     107Installing prerequisites
     108~~~~~~~~~~~~~~~~~~~~~~~~
    100109
    101     The third line will rebuild all parts of Sage that depend on Python;
    102     this can take a while.
     110To check if you have the above prerequisites installed, for example ``perl``,
     111type::
    103112
    104 To check if you have ``perl`` installed, for example, type
     113    command -v perl
     114
     115or::
     116
     117    which perl
     118
     119on the command line. If it gives an error (or returns nothing), then
     120either ``perl`` is not installed, or it is installed but not in your
     121`PATH <http://en.wikipedia.org/wiki/PATH_%28variable%29>`_.
     122
     123On Linux systems (e.g., Ubuntu, Redhat, etc), ``ranlib`` is in the
     124`binutils <http://www.gnu.org/software/binutils/>`_ package.
     125The other programs are usually located in packages with their respective names.
     126Assuming you have sufficient privileges, you can install the ``binutils`` and
     127other necessary components.
     128If you do not have the privileges to do this, ask your system administrator to
     129do this, or build the components from source code.
     130The method of installing additional software varies from distribution to
     131distribution, but on a `Debian <http://www.debian.org/>`_ based system (e.g.
     132`Ubuntu <http://www.ubuntu.com/>`_ or `Mint <http://www.linuxmint.com/>`_),
     133you would use
     134`apt-get <http://en.wikipedia.org/wiki/Advanced_Packaging_Tool>`_::
     135
     136     sudo apt-get install binutils gcc make m4 perl tar
     137
     138to install all general requirements (this was tested on Ubuntu 12.04.2).
     139On other Linux systems, you might use
     140`rpm <http://en.wikipedia.org/wiki/RPM_Package_Manager>`_,
     141`yum <http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified>`_,
     142or other package managers.
     143
     144On OS X systems, you need a recent version of
     145`Command Line Tools <http://developer.apple.com/opensource/>`_.
     146It provides all the above requirements.
     147You can download it for free at
     148http://developer.apple.com/downloads/index.action?=command%20line%20tools
     149provided you registered for a free Apple Developer account at
     150http://developer.apple.com/register/.
     151Alternatively, if you have already installed
     152`Xcode <http://developer.apple.com/xcode/>`_
     153(which at the time of writing is freely available in the Mac App Store,
     154or through http://developer.apple.com/downloads/ provided you registered for an
     155Apple Developer account),
     156you can open Xcode's "Downloads" preference pane and install the command line
     157tools from there.
     158
     159On Solaris, you would use ``pkgadd`` and on OpenSolaris ``ipf`` to install
     160the necessary software.
     161
     162On Cygwin, you would use the ``setup.exe`` program.
     163As on Linux systems ``ranlib`` is provided by the ``binutils`` package.
     164As far as compilers are concerned, you should either install the ``gcc4-core``
     165package alone, or install matching versions of the ``gcc4-core``, ``gcc4-g++``,
     166and ``gcc4-gfortran`` packages to avoid the build of Sage's own GCC.
     167
     168On other systems, check the documentation for your particular operating system.
     169
     170Specific notes for ``make`` and ``tar``
     171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     172
     173On OS X, the BSD ``tar`` supplied will build Sage, so there is no need to
     174install the GNU ``tar``.
     175
     176On Solaris or OpenSolaris, the Sun/Oracle versions of ``make`` and ``tar`` are
     177unsuitable for building Sage.
     178Therefore, you must have the GNU versions of ``make`` and ``tar`` installed and
     179they must be the first ``make`` and ``tar`` in your :envvar:`PATH`.
     180
     181On Solaris 10, a version of GNU ``make`` may be found at :file:`/usr/sfw/bin/gmake`,
     182but you will need to copy it somewhere else and rename it to ``make``.
     183The same is true for GNU ``tar``; a version of GNU ``tar`` may be found at
     184:file:`/usr/sfw/bin/gtar`,
     185but it will need to be copied somewhere else and renamed to ``tar``.
     186It is recommended to create a directory :file:`$HOME/bins-for-sage` and to put
     187the GNU versions of ``tar`` and ``make`` in that directory.
     188Then ensure that :file:`$HOME/bins-for-sage` is first in your :envvar:`PATH`.
     189That's because Sage also needs :file:`/usr/ccs/bin` in your :envvar:`PATH` to
     190execute programs like ``ar`` and ``ranlib``, but :file:`/usr/ccs/bin` has the
     191Sun/Oracle versions of ``make`` and ``tar`` in it.
     192
     193If you attempt to build Sage on AIX or HP-UX, you will need to install both
     194GNU ``make`` and GNU ``tar``.
     195
     196.. _section_compilers:
     197
     198Using alternative compilers
     199~~~~~~~~~~~~~~~~~~~~~~~~~~~
     200
     201Sage developers tend to use fairly recent versions of GCC, but Sage should
     202compile with any reasonable C compiler.
     203This is because Sage will build GCC first (if needed) and then use that newly
     204built GCC to compile Sage.
     205
     206If you don't want this and want to try building Sage with a different compiler,
     207you need to set the environment variable :envvar:`SAGE_INSTALL_GCC` to ``no``.
     208
     209If you are interested in working on support for commerical compilers from
     210`HP <http://docs.hp.com/en/5966-9844/ch01s03.html>`_,
     211`IBM <http://www-01.ibm.com/software/awdtools/xlcpp/>`_,
     212`Intel <http://software.intel.com/en-us/articles/intel-compilers/>`_,
     213`Sun/Oracle <http://www.oracle.com/technetwork/server-storage/solarisstudio/overview/index.html>`_,
     214etc,
     215or the open-source `Clang <http://clang.llvm.org/>`_,
     216please email the sage-devel mailing list, also known as the sage-devel Google
     217group at http://groups.google.com/group/sage-devel.
     218
     219
     220Additional software
     221-------------------
     222
     223Recommended programs
     224~~~~~~~~~~~~~~~~~~~~
     225
     226The following programs are recommended.
     227They are not strictly required at build time or at run time,
     228but provide additional capablities:
     229
     230- **dvipng**.
     231- **ffmpeg**.
     232- **ImageMagick**.
     233- **latex**: highly recommended.
     234
     235It is highly recommended that you have `Latex <http://en.wikipedia.org/wiki/LaTeX>`_
     236installed, but it is not required.
     237
     238On Linux systems, it is usually provided by packages derived from
     239`TeX Live <www.tug.org/texlive/>`_  and can be installed using::
     240
     241    sudo apt-get install texlive
     242
     243or similar commands.
     244
     245On other systems it might be necessary to install TeX Live from source code,
     246which is quite easy, though a rather time-consuming process.
     247
     248If you don't have either ImageMagick or ffmpeg, you won't be able to
     249view animations.
     250ffmpeg can produce animations in more different formats than ImageMagick,
     251and seems to be faster than ImageMagick when creating animated GIFs.
     252Either ImageMagick or dvipng is used for displaying some LaTeX output in the
     253Sage notebook.
     254
     255Notebook additional features
     256~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     257
     258By default, the Sage notebook uses the
     259`HTTP <http://en.wikipedia.org/wiki/HTTP>`_
     260protocol when you type the command ``notebook()``.
     261To run the notebook in secure mode by typing ``notebook(secure=True)`` which
     262uses the `HTTPS <http://en.wikipedia.org/wiki/HTTPS>`_ protocol,
     263or to use `OpenID <http://en.wikipedia.org/wiki/OpenID>`_ authentication,
     264you need to follow specific installation steps described in
     265:ref:`section_notebook_ssl`.
     266
     267Although all necessary components are provided through Sage optional packages,
     268i.e. you can install a local version of `OpenSSL <http://www.openssl.org>`_
     269by using Sage's **openssl** spkg and running ``sage -i openssl`` as suggested
     270in :ref:`section_notebook_ssl` (this requires an Internet connection),
     271you might prefer to install OpenSSL and the OpenSSL development headers
     272globally on your system.
     273
     274On Linux systems, those are usually provided by the **libssl** and
     275**libssl-dev** packages and can be installed using::
     276
     277    sudo apt-get install libssl libssl-dev
     278
     279or similar commands.
     280
     281Finally, if you intend to distribute the notebook load onto several Sage
     282servers, you will surely want to setup an
     283`SSH <http://en.wikipedia.org/wiki/SSH>`_ server and generate SSH keys.
     284This can be achieved using `OpenSSH <http://www.openssh.org>`_.
     285
     286On Linux systems, the OpenSSH server, client and utilities are usually provided
     287by the **openssh-server** and **openssh-client** packages and can be installed
     288using::
     289
     290    sudo apt-get install openssh-server openssh-client
     291
     292or similar commands.
     293
     294Tcl/Tk
     295~~~~~~
     296
     297If you want to use `Tcl/Tk <http://www.tcl.tk/>`_ libraries in Sage,
     298you need to install the Tcl/Tk and its development headers before building
     299Sage.
     300Sage's Python will then automatically recognize your system's install of
     301Tcl/Tk.
     302
     303On Linux systems, these are usually provided by the **tk** and **tk-dev**
     304(or **tk-devel**) packages which can be installed using::
     305
     306    sudo apt-get install tk tk-dev
     307
     308or similar commands.
     309
     310If you installed Sage first, all is not lost.
     311You just need to rebuild Sage's Python, , and ideally any part of Sage relying
     312on it::
     313
     314    sage -f python  # rebuild Python
     315    SAGE_UPGRADING=yes make # rebuild components of Sage depending on Python
     316
     317after installing the Tcl/Tk development libraries as above.
     318
     319If
     320
     321.. skip
    105322
    106323::
    107324
    108        command -v perl
     325   sage: import _tkinter
     326   sage: import Tkinter
    109327
     328does not raise an ``ImportError``, then it worked.
    110329
    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.
    121330
    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.
     331Step-by-step installation procedure
     332-----------------------------------
    127333
    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.
     334General procedure
     335~~~~~~~~~~~~~~~~~
    133336
    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:
     337Installation from source is (potentially) very easy, because the distribution
     338contains (essentially) everything on which Sage depends.
    143339
    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.
     340Make sure there are **no spaces** in the path name for the directory in which
     341you build:
     342several of Sage's components will not build if there are spaces in the path.
     343Running Sage from a directory with spaces in its name will also fail.
    253344
    254345#. Go to http://www.sagemath.org/download-source.html, select a mirror,
    255    and download the file ``sage-x.y.z.tar``.
     346   and download the file :file:`sage-x.y.z.tar`.
    256347
    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
     348   This tarfile contains the source code for Sage and the source for all
     349   programs on which Sage depends.
     350   Download it into a subdirectory of your :envvar:`HOME` directory.
     351   Note that this file is not compressed; it's just a plain tarball (which
    261352   happens to be full of compressed files).
    262353
    263 #. Extract:
     354#. Extract the tarfile::
    264355
    265    ::
     356       tar xvf sage-x.y.z.tar
    266357
    267              tar xvf sage-x.y.z.tar
     358   This creates a directory :file:`sage-x.y.z`.
    268359
    269 #. This creates a directory ``sage-x.y.z``.
     360#. Change into that directory::
    270361
    271 #. Change into that directory
     362       cd sage-x.y.z
    272363
    273    ::
     364   This is Sage's home directory.
     365   It is also referred to as :envvar:`SAGE_ROOT` or the top level Sage
     366   directory.
    274367
    275              cd sage-x.y.z
     368#. Optional, but highly recommended:
     369   Read the :file:`README.txt` file there.
    276370
    277    This is Sage's home directory. It is also referred to as
    278    ``SAGE_ROOT`` or the top level Sage directory.
     371#. On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to build a
     372   64-bit version of Sage, assuming your computer and operating system are
     373   64-bit, type::
    279374
    280 #. Optional (but highly recommended): Read the ``README.txt`` file
    281    there.
     375       export SAGE64=yes
    282376
    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
     377   It should be noted that as of April 2011, 64-bit builds of Sage on both
     378   Solaris 10 and OpenSolaris are not very stable, so you are advised not to
     379   set :envvar:`SAGE64` to ``yes``.
     380   This will then create stable 32-bit versions of Sage.
     381   See http://wiki.sagemath.org/solaris for the latest information.
    286382
    287    ::
     383#. Start the build process::
    288384
    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.
     385       make
    299386
    300 #. Type
     387   or if your system is multithreaded and you want to use several threads to
     388   build Sage::
    301389
    302    ::
     390       MAKE='make -jNUM' make
    303391
    304              make
     392   to tell the ``make`` program to run ``NUM`` jobs in parallel when building
     393   Sage.
    305394
    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).
     395   This compiles Sage and all its dependencies.
     396   Note that you do not need to be logged in as root, since no files are
     397   changed outside of the :file:`sage-x.y.z` directory.
    310398   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.
     399   should only be used when absolutely necessary and mistyped commands can have
     400   serious consequences if you are logged in as root.
     401   There has been a bug reported (see :trac:`9551`) in Sage which would have
     402   overwritten a system file had the user been logged in as root.
    316403
    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.
     404   Typing ``make`` performs the usual steps for each Sage's dependency,
     405   but installs all the resulting files into the local build tree.
     406   Depending on the age and the architecture of your system, it can take from
     407   a few tens of minutes to several hours to build Sage from source.
     408   On really slow hardware, it can even take a few days to build Sage.
    323409
     410   If the build is successful, you will not see the word ``ERROR`` in the last
     411   3-4 lines of output.
    324412   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    ::
     413   :file:`SAGE_ROOT/logs/pkgs`.
     414   In particular, if the build of Sage fails, then you can type the following
     415   from the directory where you typed ``make``::
    330416
    331417            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.
    337418
    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)
     419   Then paste the contents of the log file(s) with errors to the Sage support
     420   newsgroup at http://groups.google.com/group/sage-support.
     421   If the log files are very large (and many are), then don't paste the whole
     422   file, but make sure to include any error messages.
     423   It would also be helpful to include the type of operating system
     424   (Linux, OS X, Solaris, OpenSolaris, Cygwin, or any other system),
     425   the version and release date of that operating system and the version of
     426   the copy of Sage you are using.
     427   (There are no formal requirements for bug reports -- just send them;
     428   we appreciate everything.)
    341429
    342    See :ref:`section_make` for some options for the ``make`` command.
     430   The directory where you built Sage is **NOT** hardcoded.
     431   You should be able to safely move or rename that directory.
     432   (It's a bug if this is not the case.)
    343433
    344 #. To start Sage, change into the Sage home directory and type:
     434   See :ref:`section_make` for some targets for the ``make`` command,
     435   :ref:`section_envvar` for additional informatio on useful environment
     436   variables used by Sage,
     437   and :ref:`section_notebook_ssl` for additional instruction on how to build
     438   the notebook with SSL support.
    345439
    346    ::
     440#. To start Sage, you can now simply type from Sage's home directory::
    347441
    348              ./sage
     442       ./sage
    349443
    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    ::
     444   You should see the Sage prompt, which will look something like this::
    357445
    358446       $ sage
    359447       ----------------------------------------------------------------------
    360        | Sage Version 4.7, Release Date: 2011-05-23                         |
    361        | Type notebook() for the GUI, and license() for information.        |
     448       | Sage Version 5.8, Release Date: 2013-03-15                         |
     449       | Type "notebook()" for the browser-based notebook interface.        |
     450       | Type "help()" for help.                                            |
    362451       ----------------------------------------------------------------------
    363452       sage:
    364453
     454   Note that Sage should take well under a minute when it starts for the first
     455   time, but can take several minutes if the file system is slow or busy.
     456   Since Sage opens a lot of files, it is preferable to install Sage on a fast
     457   filesystem if possible.
     458
    365459   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.)
     460   correctly.
     461   Note that this should have been already automatically tested during the
     462   build process.
     463   If the above is not displayed (e.g., if you get a massive traceback), please
     464   report the problem, e.g., at http://groups.google.com/group/sage-support.
    375465
    376    After Sage starts, try a command:
    377 
    378    ::
     466   After Sage has started, try a simple command::
    379467
    380468       sage: 2 + 2
    381469       4
    382470
    383    Try something more complicated, which uses the PARI C library:
     471   Try something more complicated, which uses the
     472   `FLINT <http://www.flintlib.org/>`_ C library::
    384473
    385    ::
    386 
    387        sage: factor(2005)
     474       sage: GF(7)(x^7)
    388475       5 * 401
    389476
    390    Try something simple that uses the Gap, Singular, Maxima and
    391    PARI/GP interfaces:
    392 
    393    ::
     477   Try something simple that uses the `GAP <http://www.gap-system.org/>`_,
     478   `Maxima <http://maxima.sourceforge.net/>`_,
     479   `PARI/GP <http://pari.math.u-bordeaux.fr/>`_ and
     480   `Singular <http://www.singular.uni-kl.de/>`_ interfaces::
    394481
    395482       sage: gap('2+2')
    396483       4
     484       sage: maxima('2+2')
     485       4
     486       sage: pari('2+2')
     487       4
    397488       sage: gp('2+2')
    398489       4
    399        sage: maxima('2+2')
    400        4
    401490       sage: singular('2+2')
    402491       4
    403        sage: pari('2+2')
    404        4
    405492
    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.)
     493   (For those familiar with GAP: Sage automatically builds a GAP "workspace"
     494   during installation, so the response time from this GAP command is
     495   relatively fast.
     496   For those familiar with GP/PARI, the ``pari`` command creates an object
     497   directly in the PARI C library, and the ``gp`` command creates an object in
     498   the GP interpreter.)
    411499
    412    Try running Gap, Singular or GP from Sage:
     500   Try running GAP, GP, Maxima, or Singular, from Sage:
    413501
    414502   .. skip
    415503
    416504   ::
    417505
    418506       sage: gap_console()
    419        GAP4, Version: 4.4.12 of 17-Dec-2008, i386-pc-solaris2.11-gcc
     507        ┌───────┐   GAP, Version 4.5.7 of 14-Dec-2012 (free software, GPL)
     508        │  GAP  │   http://www.gap-system.org
     509        └───────┘   Architecture: x86_64-unknown-linux-gnu-gcc-default64
     510        Libs used:  gmp, readline
     511        Loading the library and packages ...
     512        Packages:   GAPDoc 1.5.1
     513        Try '?help' for help. See also  '?copyright' and  '?authors'
    420514       gap> 2+2;
    421515       4
    422        [ctrl-d]
     516       gap>
     517       [CTRL+D]
    423518
    424519   .. skip
    425520
    426521   ::
    427522
    428523       sage: gp_console()
    429        ...
    430        [ctrl-d]
     524       Reading GPRC: .../sage-5.8/local/etc/gprc.expect ...Done.
     525       
     526                  GP/PARI CALCULATOR Version 2.5.3 (development git-6fd07f9)
     527                 amd64 running linux (x86-64/GMP-5.0.2 kernel) 64-bit version
     528               compiled: Apr 10 2013, gcc-4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5)
     529                        (readline v6.2 enabled, extended help enabled)
     530       
     531                            Copyright (C) 2000-2011 The PARI Group
     532       
     533       PARI/GP is free software, covered by the GNU General Public License, and comes
     534       WITHOUT ANY WARRANTY WHATSOEVER.
     535       
     536       Type ? for help, \q to quit.
     537       Type ?12 for how to get moral (and possibly technical) support.
     538       
     539       parisize = 8000000, primelimit = 500509
     540       ? 2+2
     541       %1 = 4
     542       ?
     543       [CTRL+D]
     544
     545   .. skip
     546
     547   ::
     548
     549       sage: maxima_console()
     550       ;;; Loading #P".../sage-5.8/local/lib/ecl/sb-bsd-sockets.fas"
     551       ;;; Loading #P".../sage-5.8/local/lib/ecl/sockets.fas"
     552       ;;; Loading #P".../sage-5.8/local/lib/ecl/defsystem.fas"
     553       ;;; Loading #P".../sage-5.8/local/lib/ecl/cmp.fas"
     554       Maxima 5.29.1 http://maxima.sourceforge.net
     555       using Lisp ECL 12.12.1
     556       Distributed under the GNU Public License. See the file COPYING.
     557       Dedicated to the memory of William Schelter.
     558       The function bug_report() provides bug reporting information.
     559       (%i1) 2+2;
     560       (%o1)                                  4
     561       (%i2)
     562       [CTRL+D]
    431563
    432564   .. skip
    433565
    434566   ::
    435567
    436568       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:
     569                            SINGULAR                                 /  Development
     570        A Computer Algebra System for Polynomial Computations       /   version 3-1-5
     571                                                                  0<
     572        by: W. Decker, G.-M. Greuel, G. Pfister, H. Schoenemann     \   Jul 2012
     573       FB Mathematik der Universitaet, D-67653 Kaiserslautern        \
     574       > 2+2;
     575       4
     576       >
     577       [CTRL+D]
    445578
    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    ::
     579#. Optional:
     580   Check the interfaces to any other software that you have available.
     581   Note that each interface calls its corresponding program by a particular
     582   name: `Mathematica <http://www.wolfram.com/mathematica/>`_ is invoked by
     583   calling ``math``, `Maple <http://www.maplesoft.com/>`_ by calling ``maple``,
     584   etc.
     585   The easiest way to change this name or perform other customizations is
     586   to create a redirection script in :file:`$SAGE_ROOT/local/bin`.
     587   Sage inserts this directory at the front of your :envvar:`PATH`, so your
     588   script may need to use an absolute path to avoid calling itself; also, your
     589   script should use ``$*`` to pass along all of its arguments.
     590   For example, a ``maple`` script might look like::
    459591
    460592       #!/bin/sh
    461593
    462594       /etc/maple10.2/maple.tty $*
    463595
    464 #. Optional: Different possibilities to make using Sage a little
    465    easier:
     596#. Optional:
     597   There are different possibilities to make using Sage a little easier:
    466598
    467    - Make a symbolic link from ``/usr/local/bin/sage`` (or another
    468      directory in your :envvar:`PATH`) to ``$SAGE_ROOT/sage``::
     599   - Make a symbolic link from :file:`/usr/local/bin/sage` (or another
     600     directory in your :envvar:`PATH`) to :file:`$SAGE_ROOT/sage`::
    469601
    470602         ln -s /path/to/sage-x.y.z/sage /usr/local/bin/sage
    471603
    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
     604     Now simply typing ``sage`` from any directory should be sufficient to run
    500605     Sage.
    501606
    502 #. Optional, but highly recommended: Test the install by typing ``./sage --testall``.
     607   - Copy :file:`$SAGE_ROOT/sage` to a location in your :envvar:`PATH`.
     608     If you do this, make sure you edit the line::
     609
     610         #SAGE_ROOT=/path/to/sage-version
     611
     612     at the beginning of the copied ``sage`` script according to the direction
     613     given there to something like::
     614
     615         SAGE_ROOT=<SAGE_ROOT>
     616
     617     (note that you have to change ``<SAGE_ROOT>`` above!).
     618     It is best to edit only the copy, not the original.
     619
     620   - For `KDE <http://www.kde.org/>`_ users, create a bash script called
     621     ``sage`` containing the lines
     622     (note that you have to change ``<SAGE_ROOT>`` below!)::
     623
     624         #!/bin/bash
     625
     626         konsole -T "sage" -e <SAGE_ROOT>/sage
     627
     628     make it executable::
     629
     630         chmod a+x sage
     631
     632     and put it somewhere in your :envvar:`PATH`.
     633
     634     You can also make a KDE desktop icon with this line as the command
     635     (under the Application tab of the Properties of the icon, which you get my
     636     right clicking the mouse on the icon).
     637
     638   - On Linux and OS X systems, you can make an alias to
     639     :file:`$SAGE_ROOT/sage`.
     640     For example, put something similar to the following line in your
     641     :file:`.bashrc` file::
     642
     643         alias sage=<SAGE_ROOT>/sage
     644
     645     (Note that you have to change ``<SAGE_ROOT>`` above!)
     646     Having done so, quit your terminal emulator and restart it.
     647     Now typing ``sage`` within your terminal emulator should start Sage.
     648
     649#. Optional, but highly recommended:
     650   Test the install by typing ``./sage --testall``.
    503651   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!
     652   exactly as claimed.
     653   To test all examples, use ``./sage --testall --optional --long``;
     654   this will run examples that take a long time, and those that depend on
     655   optional packages and software, e.g., Mathematica or Magma.
     656   Some (optional) examples will therefore likely fail.
    513657
    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.
     658   Alternatively, from within :file:`$SAGE_ROOT`, you can type ``make test``
     659   (respectively ``make ptest``) to run all the standard test code serially
     660   (respectively in parallel).
    519661
    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.
     662   Testing the Sage library can take from half an hour to several hours,
     663   depending on your hardware.
     664   On slow hardware building and testing Sage can even take several days!
    523665
     666#. Optional:
     667   Install optional Sage packages and databases.
     668   Type ``sage --optional`` to see a list of them (this requires an Internet
     669   connection), or visit http://www.sagemath.org/packages/optional/.
     670   Then type ``sage -i <package-name>`` to automatically download and install
     671   a given package.
    524672
    525 Have fun! Discover some amazing conjectures!
     673#. Optional:
     674   Run the ``install_scripts`` command from within Sage to create GAP, GP,
     675   Maxima, Singular, etc., scripts in your :envvar:`PATH`.
     676   Type ``install_scripts?`` in Sage for details.
     677
     678#. Have fun! Discover some amazing conjectures!
     679
     680.. _section_notebook_ssl:
     681
     682Building the notebook with SSL support
     683~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     684
     685Read this section if you are intending to run a Sage notebook server for
     686multiple users.
     687
     688For security, you may wish users to access the server using the HTTPS protocol
     689(i.e., to run ``notebook(secure=True)``).
     690You also may want to use OpenID for user authentication.
     691The first of these requires you to install
     692`pyOpenSSL <http://pyopenssl.sourceforge.net/>`_,
     693and they both require OpenSSL.
     694
     695If you have OpenSSL and the OpenSSL development headers installed on your
     696system, you can install pyOpenSSL by building Sage and then typing::
     697
     698    ./sage -i pyopenssl
     699
     700Alternatively, ``make ssl`` builds Sage and installs pyOpenSSL at once.
     701Note that these commands require Internet access.
     702
     703If you are missing either OpenSSL or OpenSSL's development headers,
     704you can install a local copy of both into your Sage installation first.
     705Ideally, this should be done before installing Sage; otherwise, you should at
     706least rebuild Sage's Python, and ideally any part of Sage relying on it.
     707The procedure is as follows (again, with a computer connected to the
     708Internet).
     709Starting from a fresh Sage tarball::
     710
     711    ./sage -i openssl
     712    make ssl
     713
     714And if you've already built Sage::
     715
     716    ./sage -i openssl
     717    ./sage -f python
     718    SAGE_UPGRADING=yes make ssl
     719
     720The third line will rebuild all parts of Sage that depend on Python;
     721this can take a while.
     722
     723Rebasing issues on Cygwin
     724~~~~~~~~~~~~~~~~~~~~~~~~~
     725
     726Building on Cygwin will occasionally require "rebasing" ``dll`` files.
     727Sage provides some scripts, located in :file:`$SAGE_LOCAL/bin`, to do so:
     728
     729- ``sage-rebaseall.sh``, a shell script which calls Cygwin's ``rebaseall``
     730  program.
     731  It must be run within a ``dash`` shell from the :envvar:`SAGE_ROOT` directory
     732  after all other Cygwin processes have been shut down and needs write-access
     733  to the system-wide rebase database located at :file:`/etc/rebase.db.i386`,
     734  which usually means administrator privileges.
     735  It updates the system-wide database and adds Sage dlls to it, so that
     736  subsequent calls to ``rebaseall`` will take them into account.
     737- ``sage-rebase.sh``, a shell script which calls Cygwin's ``rebase`` program
     738  together with the ``-O/--oblivious`` option.
     739  It must be run within a shell from :envvar:`SAGE_ROOT` directory.
     740  Contrary to the ``sage-rebaseall.sh`` script, it neither updates the
     741  system-wide database, nor adds Sage dlls to it.
     742  Therefore, subsequent calls to ``rebaseall`` will not take them into account.
     743- ``sage-rebaseall.bat`` (respectively ``sage-rebase.bat``), an MS-DOS batch
     744  file which calls the ``sage-rebaseall.sh`` (respectively ``sage-rebase.sh``)
     745  script.
     746  It must be run from a Windows command prompt, after adjusting
     747  :envvar:`SAGE_ROOT` to the Windows location of Sage's home directory, and, if
     748  Cygwin is installed in a non-standard location, adjusting
     749  :envvar:`CYGWIN_ROOT` as well.
     750
     751Some systems may encounter this problem frequently enough to make building or
     752testing difficult.
     753If executing the above scripts or directly calling ``rebaseall`` does not solve
     754rebasing issues, deleting the system-wide database and then regenerating it
     755from scratch, e.g., by executing ``sage-rebaseall.sh``, might help.
     756
     757Finally, on Cygwin, one should also avoid the following:
     758
     759- building in home directories of Windows domain users;
     760- building in paths with capital letters.
     761
    526762
    527763.. _section_make:
    528764
    529765Make targets
    530766------------
    531767
    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.
     768To build Sage from scratch, you would typically execute ``make`` in Sage's home
     769directory to build Sage and its `HTML <http://en.wikipedia.org/wiki/HTML>`_
     770documentation.
     771The ``make`` command is pretty smart, so if your build of Sage is interrupted,
     772then running ``make`` again should cause it to pick up where it left off.
     773The ``make`` command can also be given options, which control what is built and
     774how it is built:
    538775
    539 - ``make build`` builds Sage: it compiles all of the Sage packages. It
    540   does not build the documentation.
     776- ``make build`` builds Sage: it compiles all of the Sage packages.
     777  It does not build the documentation.
    541778
    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``.
     779- ``make doc`` builds Sage's documentation in HTML format.
     780  Note that this requires that Sage be built first, so it will automatically
     781  run ``make build`` first.
     782  Thus, running ``make doc`` is equivalent to running ``make``.
    546783
    547784- ``make doc-pdf`` builds Sage's documentation in PDF format. This also
    548785  requires that Sage be built first, so it will automatically run ``make
    549786  build``.
    550787
    551788- ``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
     789  than in parallel (parallel building is the default).
     790  Running ``make build-serial`` is equivalent to setting the environment
     791  variable :envvar:`SAGE_PARALLEL_SPKG_BUILD` to "no" -- see below for
    555792  information about this variable.
    556793
    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.
     794- ``make ptest`` and ``make ptestlong``: these run Sage's test suite.
     795  The first version skips tests that needs more than a few seconds to complete
     796  and those which depends on optional packages or additional software.
     797  The second version includes them the former, and so it takes longer.
     798  The "p" in ``ptest`` stands for "parallel": tests are run in parallel.
     799  If you want to run tests serially, you can use ``make test`` or
     800  ``make testlong`` instead.
     801  If you want to run tests depending on optional packages and additional
     802  software, you can use ``make testalll``, ``make ptestall``,
     803  ``make testalllong``, or ``make ptestalllong``.
    563804
    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.
     805- ``make distclean`` restores the Sage directory to its state before doing any
     806  building: it is equivalent to deleting the entire Sage's home directory and
     807  unpacking the source tarfile again.
     808
     809.. _section_envvar:
    567810
    568811Environment variables
    569812---------------------
    570813
    571814Sage 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
     815Most users won't need to set any of these: the build process just works on many
     816platforms.
     817(Note though that setting :envvar:`MAKE`, as described below, can significantly
     818speed up the process.)
     819Building Sage involves building about 100 packages, each of which has its own
    576820compilation instructions.
    577821
    578 Here are some of the more commonly used variables affecting the build
    579 process:
     822Here are some of the more commonly used variables affecting the build process:
    580823
    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
     824- :envvar:`MAKE` - one useful setting for this variable when building Sage is
     825  ``MAKE='make -jNUM'`` to tell the ``make`` program to run ``NUM`` jobs in
     826  parallel when building.
     827  Some people advise using more jobs than there are CPU cores, at least if the
     828  system is not heavily loaded and has plenty of RAM; for example, a good
     829  setting for ``NUM`` might be between 1 and 1.5 times the number of cores.
     830  In addition, the ``-l`` option sets a load limit: ``MAKE='make -j4 -l5.5``,
     831  for example, tells ``make`` to try to use four jobs, but to not start more
     832  than one job if the system load average is above 5.5.
     833  See the manual page for GNU ``make``: `Command-line options
    591834  <http://www.gnu.org/software/make/manual/make.html#Options-Summary>`_
    592835  and `Parallel building
    593836  <http://www.gnu.org/software/make/manual/make.html#Parallel>`_.
    594837
    595838  .. warning::
    596839
    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.
     840      Some users on single-core OS X machines have reported problems when
     841      building Sage with ``MAKE='make -jNUM'`` with ``NUM`` greater than one.
    600842
    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
     843- :envvar:`SAGE_NUM_THREADS` - if set to a number, then when building the
     844  documentation, parallel doctesting, or running ``sage -b``, use this many
     845  threads.
     846  If this is not set, then determine the number of threads using the value of
     847  the :envvar:`MAKE` (see above) or :envvar:`MAKEFLAGS` environment variables.
     848  If none of these specifies a number of jobs, use one thread (except for
     849  parallel testing: there we use a default of the number of CPU cores, with a
    608850  maximum of 8 and a minimum of 2).
    609851
    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.
     852- :envvar:`SAGE_PARALLEL_SPKG_BUILD` - if set to ``no``, then build spkgs
     853  serially rather than in parallel.
     854  If this is set to ``no``, then each spkg may still take advantage of the setting
     855  of :envvar:`MAKE` to build using multiple jobs, but the spkgs will be built
     856  one at a time.
     857  Alternatively, run ``make build-serial`` which sets this environment
     858  variable for you.
    616859
    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`.
     860- :envvar:`SAGE_CHECK` - if set to ``yes``, then during the build process,
     861  and when running ``sage -i <package-name>`` or ``sage -f <package-name>``,
     862  run the test suite for each package which has one.
     863  See also :envvar:`SAGE_CHECK_PACKAGES`.
    621864
    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.
     865- :envvar:`SAGE_CHECK_PACKAGES` - if :envvar:`SAGE_CHECK` is set to ``yes``,
     866  then the default behavior is to run test suites for all spkgs which contain
     867  them.
     868  If :envvar:`SAGE_CHECK_PACKAGES` is set, it should be a comma-separated list
     869  of strings of the form ``pakage-name`` or ``!pakage-name``.
     870  An entry ``pakage-name`` means to run the test suite for the named package
     871  regardless of the setting of :envvar:`SAGE_CHECK`.
     872  An entry ``!pakage-name`` means to skip its test suite.
     873  So if this is set to ``mpir,!python``, then always run the test suite for
     874  MPIR, but always skip the test suite for Python.
    631875
    632876  .. note::
    633877
    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``.
     878     As of this writing (April 2013, Sage 5.8), the test suite for the Python
     879     spkg fails on most platforms.
     880     So when this variable is empty or unset, Sage uses a default of
     881     ``!python``.
    637882
    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.
     883- :envvar:`SAGE64` - if set to ``yes``, then build a 64-bit binary on platforms
     884  which default to 32-bit, even though they can build 64-bit binaries.
     885  It adds the compiler flag ``-m64`` when compiling programs.
     886  The :envvar:`SAGE64` variable is mainly of use on OS X (pre 10.6), Solaris
     887  and OpenSolaris, though it will add the ``-m64`` flag on any operating
     888  system.
     889  If you are running Linux or version 10.6 or later of OS X on a 64-bit
     890  machine, then Sage will automatically build a 64-bit binary, so this
     891  variable does not need to be set.
    646892
    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.
     893- :envvar:`CFLAG64` - default value ``-m64``.
     894  If Sage detects that it should build a 64-bit binary, then it uses this flag
     895  when compiling C code.
     896  Modify it if necessary for your system and C compiler.
     897  This should not be necessary on most systems -- this flag will typically be
     898  set automatically, based on the setting of :envvar:`SAGE64`, for example.
    653899
    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.
     900- :envvar:`SAGE_INSTALL_GCC` - by default, Sage will automatically detect
     901  whether to install the `GNU Compiler Collection (GCC) <http://gcc.gnu.org/>`_
     902  package or not (depending on whether C, C++ and Fortran compilers are present
     903  and the versions of those compilers).
     904  Setting ``SAGE_INSTALL_GCC=yes`` will force Sage to install GCC.
     905  Setting ``SAGE_INSTALL_GCC=no`` will prevent Sage from installing GCC.
    662906
    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.
     907- :envvar:`SAGE_INSTALL_CCACHE` - by default Sage doesn't install ccache,
     908  however by setting ``SAGE_INSTALL_CCACHE=yes`` Sage will install ccache.
     909  Because the Sage distribution is quite large, the maximum cache is set to 4G.
     910  This can be changed by running ``sage -sh -c "ccache --max-size=SIZE"``,
     911  where ``SIZE`` is specified in gigabytes, megabytes, or kilobytes by
     912  appending a "G", "M", or "K".
    669913
    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.
     914  Sage does not include the sources for ccache since it is an optional package.
     915  Because of this, it is necessary to have an Internet connection while
     916  building ccache for Sage, so that Sage can pull down the necessary
     917  sources.
    674918
    675 - :envvar:`SAGE_DEBUG` - enable debugging support. There are three
    676   different values:
     919- :envvar:`SAGE_DEBUG` - controls debugging support.
     920  There are three different possible values:
    677921
    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.
     922  * Not set (or set to anything else than "yes" or "no"): build binaries with
     923    debugging symbols, but no special debug builds.
     924    This is the default.
     925    There is no performance impact, only additional disk space is used.
    682926
    683   * ``SAGE_DEBUG=no``: no means no debugging symbols (that is, no
     927  * ``SAGE_DEBUG=no``: ``no`` means no debugging symbols (that is, no
    684928    ``gcc -g``), which saves some disk space.
    685929
    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
     930  * ``SAGE_DEBUG=yes``: build debug versions if possible (in particular,
     931    Python is built with additional debugging turned on and Singular is built
     932    with a different memory manager).
     933    These will be notably slower but, for example, make it much easier to
    690934    pinpoint memory allocation problems.
    691935
    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``.
     936- :envvar:`SAGE_SPKG_LIST_FILES` - if set to ``yes``, then enable verbose
     937  extraction of tar files, i.e. Sage's spkg files.
     938  Since some spkgs contain such a huge number of files that the log files
     939  get very large and harder to search (and listing the contained files is
     940  usually less valuable), we decided to turn this off by default.
     941  This variable affects builds of Sage with ``make`` (and ``sage --upgrade``)
     942  as well as the manual installation of individual spkgs with e.g. ``sage -i``
     943  or ``sage -f``.
    700944
    701 - :envvar:`SAGE_SPKG_INSTALL_DOCS` - Set this to "yes" to install
     945- :envvar:`SAGE_SPKG_INSTALL_DOCS` - if set to ``yes``, then install
    702946  package-specific documentation to
    703947  :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
     948  installed.
     949  This option may not be supported by all spkgs.
     950  Some spkgs might also assume that certain programs are available on the
    706951  system (for example, ``latex`` or ``pdflatex``).
    707952
    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.
     953- :envvar:`SAGE_DOC_MATHJAX` - by default, any LaTeX code in Sage's
     954  documentation is processed by MathJax.
     955  If this variable is set to ``no``, then MathJax is not used -- instead,
     956  math is processed using LaTeX and converted by dvipng to image files,
     957  and then those files are included into the documentation.
     958  Typically, building the documentation using LaTeX and dvipng takes longer
     959  and uses more memory and disk space than using MathJax.
    715960
    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.
     961- :envvar:`SAGE_BUILD_DIR` - the default behavior is to build each spkg in a
     962  subdirectory of :file:`$SAGE_ROOT/spkg/build/`; for example, build
     963  :file:`atlas-3.8.3.p12.spkg` in the directory
     964  :file:`$SAGE_ROOT/spkg/build/atlas-3.8.3.p12/`.
     965  If this variable is set, then build in
     966  :file:`$SAGE_BUILD_DIR/atlas-3.8.3.p12/` instead.
     967  If the directory :file:`$SAGE_BUILD_DIR` does not exist, it is created.
     968  As of this writing (Sage 4.8), when building the standard Sage packages,
     969  1.5 gigabytes of free space are required in this directory (or more if
     970  ``SAGE_KEEP_BUILT_SPKGS=yes`` -- see below); the exact amount of required
     971  space varies from platform to platform.
     972  For example, the block size of the file system will affect the amount of
     973  space used, since some spkgs contain many small files.
    729974
    730975  .. warning::
    731976
    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.
     977      The variable :envvar:`SAGE_BUILD_DIR` must be set to the full path name
     978      of either an existing directory for which the user has write permissions,
     979      or to the full path name of a nonexistent directory which the user has
     980      permission to create.
     981      The path name must contain **no spaces**.
    737982
    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.
     983- :envvar:`SAGE_KEEP_BUILT_SPKGS` - the default behavior is to delete each
     984  build directory -- the appropriate subdirectory of
     985  :file:`$SAGE_ROOT/spkg/build` or :file:`$SAGE_BUILD_DIR` -- after each spkg
     986  is successfully built, and to keep it if there were errors installing the
     987  spkg.
     988  Set this variable to ``yes`` to keep the subdirectory regardless.
     989  Furthermore, if you install an spkg for which there is already a
     990  corresponding subdirectory, for example left over from a previous build,
     991  then the default behavior is to delete that old subdirectory.
     992  If this variable is set to ``yes``, then the old subdirectory is moved to
     993  :file:`$SAGE_ROOT/spkg/build/old/` (or :file:`$SAGE_BUILD_DIR/old`),
     994  overwriting any already existing file or directory with the same name.
    751995
    752996  .. note::
    753997
    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.
     998      After a full build of Sage (as of version 4.8), these subdirectories can
     999      take up to 6 gigabytes of storage, in total, depending on the platform
     1000      and the block size of the file system.
     1001      If you always set this variable to ``yes``, it can take even more space:
     1002      rebuilding every spkg would use double the amount of space, and any
     1003      upgrades to spkgs would create still more directories, using still more
     1004      space.
    7611005
    7621006  .. note::
    7631007
    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``.
     1008      In an existing Sage installation, running ``sage -i -s <package-name>``
     1009      or ``sage -f -s <package-name>`` installs the spkg ``<package-name>`` and
     1010      keeps the corresponding build directory; thus setting
     1011      :envvar:`SAGE_KEEP_BUILT_SPKGS` to ``yes`` mimics this behavior when
     1012      building Sage from scratch or when installing individual spkgs.
     1013      So you can set this variable to ``yes`` instead of using the ``-s`` flag
     1014      for ``sage -i`` and ``sage -f``.
    7711015
    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::
     1016- :envvar:`SAGE_FAT_BINARY` - to prepare a binary distribution that will run
     1017  on the widest range of target machines, set this variable to ``yes`` before
     1018  building Sage::
    7751019
    7761020      export SAGE_FAT_BINARY="yes"
    7771021      make
    7781022      ./sage --bdist x.y.z-fat
    7791023
    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:
     1024Variables to set if you're trying to build Sage with an unusual setup, e.g.,
     1025an unsupported machine or an unusual compiler:
    7821026
    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 ::
     1027- :envvar:`SAGE_PORT` - if you try to build Sage on a platform which is
     1028  recognized as being unsupported (e.g. AIX, or HP-UX), or with a compiler
     1029  which is unsupported (anything except GCC), you will see a message saying
     1030  something like::
    7871031
    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.
     1032      You are attempting to build Sage on IBM's AIX operating system,
     1033      which is not a supported platform for Sage yet. Things may or
     1034      may not work. If you would like to help port Sage to AIX,
     1035      please join the sage-devel discussion list -- see
     1036      http://groups.google.com/group/sage-devel
     1037      The Sage community would also appreciate any patches you submit.
    7971038
    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).
     1039      To get past this message and try building Sage anyway,
     1040      export the variable SAGE_PORT to something non-empty.
    8011041
    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.
     1042  If this is case and you want to try to build Sage anyway, follow the
     1043  directions: set :envvar:`SAGE_PORT` to something non-empty (and expect to
     1044  run into problems).
     1045
     1046- :envvar:`SAGE_USE_OLD_GCC` - the Sage build process requires GCC with a
     1047  version number of at least 4.0.1.
     1048  If the most recent version of GCC on your system is the older 3.4.x series
     1049  and you want to build with ``SAGE_INSTALL_GCC=no``, then set
     1050  :envvar:`SAGE_USE_OLD_GCC` to something non-empty.
     1051  Expect the build to fail in this case.
    8071052
    8081053Environment variables dealing with specific Sage packages:
    8091054
    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
     1055- :envvar:`SAGE_ATLAS_ARCH` - if you are compiling ATLAS (in particular,
     1056  if :envvar:`SAGE_ATLAS_LIB` is not set), you can use this environment
     1057  variable to set a particular architecture and instruction set extension.
     1058  The syntax is ``SAGE_ATLAS_ARCH=arch[,isaext1][,isaext2]...[,isaextN]``.
     1059  While ATLAS comes with precomputed timings for a variety of CPUs, it only
     1060  uses them if it finds an exact match.
     1061  Otherwise, ATLAS runs through a lengthy automated tuning process in order
     1062  to optimize performance for your particular system, which can take several
     1063  days on slow and unusual systems.
     1064  You drastically reduce the total Sage compile time if you manually select a
     1065  suitable architecture.
     1066  It is recommended to specify a suitable architecture on laptops or other
     1067  systems with CPU throttling or if you want to distribute the binaries.
     1068  Available architectures are
    8231069
    8241070    ``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``, ``P5``,
    8251071    ``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
     
    8281074    ``IA64Itan``, ``IA64Itan2``, ``USI``, ``USII``, ``USIII``,
    8291075    ``USIV``, ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``
    8301076
    831   and instruction set extensions are 
    832    
     1077  and instruction set extensions are
     1078
    8331079    ``AltiVec``, ``SSE3``, ``SSE2``, ``SSE1``, ``3DNow``.
    8341080
    8351081  In addition, you can also set
    8361082
    837   - ``SAGE_ATLAS_ARCH=fast`` picks defaults for a modern (2-3 year old)
     1083  - ``SAGE_ATLAS_ARCH=fast`` which picks defaults for a modern (2-3 year old)
    8381084    CPU of your processor line, and
    8391085
    840   - ``SAGE_ATLAS_ARCH=base`` picks defaults that should work for a ~10
     1086  - ``SAGE_ATLAS_ARCH=base`` which picks defaults that should work for a ~10
    8411087    year old CPU.
    8421088
    843   For example, 
     1089  For example,
    8441090
    8451091    ``SAGE_ATLAS_ARCH=Corei7,SSE3,SSE2,SSE1``
    8461092
    8471093  would be appropriate for a Core i7 CPU.
    8481094
    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/``.
     1095- :envvar:`SAGE_ATLAS_LIB` - if you have an installation of ATLAS on your
     1096  system and you want Sage to use it instead of building and installing its
     1097  own version of ATLAS, set this variable to be the directory containing your
     1098  ATLAS installation.
     1099  It should contain the files :file:`libatlas`, :file:`liblapack`,
     1100  :file:`libcblas`, and :file:`libf77blas` with extensions ``.a``, ``.so``, or
     1101  ``.dylib``.
     1102  For backward compatibility, the libraries may also be in the subdirectory
     1103  :file:`SAGE_ATLAS_LIB/lib/`.
    8571104
    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.
     1105- :envvar:`SAGE_MATPLOTLIB_GUI` - if set to anything non-empty except ``no``,
     1106  then Sage will attempt to build the graphical backend when it builds the
     1107  matplotlib package.
    8611108
    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:
     1109- :envvar:`INCLUDE_MPFR_PATCH` - this is used to add a patch to MPFR to bypass
     1110  a bug in the memset function affecting sun4v machines with versions of
     1111  Solaris earlier than Solaris 10 update 8 (10/09).
     1112  Earlier versions of Solaris 10 can be patched by applying Sun patch
     1113  142542-01.
     1114  Recognized values are:
    8671115
    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.
     1116  - ``INCLUDE_MPFR_PATCH=0`` - never include the patch - useful if you know all
     1117    sun4v machines Sage will be used are running Solaris 10 update 8 or later,
     1118    or have been patched with Sun patch 142542-01.
    8721119
    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.
     1120  - ``INCLUDE_MPFR_PATCH=1`` - always include the patch, so the binary will
     1121    work on a sun4v machine, even if created on an older sun4u machine.
    8761122
    877   If this variable is unset, include the patch on sun4v machines only.
     1123  - If this variable is unset, include the patch on sun4v machines only.
    8781124
    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.
     1125- :envvar:`SAGE_BINARY_BUILD` - used by the pil package.
     1126  If set to ``yes``, then force Sage to use the versions of libjpeg, libtiff
     1127  and libpng from :file:`$SAGE_ROOT/local/lib`.
     1128  Otherwise, allow the use of the system's versions of these libraries.
    8831129
    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.)
     1130- :envvar:`SAGE_PIL_NOTK` - used by the pil package.
     1131  If set to ``yes``, then disable building TK.
     1132  If this is not set, then this should be dealt with automatically: Sage tries
     1133  to build the pil package with TK support enabled, but if it runs into
     1134  problems, it tries building again with TK disabled.
     1135  So only use this variable to force TK to be disabled.
     1136  (Building the pil package is pretty fast -- less than a minute on many
     1137  systems -- so allowing it to build twice is not a serious issue.)
    8921138
    8931139Some standard environment variables which are used by Sage:
    8941140
    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.
     1141- :envvar:`CC` - while some programs allow you to use this to specify your C
     1142  compiler, **not every Sage package recognizes this**.
     1143  If GCC is installed within Sage, :envvar:`CC` is ignored and Sage's ``gcc``
     1144  is used instead.
    8991145
    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.
     1146- :envvar:`CPP` - similarly, this will set the C preprocessor for some Sage
     1147  packages, and similarly, using it is likely quite risky.
     1148  If GCC is installed within Sage, :envvar:`CPP` is ignored and Sage's ``cpp``
     1149  is used instead.
     1150
     1151- :envvar:`CXX` - similarly, this will set the C++ compiler for some Sage
     1152  packages, and similarly, using it is likely quite risky.
     1153  If GCC is installed within Sage, :envvar:`CXX` is ignored and Sage's ``g++``
     1154  is used instead.
    9041155
    9051156- :envvar:`FC` - similarly, this will set the Fortran compiler.
    9061157  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).
     1158  However, for historical reasons, the value is hardcoded during the initial
     1159  ``make`` and subsequent changes to ``$FC`` might be ignored (in which case,
     1160  the original value will be used instead).
    9101161  If GCC is installed within Sage, :envvar:`FC` is ignored and Sage's
    9111162  ``gfortran`` is used instead.
    9121163
    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.
     1164- :envvar:`CFLAGS`, :envvar:`CXXFLAGS` and :envvar:`FCFLAGS` - the flags for
     1165  the C compiler, the C++ compiler and the Fortran compiler, respectively.
     1166  The same comments apply to these: setting them may cause problems, because
     1167  they are not universally respected among the Sage packages.
    9181168
    919 The following Fortran-related environment variables are **deprecated**
    920 since Sage 5.3 and support for these will likely be removed.
     1169The following Fortran-related environment variables are **deprecated** since
     1170Sage 5.3 and support for these will likely be removed.
    9211171They are still recognized, but should not be used for new setups.
    9221172
    9231173- :envvar:`SAGE_FORTRAN` - the path to the Fortran compiler.
    9241174  Deprecated, use :envvar:`FC` instead.
    9251175
    9261176- :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
     1177  Normally, you don't need to set this.
     1178  If you really need to, you can add the directory containing the library to
    9291179  :envvar:`LIBRARY_PATH` and/or :envvar:`LD_LIBRARY_PATH`.
    9301180
    9311181Sage uses the following environment variables when it runs:
    9321182
    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.
     1183- :envvar:`DOT_SAGE` - this is the directory, to which the user has read and
     1184  write access, where Sage stores a number of files.
     1185  The default location is :file:`$HOME/.sage/`.
    9371186
    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``.
     1187- :envvar:`SAGE_STARTUP_FILE` - a file including commands to be executed every
     1188  time Sage starts.
     1189  The default value is :file:`$DOT_SAGE/init.sage`.
    9411190
    9421191- :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.
     1192  ``sage -i <package-name>``, Sage downloads the file from the web, using the
     1193  address ``http://www.sagemath.org/`` by default, or the address given by
     1194  :envvar:`SAGE_SERVER` if it is set.
     1195  If you wish to set up your own server, then note that Sage will search the
     1196  directories:
    9521197
    953 - :envvar:`SAGE_PATH` - a colon-separated list of directories which
    954   Sage searches when trying to locate Python libraries.
     1198  - ``SAGE_SERVER/packages/standard/``,
     1199  - ``SAGE_SERVER/packages/optional/``,
     1200  - ``SAGE_SERVER/packages/experimental/``,
     1201  - and ``SAGE_SERVER/packages/archive/``
    9551202
    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.
     1203  for packages.
     1204  See the script :file:`$SAGE_ROOT/spkg/bin/sage-spkg` for the implementation.
    9591205
    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.
     1206- :envvar:`SAGE_PATH` - a colon-separated list of directories which Sage
     1207  searches when trying to locate Python libraries.
    9631208
    964 - :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used
    965   on Mac OS X to set the :envvar:`DYLD_LIBRARY_PATH`.
     1209- :envvar:`SAGE_BROWSER` - on most platforms, Sage will detect the command to
     1210  run a web browser, but if this doesn't seem to work on your machine, set this
     1211  variable to the appropriate command.
     1212
     1213- :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET` - set this to something non-empty to
     1214  force Sage to set the :envvar:`LD_LIBRARY_PATH` variable before executing
     1215  system commands.
     1216
     1217- :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used on OS X to
     1218  set the :envvar:`DYLD_LIBRARY_PATH` variable.
    9661219
    9671220- :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".
     1221  :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`.
     1222  Set this to the base name of the BLAS library file on your system if you want
     1223  to override the default setting.
     1224  That is, if the relevant file is called :file:`libcblas_new.so` or
     1225  :file:`libcblas_new.dylib`, then set this to ``cblas_new``.
    9731226
    9741227Sage overrides the user's settings of the following variables:
    9751228
    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
     1229- :envvar:`MPLCONFIGDIR` - ordinarily, this variable lets the user set their
     1230  matplotlib config directory.
     1231  Due to incompatibilies in the contents of this directory among different
     1232  versions of matplotlib, Sage overrides the user's setting, defining it
     1233  instead to be :file:`$DOT_SAGE/matplotlib-VER`, with ``VER`` replaced by the
    9811234  current matplotlib version number.
    9821235
    9831236Variables dealing with doctesting:
    9841237
    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).
     1238- :envvar:`SAGE_TIMEOUT` - used for Sage's doctesting: the number of seconds
     1239  to allow a doctest before timing it out.
     1240  If this isn't set, the default is 360 seconds (6 minutes).
    9931241
    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
     1242- :envvar:`SAGE_TIMEOUT_LONG` - used for Sage's doctesting: the number of
     1243  seconds to allow a doctest before timing it out, if tests are run using
     1244  ``sage -t --long``.
     1245  If this isn't set, the default is 1800 seconds (30 minutes).
     1246
     1247- :envvar:`SAGE_PICKLE_JAR` - if you want to update the the standard pickle
     1248  jar, set this to something non-empty and run the doctest suite.
     1249  See the documentation for the functions :func:`picklejar` and
     1250  :func:`unpickle_all` in
     1251  :file:`$SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
    9991252  `here (picklejar)
    10001253  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.picklejar>`_
    10011254  and `here (unpickle_all)
    10021255  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.unpickle_all>`_.
    10031256
    1004 ..
    1005   THIS INDENTED BLOCK IS A COMMENT.  FIX IT ONCE WE UNDERSTAND
    1006   THESE VARIABLES.
     1257.. comment:
     1258    ***************************************************************************
     1259    FIX THIS!
    10071260
    1008   Variables dealing with valgrind and friends:
     1261    Variables dealing with valgrind and friends:
    10091262
    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.
     1263    - :envvar:`SAGE_TIMEOUT_VALGRIND` - used for Sage's doctesting: the
     1264      number of seconds to allow a doctest before timing it out, if tests
     1265      are run using ``??``.  If this isn't set, the default is 1024*1024
     1266      seconds.
    10141267
    1015   - :envvar:`SAGE_VALGRIND` - ?
     1268    - :envvar:`SAGE_VALGRIND` - trigger black magic in Python.
    10161269
    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"
     1270    - :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`,
     1271      :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS` - flags
     1272      used when using valgrind and one of the tools "memcheck", "massif",
     1273      "cachegrind", or "omega"
     1274    ***************************************************************************
     1275
    10211276
    10221277Installation in a Multiuser Environment
    10231278---------------------------------------
    10241279
    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.
     1280This section addresses the question of how a system administrator can install
     1281a single copy of Sage in a multi-user computer network.
    10281282
    10291283System-wide install
    10301284~~~~~~~~~~~~~~~~~~~
    10311285
    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.
     1286#. After building Sage, you may optionally copy or move the entire build tree
     1287   to :file:`/usr/local` or another location.
     1288   If you do this, then you must run ``./sage`` once so that various hardcoded
     1289   locations get updated.
     1290   For this reason, it might be easier to simply build Sage in its final
     1291   location.
    10371292
    1038 #. Make a symbolic link to the ``sage`` script in ``/usr/local/bin``::
     1293#. Make a symbolic link to the ``sage`` script in :file:`/usr/local/bin`::
    10391294
    10401295       ln -s /path/to/sage-x.y.z/sage /usr/local/bin/sage
    10411296
    10421297   Alternatively, copy the Sage script::
    10431298
    10441299       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``.
    10501300
    1051 #. Make sure that all files in the Sage tree are readable by all::
     1301   If you do this, make sure you edit the line::
    10521302
    1053        chmod a+rX -R /usr/local/sage-5.0
     1303       #SAGE_ROOT=/path/to/sage-version
     1304
     1305   at the beginning of the copied ``sage`` script according to the direction
     1306   given there to something like::
     1307
     1308       SAGE_ROOT=<SAGE_ROOT>
     1309
     1310   (note that you have to change ``<SAGE_ROOT>`` above!).
     1311   It is recommended not to edit the original ``sage`` script, only the copy at
     1312   :file:`/usr/local/bin/sage`.
     1313
     1314#. Make sure that all files in the Sage tree are readable by all
     1315   (note that you have to change ``<SAGE_ROOT>`` below!)::
     1316
     1317       chmod a+rX -R <SAGE_ROOT>
    10541318
    10551319#. Optionally, you can test Sage by running::
    10561320
    10571321       make testlong
    1058    
     1322
    10591323   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.
     1324   processes.
     1325   You can also omit ``long`` to skip tests which take a long time.
     1326
     1327Sagetex
     1328~~~~~~~
     1329
     1330To make SageTeX available to your users, see the instructions for
     1331:ref:`installation in a multiuser environment <sagetex_installation_multiuser>`
     1332.
     1333
    10621334
    10631335Some common problems
    10641336--------------------
     
    10661338ATLAS
    10671339~~~~~
    10681340
    1069 Sometimes the ATLAS spkg can fail to build.  Some things to check for:
     1341Sometimes the ATLAS spkg can fail to build.
     1342Some things to check for:
    10701343
    1071 - Make sure that CPU throttling mode (= power-saving mode) is turned off
     1344- Make sure that CPU throttling mode (i.e. power-saving mode) is turned off
    10721345  when building ATLAS.
    10731346
    1074 - Also, the ATLAS build can fail if the system load is too high, and in
     1347- The ATLAS build can also fail if the system load is too high, and in
    10751348  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.
     1349  ``MAKE='make -jNUM'`` with ``NUM`` large.
     1350  If this happens, just try running ``make`` again.
     1351  If ``make`` fails after five or six attempts, report your problem to the
     1352  sage-devel mailing list at http://groups.google.com/group/sage-devel.
    10791353
    1080 Special Notes
    1081 -------------
     1354zn_poly
     1355~~~~~~~
    10821356
    1083 - To make SageTeX available to your users, see the instructions for
    1084   :ref:`installation in a multiuser environment
    1085   <sagetex_installation_multiuser>`.
     1357It has been reported (see :trac:`13947`) that the zn_poly spkg fails to build
     1358on loaded systems, especially on Mac OS X and Cygwin.
     1359If you encounter this problem, you can try to build zn_poly serially before
     1360reissuing ``make``::
    10861361
    1087   **This page was last updated in August 2012 (Sage 5.3).**
     1362    MAKE="make -j1" ./sage -i zn_poly && make
     1363
     1364
     1365**This page was last updated in April 2013 (Sage 5.8).**