Ticket #14465: source.patch

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

    # HG changeset patch
    # User Jean-Pierre Flori <jean-pierre.flori@ssi.gouv.fr>
    # Date 1366235392 -7200
    # Node ID 61500a1793e18a526b5dfabb5bffe19b3dbdd55b
    # 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`x64 <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, make sure you have a recent version of
     145`Xcode <http://developer.apple.com/xcode/>`_.
     146It provides all the above requirements.
     147You can get the latest Xcode from http://developer.apple.com/xcode/,
     148but may have to pay a small fee in order to download this.
     149See http://wiki.sagemath.org/SupportedPlatforms to find out what versions
     150of Xcode are supported.
     151
     152On Solaris, you would use ``pkgadd`` and on OpenSolaris ``ipf`` to install
     153the necessary software.
     154
     155On Cygwin, you would use the ``setup.exe`` program.
     156As on Linux systems ``ranlib`` is provided by the ``binutils`` package.
     157As far as compilers are concerned, you should either install the ``gcc4-core``
     158package alone, or install matching versions of the ``gcc4-core``, ``gcc4-g++``,
     159and ``gcc4-gfortran`` packages to avoid the build of Sage's own GCC.
     160
     161On other systems, check the documentation for your particular operating system.
     162
     163Specific notes for ``make`` and ``tar``
     164~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     165
     166On OS X, the BSD ``tar`` supplied will build Sage, so there is no need to
     167install the GNU ``tar``.
     168
     169On Solaris or OpenSolaris, the Sun/Oracle versions of ``make`` and ``tar`` are
     170unsuitable for building Sage.
     171Therefore, you must have the GNU versions of ``make`` and ``tar`` installed and
     172they must be the first ``make`` and ``tar`` in your :envvar:`PATH`.
     173
     174On Solaris 10, a version of GNU ``make`` may be found at :file:`/usr/sfw/bin/gmake`,
     175but you will need to copy it somewhere else and rename it to ``make``.
     176The same is true for GNU ``tar``; a version of GNU ``tar`` may be found at
     177:file:`/usr/sfw/bin/gtar`,
     178but it will need to be copied somewhere else and renamed to ``tar``.
     179It is recommended to create a directory :file:`$HOME/bins-for-sage` and to put
     180the GNU versions of ``tar`` and ``make`` in that directory.
     181Then ensure that :file:`$HOME/bins-for-sage` is first in your :envvar:`PATH`.
     182That's because Sage also needs :file:`/usr/ccs/bin` in your :envvar:`PATH` to
     183execute programs like ``ar`` and ``ranlib``, but :file:`/usr/ccs/bin` has the
     184Sun/Oracle versions of ``make`` and ``tar`` in it.
     185
     186If you attempt to build Sage on AIX or HP-UX, you will need to install both
     187GNU ``make`` and GNU ``tar``.
     188
     189.. _section_compilers:
     190
     191Using alternative compilers
     192~~~~~~~~~~~~~~~~~~~~~~~~~~~
     193
     194Sage developers tend to use fairly recent versions of GCC, but Sage should
     195compile with any reasonable C compiler.
     196This is because Sage will build GCC first (if needed) and then use that newly
     197built GCC to compile Sage.
     198
     199If you don't want this and want to try building Sage with a different compiler,
     200you need to set the environment variable :envvar:`SAGE_INSTALL_GCC` to ``no``.
     201
     202If you are interested in working on support for commerical compilers from
     203`HP <http://docs.hp.com/en/5966-9844/ch01s03.html>`_,
     204`IBM <http://www-01.ibm.com/software/awdtools/xlcpp/>`_,
     205`Intel <http://software.intel.com/en-us/articles/intel-compilers/>`_,
     206`Sun/Oracle <http://www.oracle.com/technetwork/server-storage/solarisstudio/overview/index.html>`_,
     207etc,
     208or the open-source `Clang <http://clang.llvm.org/>`_,
     209please email the sage-devel mailing list, also known as the sage-devel Google
     210group at http://groups.google.com/group/sage-devel.
     211
     212
     213Additional software
     214-------------------
     215
     216Recommended programs
     217~~~~~~~~~~~~~~~~~~~~
     218
     219The following programs are recommended.
     220They are not strictly required at build time or at run time,
     221but provide additional capablities:
     222
     223- **dvipng**.
     224- **ffmpeg**.
     225- **ImageMagick**.
     226- **latex**: highly recommended.
     227
     228It is highly recommended that you have `Latex <http://en.wikipedia.org/wiki/LaTeX>`_
     229installed, but it is not required.
     230
     231On Linux systems, it is usually provided by packages derived from
     232`TeX Live <www.tug.org/texlive/>`_  and can be installed using::
     233
     234    sudo apt-get install texlive
     235
     236or similar commands.
     237
     238On other systems it might be necessary to install TeX Live from source code,
     239which is quite easy, though a rather time-consuming process.
     240
     241If you don't have either ImageMagick or ffmpeg, you won't be able to
     242view animations.
     243ffmpeg can produce animations in more different formats than ImageMagick,
     244and seems to be faster than ImageMagick when creating animated GIFs.
     245Either ImageMagick or dvipng is used for displaying some LaTeX output in the
     246Sage notebook.
     247
     248Notebook additional features
     249~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     250
     251By default, the Sage notebook uses the
     252`HTTP <http://en.wikipedia.org/wiki/HTTP>`_
     253protocol when you type the command ``notebook()``.
     254To run the notebook in secure mode by typing ``notebook(secure=True)`` which
     255uses the `HTTPS <http://en.wikipedia.org/wiki/HTTPS>`_ protocol,
     256or to use `OpenID <http://en.wikipedia.org/wiki/OpenID>`_ authentication,
     257you need to follow specific installation steps described in
     258:ref:`section_notebook_ssl`.
     259Although all necessary components are provided through Sage optional packages
     260(to download separately), you might consider installing
     261`OpenSSL <http://www.openssl.org>`_ and the OpenSSL development headers
     262globally on your system rather than using Sage's **openssl** spkg.
     263
     264On Linux systems, those are usually provided by the **libssl** and
     265**libssl-dev** packages and can be installed using::
     266
     267    sudo apt-get install libssl libssl-dev
     268
     269or similar commands.
     270
     271Finally, if you intend to distribute the notebook load onto several Sage
     272servers, you will surely want to setup an
     273`SSH <http://en.wikipedia.org/wiki/SSH>`_ server and generate SSH keys.
     274This can be achieved using `OpenSSH <http://www.openssh.org>`_.
     275
     276On Linux systems, the OpenSSH server, client and utilities are usually provided
     277by the **openssh-server** and **openssh-client** packages and can be installed
     278using::
     279
     280    sudo apt-get install openssh-server openssh-client
     281
     282or similar commands.
     283
     284Tcl/Tk
     285~~~~~~
     286
     287If you want to use `Tcl/Tk <http://www.tcl.tk/>`_ libraries in Sage,
     288you need to install the Tcl/Tk and its development headers before building
     289Sage.
     290Sage's Python will then automatically recognize your system's install of
     291Tcl/Tk.
     292
     293On Linux systems, these are usually provided by the **tk** and **tk-dev**
     294(or **tk-devel**) packages which can be installed using::
     295
     296    sudo apt-get install tk tk-dev
     297
     298or similar commands.
     299
     300If you installed Sage first, all is not lost.
     301You just need to rebuild Sage's Python, , and ideally any part of Sage relying
     302on it::
     303
     304    sage -f python  # rebuild Python
     305    SAGE_UPGRADING=yes make # rebuild components of Sage depending on Python
     306
     307after installing the Tcl/Tk development libraries as above.
     308
     309If
     310
     311.. skip
    105312
    106313::
    107314
    108        command -v perl
     315   sage: import _tkinter
     316   sage: import Tkinter
    109317
     318does not raise an ``ImportError``, then it worked.
    110319
    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.
    121320
    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.
     321Step-by-step installation procedure
     322-----------------------------------
    127323
    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.
     324General procedure
     325~~~~~~~~~~~~~~~~~
    133326
    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:
     327Installation from source is (potentially) very easy, because the distribution
     328contains (essentially) everything on which Sage depends.
    143329
    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.
     330Make sure there are **no spaces** in the path name for the directory in which
     331you build:
     332several of Sage's components will not build if there are spaces in the path.
     333Running Sage from a directory with spaces in its name will also fail.
    253334
    254335#. Go to http://www.sagemath.org/download-source.html, select a mirror,
    255    and download the file ``sage-x.y.z.tar``.
     336   and download the file :file:`sage-x.y.z.tar`.
    256337
    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
     338   This tarfile contains the source code for Sage and the source for all
     339   programs on which Sage depends.
     340   Download it into a subdirectory of your :envvar:`HOME` directory.
     341   Note that this file is not compressed; it's just a plain tarball (which
    261342   happens to be full of compressed files).
    262343
    263 #. Extract:
     344#. Extract the tarfile::
    264345
    265    ::
     346       tar xvf sage-x.y.z.tar
    266347
    267              tar xvf sage-x.y.z.tar
     348   This creates a directory :file:`sage-x.y.z`.
    268349
    269 #. This creates a directory ``sage-x.y.z``.
     350#. Change into that directory::
    270351
    271 #. Change into that directory
     352       cd sage-x.y.z
    272353
    273    ::
     354   This is Sage's home directory.
     355   It is also referred to as :envvar:`SAGE_ROOT` or the top level Sage
     356   directory.
    274357
    275              cd sage-x.y.z
     358#. Optional, but highly recommended:
     359   Read the :file:`README.txt` file there.
    276360
    277    This is Sage's home directory. It is also referred to as
    278    ``SAGE_ROOT`` or the top level Sage directory.
     361#. On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to build a
     362   64-bit version of Sage, assuming your computer and operating system are
     363   64-bit, type::
    279364
    280 #. Optional (but highly recommended): Read the ``README.txt`` file
    281    there.
     365       export SAGE64=yes
    282366
    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
     367   It should be noted that as of April 2011, 64-bit builds of Sage on both
     368   Solaris 10 and OpenSolaris are not very stable, so you are advised not to
     369   set :envvar:`SAGE64` to ``yes``.
     370   This will then create stable 32-bit versions of Sage.
     371   See http://wiki.sagemath.org/solaris for the latest information.
    286372
    287    ::
     373#. Start the build process::
    288374
    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.
     375       make
    299376
    300 #. Type
     377   This compiles Sage and all its dependencies.
     378   Note that you do not need to be logged in as root, since no files are
     379   changed outside of the :file:`sage-x.y.z` directory.
     380   In fact, **it is inadvisable to build Sage as root**, as the root account
     381   should only be used when absolutely necessary and mistyped commands can have
     382   serious consequences if you are logged in as root.
     383   There has been a bug reported (see :trac:`9551`) in Sage which would have
     384   overwritten a system file had the user been logged in as root.
    301385
    302    ::
     386   Typing ``make`` performs the usual steps for each Sage's dependency,
     387   but installs all the resulting files into the local build tree.
     388   Depending on the age and the architecture of your system, it can take from
     389   a few tens of minutes to several hours to build Sage from source.
     390   On really slow hardware, it can even take a few days to build Sage.
    303391
    304              make
    305 
    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).
    310    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.
    316 
    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.
    323 
     392   If the build is successful, you will not see the word ``ERROR`` in the last
     393   3-4 lines of output.
    324394   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    ::
     395   :file:`SAGE_ROOT/logs/pkgs`.
     396   In particular, if the build of Sage fails, then you can type the following
     397   from the directory where you typed ``make``::
    330398
    331399            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.
    337400
    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)
     401   Then paste the contents of the log file(s) with errors to the Sage support
     402   newsgroup at http://groups.google.com/group/sage-support.
     403   If the log files are very large (and many are), then don't paste the whole
     404   file, but make sure to include any error messages.
     405   It would also be helpful to include the type of operating system
     406   (Linux, OS X, Solaris, OpenSolaris, Cygwin, or any other system),
     407   the version and release date of that operating system and the version of
     408   the copy of Sage you are using.
     409   (There are no formal requirements for bug reports -- just send them;
     410   we appreciate everything.)
    341411
    342    See :ref:`section_make` for some options for the ``make`` command.
     412   The directory where you built Sage is **NOT** hardcoded.
     413   You should be able to safely move or rename that directory.
     414   (It's a bug if this is not the case.)
    343415
    344 #. To start Sage, change into the Sage home directory and type:
     416   See :ref:`section_make` for some targets for the ``make`` command,
     417   and :ref:`section_notebook_ssl` for additional instruction on how to build
     418   the notebook with SSL support.
    345419
    346    ::
     420#. To start Sage, you can now simply type from Sage's home directory::
    347421
    348              ./sage
     422       ./sage
    349423
    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    ::
     424   You should see the Sage prompt, which will look something like this::
    357425
    358426       $ sage
    359427       ----------------------------------------------------------------------
    360        | Sage Version 4.7, Release Date: 2011-05-23                         |
    361        | Type notebook() for the GUI, and license() for information.        |
     428       | Sage Version 5.8, Release Date: 2013-03-15                         |
     429       | Type "notebook()" for the browser-based notebook interface.        |
     430       | Type "help()" for help.                                            |
    362431       ----------------------------------------------------------------------
    363432       sage:
    364433
     434   Note that Sage should take well under a minute when it starts for the first
     435   time, but can take several minutes if the file system is slow or busy.
     436   Since Sage opens a lot of files, it is preferable to install Sage on a fast
     437   filesystem if possible.
     438
    365439   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.)
     440   correctly.
     441   Note that this should have been already automatically tested during the
     442   build process.
     443   If the above is not displayed (e.g., if you get a massive traceback), please
     444   report the problem, e.g., at http://groups.google.com/group/sage-support.
    375445
    376    After Sage starts, try a command:
    377 
    378    ::
     446   After Sage has started, try a simple command::
    379447
    380448       sage: 2 + 2
    381449       4
    382450
    383    Try something more complicated, which uses the PARI C library:
     451   Try something more complicated, which uses the
     452   `FLINT <http://www.flintlib.org/>`_ C library::
    384453
    385    ::
    386 
    387        sage: factor(2005)
     454       sage: GF(7)(x^7)
    388455       5 * 401
    389456
    390    Try something simple that uses the Gap, Singular, Maxima and
    391    PARI/GP interfaces:
    392 
    393    ::
     457   Try something simple that uses the `GAP <http://www.gap-system.org/>`_,
     458   `Maxima <http://maxima.sourceforge.net/>`_,
     459   `PARI/GP <http://pari.math.u-bordeaux.fr/>`_ and
     460   `Singular <http://www.singular.uni-kl.de/>`_ interfaces::
    394461
    395462       sage: gap('2+2')
    396463       4
     464       sage: maxima('2+2')
     465       4
     466       sage: pari('2+2')
     467       4
    397468       sage: gp('2+2')
    398469       4
    399        sage: maxima('2+2')
    400        4
    401470       sage: singular('2+2')
    402471       4
    403        sage: pari('2+2')
    404        4
    405472
    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.)
     473   (For those familiar with GAP: Sage automatically builds a GAP "workspace"
     474   during installation, so the response time from this GAP command is
     475   relatively fast.
     476   For those familiar with GP/PARI, the ``pari`` command creates an object
     477   directly in the PARI C library, and the ``gp`` command creates an object in
     478   the GP interpreter.)
    411479
    412    Try running Gap, Singular or GP from Sage:
     480   Try running GAP, GP, Maxima, or Singular, from Sage:
    413481
    414482   .. skip
    415483
    416484   ::
    417485
    418486       sage: gap_console()
    419        GAP4, Version: 4.4.12 of 17-Dec-2008, i386-pc-solaris2.11-gcc
     487        ┌───────┐   GAP, Version 4.5.7 of 14-Dec-2012 (free software, GPL)
     488        │  GAP  │   http://www.gap-system.org
     489        └───────┘   Architecture: x86_64-unknown-linux-gnu-gcc-default64
     490        Libs used:  gmp, readline
     491        Loading the library and packages ...
     492        Packages:   GAPDoc 1.5.1
     493        Try '?help' for help. See also  '?copyright' and  '?authors'
    420494       gap> 2+2;
    421495       4
    422        [ctrl-d]
     496       gap>
     497       [CTRL+D]
    423498
    424499   .. skip
    425500
    426501   ::
    427502
    428503       sage: gp_console()
    429        ...
    430        [ctrl-d]
     504       Reading GPRC: .../sage-5.8/local/etc/gprc.expect ...Done.
     505       
     506                  GP/PARI CALCULATOR Version 2.5.3 (development git-6fd07f9)
     507                 amd64 running linux (x86-64/GMP-5.0.2 kernel) 64-bit version
     508               compiled: Apr 10 2013, gcc-4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5)
     509                        (readline v6.2 enabled, extended help enabled)
     510       
     511                            Copyright (C) 2000-2011 The PARI Group
     512       
     513       PARI/GP is free software, covered by the GNU General Public License, and comes
     514       WITHOUT ANY WARRANTY WHATSOEVER.
     515       
     516       Type ? for help, \q to quit.
     517       Type ?12 for how to get moral (and possibly technical) support.
     518       
     519       parisize = 8000000, primelimit = 500509
     520       ? 2+2
     521       %1 = 4
     522       ?
     523       [CTRL+D]
     524
     525   .. skip
     526
     527   ::
     528
     529       sage: maxima_console()
     530       ;;; Loading #P".../sage-5.8/local/lib/ecl/sb-bsd-sockets.fas"
     531       ;;; Loading #P".../sage-5.8/local/lib/ecl/sockets.fas"
     532       ;;; Loading #P".../sage-5.8/local/lib/ecl/defsystem.fas"
     533       ;;; Loading #P".../sage-5.8/local/lib/ecl/cmp.fas"
     534       Maxima 5.29.1 http://maxima.sourceforge.net
     535       using Lisp ECL 12.12.1
     536       Distributed under the GNU Public License. See the file COPYING.
     537       Dedicated to the memory of William Schelter.
     538       The function bug_report() provides bug reporting information.
     539       (%i1) 2+2;
     540       (%o1)                                  4
     541       (%i2)
     542       [CTRL+D]
    431543
    432544   .. skip
    433545
    434546   ::
    435547
    436548       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:
     549                            SINGULAR                                 /  Development
     550        A Computer Algebra System for Polynomial Computations       /   version 3-1-5
     551                                                                  0<
     552        by: W. Decker, G.-M. Greuel, G. Pfister, H. Schoenemann     \   Jul 2012
     553       FB Mathematik der Universitaet, D-67653 Kaiserslautern        \
     554       > 2+2;
     555       4
     556       >
     557       [CTRL+D]
    445558
    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    ::
     559#. Optional:
     560   Check the interfaces to any other software that you have available.
     561   Note that each interface calls its corresponding program by a particular
     562   name: `Mathematica <http://www.wolfram.com/mathematica/>`_ is invoked by
     563   calling ``math``, `Maple <http://www.maplesoft.com/>`_ by calling ``maple``,
     564   etc.
     565   The easiest way to change this name or perform other customizations is
     566   to create a redirection script in :file:`$SAGE_ROOT/local/bin`.
     567   Sage inserts this directory at the front of your :envvar:`PATH`, so your
     568   script may need to use an absolute path to avoid calling itself; also, your
     569   script should use ``$*`` to pass along all of its arguments.
     570   For example, a ``maple`` script might look like::
    459571
    460572       #!/bin/sh
    461573
    462574       /etc/maple10.2/maple.tty $*
    463575
    464 #. Optional: Different possibilities to make using Sage a little
    465    easier:
     576#. Optional:
     577   There are different possibilities to make using Sage a little easier:
    466578
    467    - Make a symbolic link from ``/usr/local/bin/sage`` (or another
    468      directory in your :envvar:`PATH`) to ``$SAGE_ROOT/sage``::
     579   - Make a symbolic link from :file:`/usr/local/bin/sage` (or another
     580     directory in your :envvar:`PATH`) to :file:`$SAGE_ROOT/sage`::
    469581
    470582         ln -s /path/to/sage-x.y.z/sage /usr/local/bin/sage
    471583
    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
     584     Now simply typing ``sage`` from any directory should be sufficient to run
    500585     Sage.
    501586
    502 #. Optional, but highly recommended: Test the install by typing ``./sage --testall``.
     587   - Copy :file:`$SAGE_ROOT/sage` to a location in your :envvar:`PATH`.
     588     If you do this, make sure you edit the line::
     589
     590         #SAGE_ROOT=/path/to/sage-version
     591
     592     at the beginning of the copied ``sage`` script according to the direction
     593     given there to something like::
     594
     595         SAGE_ROOT=<SAGE_ROOT>
     596
     597     (note that you have to change ``<SAGE_ROOT>`` above!).
     598     It is best to edit only the copy, not the original.
     599
     600   - For `KDE <http://www.kde.org/>`_ users, create a bash script called
     601     ``sage`` containing the lines
     602     (note that you have to change ``<SAGE_ROOT>`` below!)::
     603
     604         #!/bin/bash
     605
     606         konsole -T "sage" -e <SAGE_ROOT>/sage
     607
     608     make it executable::
     609
     610         chmod a+x sage
     611
     612     and put it somewhere in your :envvar:`PATH`.
     613
     614     You can also make a KDE desktop icon with this line as the command
     615     (under the Application tab of the Properties of the icon, which you get my
     616     right clicking the mouse on the icon).
     617
     618   - On Linux and OS X systems, you can make an alias to
     619     :file:`$SAGE_ROOT/sage`.
     620     For example, put something similar to the following line in your
     621     :file:`.bashrc` file::
     622
     623         alias sage=<SAGE_ROOT>/sage
     624
     625     (Note that you have to change ``<SAGE_ROOT>`` above!)
     626     Having done so, quit your terminal emulator and restart it.
     627     Now typing ``sage`` within your terminal emulator should start Sage.
     628
     629#. Optional, but highly recommended:
     630   Test the install by typing ``./sage --testall``.
    503631   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!
     632   exactly as claimed.
     633   To test all examples, use ``./sage --testall --optional --long``;
     634   this will run examples that take a long time, and those that depend on
     635   optional packages and software, e.g., Mathematica or Magma.
     636   Some (optional) examples will therefore likely fail.
    513637
    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.
     638   Alternatively, from within :file:`$SAGE_ROOT`, you can type ``make test``
     639   (respectively ``make ptest``) to run all the standard test code serially
     640   (respectively in parallel).
    519641
    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.
     642   Testing the Sage library can take from half an hour to several hours,
     643   depending on your hardware.
     644   On slow hardware building and testing Sage can even take several days!
    523645
     646#. Optional:
     647   Install optional Sage packages and databases.
     648   Type ``sage --optional`` to see a list of them (this requires an Internet
     649   connection), or visit http://www.sagemath.org/packages/optional/.
     650   Then type ``sage -i <package-name>`` to automatically download and install
     651   a given package.
    524652
    525 Have fun! Discover some amazing conjectures!
     653#. Optional:
     654   Run the ``install_scripts`` command from within Sage to create GAP, GP,
     655   Maxima, Singular, etc., scripts in your :envvar:`PATH`.
     656   Type ``install_scripts?`` in Sage for details.
     657
     658#. Have fun! Discover some amazing conjectures!
     659
     660.. _section_notebook_ssl:
     661
     662Building the notebook with SSL support
     663~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     664
     665Read this section if you are intending to run a Sage notebook server for
     666multiple users.
     667
     668For security, you may wish users to access the server using the HTTPS protocol
     669(i.e., to run ``notebook(secure=True)``).
     670You also may want to use OpenID for user authentication.
     671The first of these requires you to install
     672`pyOpenSSL <http://pyopenssl.sourceforge.net/>`_,
     673and they both require OpenSSL.
     674
     675If you have OpenSSL and the OpenSSL development headers installed on your
     676system, you can install pyOpenSSL by building Sage and then typing::
     677
     678    ./sage -i pyopenssl
     679
     680Alternatively, ``make ssl`` builds Sage and installs pyOpenSSL at once.
     681Note that these commands require Internet access.
     682
     683If you are missing either OpenSSL or OpenSSL's development headers,
     684you can install a local copy of both into your Sage installation first.
     685Ideally, this should be done before installing Sage; otherwise, you should at
     686least rebuild Sage's Python, and ideally any part of Sage relying on it.
     687The procedure is as follows (again, with a computer connected to the
     688Internet).
     689Starting from a fresh Sage tarball::
     690
     691    ./sage -i openssl
     692    make ssl
     693
     694And if you've already built Sage::
     695
     696    ./sage -i openssl
     697    ./sage -f python
     698    SAGE_UPGRADING=yes make ssl
     699
     700The third line will rebuild all parts of Sage that depend on Python;
     701this can take a while.
     702
     703Rebasing issues on Cygwin
     704~~~~~~~~~~~~~~~~~~~~~~~~~
     705
     706Building on Cygwin will occasionally require "rebasing" ``dll`` files.
     707Sage provides some scripts, located in :file:`$SAGE_LOCAL/bin`, to do so:
     708
     709- ``sage-rebaseall.sh``, a shell script which calls Cygwin's ``rebaseall``
     710  program.
     711  It must be run within a ``dash`` shell from the :envvar:`SAGE_ROOT` directory
     712  after all other Cygwin processes have been shut down and needs write-access
     713  to the system-wide rebase database located at :file:`/etc/rebase.db.i386`,
     714  which usually means administrator privileges.
     715  It updates the system-wide database and adds Sage dlls to it, so that
     716  subsequent calls to ``rebaseall`` will take them into account.
     717- ``sage-rebase.sh``, a shell script which calls Cygwin's ``rebase`` program
     718  together with the ``-O/--oblivious`` option.
     719  It must be run within a shell from :envvar:`SAGE_ROOT` directory.
     720  Contrary to the ``sage-rebaseall.sh`` script, it neither updates the
     721  system-wide database, nor adds Sage dlls to it.
     722  Therefore, subsequent calls to ``rebaseall`` will not take them into account.
     723- ``sage-rebaseall.bat`` (respectively ``sage-rebase.bat``), an MS-DOS batch
     724  file which calls the ``sage-rebaseall.sh`` (respectively ``sage-rebase.sh``)
     725  script.
     726  It must be run from a Windows command prompt, after adjusting
     727  :envvar:`SAGE_ROOT` to the Windows location of Sage's home directory, and, if
     728  Cygwin is installed in a non-standard location, adjusting
     729  :envvar:`CYGWIN_ROOT` as well.
     730
     731Some systems may encounter this problem frequently enough to make building or
     732testing difficult.
     733If executing the above scripts or directly calling ``rebaseall`` does not solve
     734rebasing issues, deleting the system-wide database and then regenerating it
     735from scratch, e.g., by executing ``sage-rebaseall.sh``, might help.
     736
     737Finally, on Cygwin, one should also avoid the following:
     738
     739- building in home directories of Windows domain users;
     740- building in paths with capital letters.
     741
    526742
    527743.. _section_make:
    528744
    529745Make targets
    530746------------
    531747
    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.
     748To build Sage from scratch, you would typically execute ``make`` in Sage's home
     749directory to build Sage and its `HTML <http://en.wikipedia.org/wiki/HTML>`_
     750documentation.
     751The ``make`` command is pretty smart, so if your build of Sage is interrupted,
     752then running ``make`` again should cause it to pick up where it left off.
     753The ``make`` command can also be given options, which control what is built and
     754how it is built:
    538755
    539 - ``make build`` builds Sage: it compiles all of the Sage packages. It
    540   does not build the documentation.
     756- ``make build`` builds Sage: it compiles all of the Sage packages.
     757  It does not build the documentation.
    541758
    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``.
     759- ``make doc`` builds Sage's documentation in HTML format.
     760  Note that this requires that Sage be built first, so it will automatically
     761  run ``make build`` first.
     762  Thus, running ``make doc`` is equivalent to running ``make``.
    546763
    547764- ``make doc-pdf`` builds Sage's documentation in PDF format. This also
    548765  requires that Sage be built first, so it will automatically run ``make
    549766  build``.
    550767
    551768- ``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
     769  than in parallel (parallel building is the default).
     770  Running ``make build-serial`` is equivalent to setting the environment
     771  variable :envvar:`SAGE_PARALLEL_SPKG_BUILD` to "no" -- see below for
    555772  information about this variable.
    556773
    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.
     774- ``make ptest`` and ``make ptestlong``: these run Sage's test suite.
     775  The first version skips tests that needs more than a few seconds to complete
     776  and those which depends on optional packages or additional software.
     777  The second version includes them the former, and so it takes longer.
     778  The "p" in ``ptest`` stands for "parallel": tests are run in parallel.
     779  If you want to run tests serially, you can use ``make test`` or
     780  ``make testlong`` instead.
     781  If you want to run tests depending on optional packages and additional
     782  software, you can use ``make testalll``, ``make ptestall``,
     783  ``make testalllong``, or ``make ptestalllong``.
    563784
    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.
     785- ``make distclean`` restores the Sage directory to its state before doing any
     786  building: it is equivalent to deleting the entire Sage's home directory and
     787  unpacking the source tarfile again.
     788
    567789
    568790Environment variables
    569791---------------------
    570792
    571793Sage 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
     794Most users won't need to set any of these: the build process just works on many
     795platforms.
     796(Note though that setting :envvar:`MAKE`, as described below, can significantly
     797speed up the process.)
     798Building Sage involves building about 100 packages, each of which has its own
    576799compilation instructions.
    577800
    578 Here are some of the more commonly used variables affecting the build
    579 process:
     801Here are some of the more commonly used variables affecting the build process:
    580802
    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
     803- :envvar:`MAKE` - one useful setting for this variable when building Sage is
     804  ``MAKE='make -jNUM'`` to tell the ``make`` program to run ``NUM`` jobs in
     805  parallel when building.
     806  Some people advise using more jobs than there are CPU cores, at least if the
     807  system is not heavily loaded and has plenty of RAM; for example, a good
     808  setting for ``NUM`` might be between 1 and 1.5 times the number of cores.
     809  In addition, the ``-l`` option sets a load limit: ``MAKE='make -j4 -l5.5``,
     810  for example, tells ``make`` to try to use four jobs, but to not start more
     811  than one job if the system load average is above 5.5.
     812  See the manual page for GNU ``make``: `Command-line options
    591813  <http://www.gnu.org/software/make/manual/make.html#Options-Summary>`_
    592814  and `Parallel building
    593815  <http://www.gnu.org/software/make/manual/make.html#Parallel>`_.
    594816
    595817  .. warning::
    596818
    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.
     819      Some users on single-core OS X machines have reported problems when
     820      building Sage with ``MAKE='make -jNUM'`` with ``NUM`` greater than one.
    600821
    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
     822- :envvar:`SAGE_NUM_THREADS` - if set to a number, then when building the
     823  documentation, parallel doctesting, or running ``sage -b``, use this many
     824  threads.
     825  If this is not set, then determine the number of threads using the value of
     826  the :envvar:`MAKE` (see above) or :envvar:`MAKEFLAGS` environment variables.
     827  If none of these specifies a number of jobs, use one thread (except for
     828  parallel testing: there we use a default of the number of CPU cores, with a
    608829  maximum of 8 and a minimum of 2).
    609830
    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.
     831- :envvar:`SAGE_PARALLEL_SPKG_BUILD` - if set to ``no``, then build spkgs
     832  serially rather than in parallel.
     833  If this is set to ``no``, then each spkg may still take advantage of the setting
     834  of :envvar:`MAKE` to build using multiple jobs, but the spkgs will be built
     835  one at a time.
     836  Alternatively, run ``make build-serial`` which sets this environment
     837  variable for you.
    616838
    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`.
     839- :envvar:`SAGE_CHECK` - if set to ``yes``, then during the build process,
     840  and when running ``sage -i <package-name>`` or ``sage -f <package-name>``,
     841  run the test suite for each package which has one.
     842  See also :envvar:`SAGE_CHECK_PACKAGES`.
    621843
    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.
     844- :envvar:`SAGE_CHECK_PACKAGES` - if :envvar:`SAGE_CHECK` is set to ``yes``,
     845  then the default behavior is to run test suites for all spkgs which contain
     846  them.
     847  If :envvar:`SAGE_CHECK_PACKAGES` is set, it should be a comma-separated list
     848  of strings of the form ``pakage-name`` or ``!pakage-name``.
     849  An entry ``pakage-name`` means to run the test suite for the named package
     850  regardless of the setting of :envvar:`SAGE_CHECK`.
     851  An entry ``!pakage-name`` means to skip its test suite.
     852  So if this is set to ``mpir,!python``, then always run the test suite for
     853  MPIR, but always skip the test suite for Python.
    631854
    632855  .. note::
    633856
    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``.
     857     As of this writing (April 2013, Sage 5.8), the test suite for the Python
     858     spkg fails on most platforms.
     859     So when this variable is empty or unset, Sage uses a default of
     860     ``!python``.
    637861
    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.
     862- :envvar:`SAGE64` - if set to ``yes``, then build a 64-bit binary on platforms
     863  which default to 32-bit, even though they can build 64-bit binaries.
     864  It adds the compiler flag ``-m64`` when compiling programs.
     865  The :envvar:`SAGE64` variable is mainly of use on OS X (pre 10.6), Solaris
     866  and OpenSolaris, though it will add the ``-m64`` flag on any operating
     867  system.
     868  If you are running Linux or version 10.6 or later of OS X on a 64-bit
     869  machine, then Sage will automatically build a 64-bit binary, so this
     870  variable does not need to be set.
    646871
    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.
     872- :envvar:`CFLAG64` - default value ``-m64``.
     873  If Sage detects that it should build a 64-bit binary, then it uses this flag
     874  when compiling C code.
     875  Modify it if necessary for your system and C compiler.
     876  This should not be necessary on most systems -- this flag will typically be
     877  set automatically, based on the setting of :envvar:`SAGE64`, for example.
    653878
    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.
     879- :envvar:`SAGE_INSTALL_GCC` - by default, Sage will automatically detect
     880  whether to install the `GNU Compiler Collection (GCC) <http://gcc.gnu.org/>`_
     881  package or not (depending on whether C, C++ and Fortran compilers are present
     882  and the versions of those compilers).
     883  Setting ``SAGE_INSTALL_GCC=yes`` will force Sage to install GCC.
     884  Setting ``SAGE_INSTALL_GCC=no`` will prevent Sage from installing GCC.
    662885
    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.
     886- :envvar:`SAGE_INSTALL_CCACHE` - by default Sage doesn't install ccache,
     887  however by setting ``SAGE_INSTALL_CCACHE=yes`` Sage will install ccache.
     888  Because the Sage distribution is quite large, the maximum cache is set to 4G.
     889  This can be changed by running ``sage -sh -c "ccache --max-size=SIZE"``,
     890  where ``SIZE`` is specified in gigabytes, megabytes, or kilobytes by
     891  appending a "G", "M", or "K".
    669892
    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.
     893  Sage does not include the sources for ccache since it is an optional package.
     894  Because of this, it is necessary to have an Internet connection while
     895  building ccache for Sage, so that Sage can pull down the necessary
     896  sources.
    674897
    675 - :envvar:`SAGE_DEBUG` - enable debugging support. There are three
    676   different values:
     898- :envvar:`SAGE_DEBUG` - controls debugging support.
     899  There are three different possible values:
    677900
    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.
     901  * Not set (or set to anything else than "yes" or "no"): build binaries with
     902    debugging symbols, but no special debug builds.
     903    This is the default.
     904    There is no performance impact, only additional disk space is used.
    682905
    683   * ``SAGE_DEBUG=no``: no means no debugging symbols (that is, no
     906  * ``SAGE_DEBUG=no``: ``no`` means no debugging symbols (that is, no
    684907    ``gcc -g``), which saves some disk space.
    685908
    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
     909  * ``SAGE_DEBUG=yes``: build debug versions if possible (in particular,
     910    Python is built with additional debugging turned on and Singular is built
     911    with a different memory manager).
     912    These will be notably slower but, for example, make it much easier to
    690913    pinpoint memory allocation problems.
    691914
    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``.
     915- :envvar:`SAGE_SPKG_LIST_FILES` - if set to ``yes``, then enable verbose
     916  extraction of tar files, i.e. Sage's spkg files.
     917  Since some spkgs contain such a huge number of files that the log files
     918  get very large and harder to search (and listing the contained files is
     919  usually less valuable), we decided to turn this off by default.
     920  This variable affects builds of Sage with ``make`` (and ``sage --upgrade``)
     921  as well as the manual installation of individual spkgs with e.g. ``sage -i``
     922  or ``sage -f``.
    700923
    701 - :envvar:`SAGE_SPKG_INSTALL_DOCS` - Set this to "yes" to install
     924- :envvar:`SAGE_SPKG_INSTALL_DOCS` - if set to ``yes``, then install
    702925  package-specific documentation to
    703926  :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
     927  installed.
     928  This option may not be supported by all spkgs.
     929  Some spkgs might also assume that certain programs are available on the
    706930  system (for example, ``latex`` or ``pdflatex``).
    707931
    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.
     932- :envvar:`SAGE_DOC_MATHJAX` - by default, any LaTeX code in Sage's
     933  documentation is processed by MathJax.
     934  If this variable is set to ``no``, then MathJax is not used -- instead,
     935  math is processed using LaTeX and converted by dvipng to image files,
     936  and then those files are included into the documentation.
     937  Typically, building the documentation using LaTeX and dvipng takes longer
     938  and uses more memory and disk space than using MathJax.
    715939
    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.
     940- :envvar:`SAGE_BUILD_DIR` - the default behavior is to build each spkg in a
     941  subdirectory of :file:`$SAGE_ROOT/spkg/build/`; for example, build
     942  :file:`atlas-3.8.3.p12.spkg` in the directory
     943  :file:`$SAGE_ROOT/spkg/build/atlas-3.8.3.p12/`.
     944  If this variable is set, then build in
     945  :file:`$SAGE_BUILD_DIR/atlas-3.8.3.p12/` instead.
     946  If the directory :file:`$SAGE_BUILD_DIR` does not exist, it is created.
     947  As of this writing (Sage 4.8), when building the standard Sage packages,
     948  1.5 gigabytes of free space are required in this directory (or more if
     949  ``SAGE_KEEP_BUILT_SPKGS=yes`` -- see below); the exact amount of required
     950  space varies from platform to platform.
     951  For example, the block size of the file system will affect the amount of
     952  space used, since some spkgs contain many small files.
    729953
    730954  .. warning::
    731955
    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.
     956      The variable :envvar:`SAGE_BUILD_DIR` must be set to the full path name
     957      of either an existing directory for which the user has write permissions,
     958      or to the full path name of a nonexistent directory which the user has
     959      permission to create.
     960      The path name must contain **no spaces**.
    737961
    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.
     962- :envvar:`SAGE_KEEP_BUILT_SPKGS` - the default behavior is to delete each
     963  build directory -- the appropriate subdirectory of
     964  :file:`$SAGE_ROOT/spkg/build` or :file:`$SAGE_BUILD_DIR` -- after each spkg
     965  is successfully built, and to keep it if there were errors installing the
     966  spkg.
     967  Set this variable to ``yes`` to keep the subdirectory regardless.
     968  Furthermore, if you install an spkg for which there is already a
     969  corresponding subdirectory, for example left over from a previous build,
     970  then the default behavior is to delete that old subdirectory.
     971  If this variable is set to ``yes``, then the old subdirectory is moved to
     972  :file:`$SAGE_ROOT/spkg/build/old/` (or :file:`$SAGE_BUILD_DIR/old`),
     973  overwriting any already existing file or directory with the same name.
    751974
    752975  .. note::
    753976
    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.
     977      After a full build of Sage (as of version 4.8), these subdirectories can
     978      take up to 6 gigabytes of storage, in total, depending on the platform
     979      and the block size of the file system.
     980      If you always set this variable to ``yes``, it can take even more space:
     981      rebuilding every spkg would use double the amount of space, and any
     982      upgrades to spkgs would create still more directories, using still more
     983      space.
    761984
    762985  .. note::
    763986
    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``.
     987      In an existing Sage installation, running ``sage -i -s <package-name>``
     988      or ``sage -f -s <package-name>`` installs the spkg ``<package-name>`` and
     989      keeps the corresponding build directory; thus setting
     990      :envvar:`SAGE_KEEP_BUILT_SPKGS` to ``yes`` mimics this behavior when
     991      building Sage from scratch or when installing individual spkgs.
     992      So you can set this variable to ``yes`` instead of using the ``-s`` flag
     993      for ``sage -i`` and ``sage -f``.
    771994
    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::
     995- :envvar:`SAGE_FAT_BINARY` - to prepare a binary distribution that will run
     996  on the widest range of target machines, set this variable to ``yes`` before
     997  building Sage::
    775998
    776999      export SAGE_FAT_BINARY="yes"
    7771000      make
    7781001      ./sage --bdist x.y.z-fat
    7791002
    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:
     1003Variables to set if you're trying to build Sage with an unusual setup, e.g.,
     1004an unsupported machine or an unusual compiler:
    7821005
    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 ::
     1006- :envvar:`SAGE_PORT` - if you try to build Sage on a platform which is
     1007  recognized as being unsupported (e.g. AIX, or HP-UX), or with a compiler
     1008  which is unsupported (anything except GCC), you will see a message saying
     1009  something like::
    7871010
    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.
     1011      You are attempting to build Sage on IBM's AIX operating system,
     1012      which is not a supported platform for Sage yet. Things may or
     1013      may not work. If you would like to help port Sage to AIX,
     1014      please join the sage-devel discussion list -- see
     1015      http://groups.google.com/group/sage-devel
     1016      The Sage community would also appreciate any patches you submit.
    7971017
    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).
     1018      To get past this message and try building Sage anyway,
     1019      export the variable SAGE_PORT to something non-empty.
    8011020
    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.
     1021  If this is case and you want to try to build Sage anyway, follow the
     1022  directions: set :envvar:`SAGE_PORT` to something non-empty (and expect to
     1023  run into problems).
     1024
     1025- :envvar:`SAGE_USE_OLD_GCC` - the Sage build process requires GCC with a
     1026  version number of at least 4.0.1.
     1027  If the most recent version of GCC on your system is the older 3.4.x series
     1028  and you want to build with ``SAGE_INSTALL_GCC=no``, then set
     1029  :envvar:`SAGE_USE_OLD_GCC` to something non-empty.
     1030  Expect the build to fail in this case.
    8071031
    8081032Environment variables dealing with specific Sage packages:
    8091033
    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
     1034- :envvar:`SAGE_ATLAS_ARCH` - if you are compiling ATLAS (in particular,
     1035  if :envvar:`SAGE_ATLAS_LIB` is not set), you can use this environment
     1036  variable to set a particular architecture and instruction set extension.
     1037  The syntax is ``SAGE_ATLAS_ARCH=arch[,isaext1][,isaext2]...[,isaextN]``.
     1038  While ATLAS comes with precomputed timings for a variety of CPUs, it only
     1039  uses them if it finds an exact match.
     1040  Otherwise, ATLAS runs through a lengthy automated tuning process in order
     1041  to optimize performance for your particular system, which can take several
     1042  days on slow and unusual systems.
     1043  You drastically reduce the total Sage compile time if you manually select a
     1044  suitable architecture.
     1045  It is recommended to specify a suitable architecture on laptops or other
     1046  systems with CPU throttling or if you want to distribute the binaries.
     1047  Available architectures are
    8231048
    8241049    ``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``, ``P5``,
    8251050    ``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
     
    8281053    ``IA64Itan``, ``IA64Itan2``, ``USI``, ``USII``, ``USIII``,
    8291054    ``USIV``, ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``
    8301055
    831   and instruction set extensions are 
    832    
     1056  and instruction set extensions are
     1057
    8331058    ``AltiVec``, ``SSE3``, ``SSE2``, ``SSE1``, ``3DNow``.
    8341059
    8351060  In addition, you can also set
    8361061
    837   - ``SAGE_ATLAS_ARCH=fast`` picks defaults for a modern (2-3 year old)
     1062  - ``SAGE_ATLAS_ARCH=fast`` which picks defaults for a modern (2-3 year old)
    8381063    CPU of your processor line, and
    8391064
    840   - ``SAGE_ATLAS_ARCH=base`` picks defaults that should work for a ~10
     1065  - ``SAGE_ATLAS_ARCH=base`` which picks defaults that should work for a ~10
    8411066    year old CPU.
    8421067
    843   For example, 
     1068  For example,
    8441069
    8451070    ``SAGE_ATLAS_ARCH=Corei7,SSE3,SSE2,SSE1``
    8461071
    8471072  would be appropriate for a Core i7 CPU.
    8481073
    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/``.
     1074- :envvar:`SAGE_ATLAS_LIB` - if you have an installation of ATLAS on your
     1075  system and you want Sage to use it instead of building and installing its
     1076  own version of ATLAS, set this variable to be the directory containing your
     1077  ATLAS installation.
     1078  It should contain the files :file:`libatlas`, :file:`liblapack`,
     1079  :file:`libcblas`, and :file:`libf77blas` with extensions ``.a``, ``.so``, or
     1080  ``.dylib``.
     1081  For backward compatibility, the libraries may also be in the subdirectory
     1082  :file:`SAGE_ATLAS_LIB/lib/`.
    8571083
    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.
     1084- :envvar:`SAGE_MATPLOTLIB_GUI` - if set to anything non-empty except ``no``,
     1085  then Sage will attempt to build the graphical backend when it builds the
     1086  matplotlib package.
    8611087
    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:
     1088- :envvar:`INCLUDE_MPFR_PATCH` - this is used to add a patch to MPFR to bypass
     1089  a bug in the memset function affecting sun4v machines with versions of
     1090  Solaris earlier than Solaris 10 update 8 (10/09).
     1091  Earlier versions of Solaris 10 can be patched by applying Sun patch
     1092  142542-01.
     1093  Recognized values are:
    8671094
    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.
     1095  - ``INCLUDE_MPFR_PATCH=0`` - never include the patch - useful if you know all
     1096    sun4v machines Sage will be used are running Solaris 10 update 8 or later,
     1097    or have been patched with Sun patch 142542-01.
    8721098
    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.
     1099  - ``INCLUDE_MPFR_PATCH=1`` - always include the patch, so the binary will
     1100    work on a sun4v machine, even if created on an older sun4u machine.
    8761101
    877   If this variable is unset, include the patch on sun4v machines only.
     1102  - If this variable is unset, include the patch on sun4v machines only.
    8781103
    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.
     1104- :envvar:`SAGE_BINARY_BUILD` - used by the pil package.
     1105  If set to ``yes``, then force Sage to use the versions of libjpeg, libtiff
     1106  and libpng from :file:`$SAGE_ROOT/local/lib`.
     1107  Otherwise, allow the use of the system's versions of these libraries.
    8831108
    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.)
     1109- :envvar:`SAGE_PIL_NOTK` - used by the pil package.
     1110  If set to ``yes``, then disable building TK.
     1111  If this is not set, then this should be dealt with automatically: Sage tries
     1112  to build the pil package with TK support enabled, but if it runs into
     1113  problems, it tries building again with TK disabled.
     1114  So only use this variable to force TK to be disabled.
     1115  (Building the pil package is pretty fast -- less than a minute on many
     1116  systems -- so allowing it to build twice is not a serious issue.)
    8921117
    8931118Some standard environment variables which are used by Sage:
    8941119
    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.
     1120- :envvar:`CC` - while some programs allow you to use this to specify your C
     1121  compiler, **not every Sage package recognizes this**.
     1122  If GCC is installed within Sage, :envvar:`CC` is ignored and Sage's ``gcc``
     1123  is used instead.
    8991124
    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.
     1125- :envvar:`CPP` - similarly, this will set the C preprocessor for some Sage
     1126  packages, and similarly, using it is likely quite risky.
     1127  If GCC is installed within Sage, :envvar:`CPP` is ignored and Sage's ``cpp``
     1128  is used instead.
     1129
     1130- :envvar:`CXX` - similarly, this will set the C++ compiler for some Sage
     1131  packages, and similarly, using it is likely quite risky.
     1132  If GCC is installed within Sage, :envvar:`CXX` is ignored and Sage's ``g++``
     1133  is used instead.
    9041134
    9051135- :envvar:`FC` - similarly, this will set the Fortran compiler.
    9061136  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).
     1137  However, for historical reasons, the value is hardcoded during the initial
     1138  ``make`` and subsequent changes to ``$FC`` might be ignored (in which case,
     1139  the original value will be used instead).
    9101140  If GCC is installed within Sage, :envvar:`FC` is ignored and Sage's
    9111141  ``gfortran`` is used instead.
    9121142
    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.
     1143- :envvar:`CFLAGS`, :envvar:`CXXFLAGS` and :envvar:`FCFLAGS` - the flags for
     1144  the C compiler, the C++ compiler and the Fortran compiler, respectively.
     1145  The same comments apply to these: setting them may cause problems, because
     1146  they are not universally respected among the Sage packages.
    9181147
    919 The following Fortran-related environment variables are **deprecated**
    920 since Sage 5.3 and support for these will likely be removed.
     1148The following Fortran-related environment variables are **deprecated** since
     1149Sage 5.3 and support for these will likely be removed.
    9211150They are still recognized, but should not be used for new setups.
    9221151
    9231152- :envvar:`SAGE_FORTRAN` - the path to the Fortran compiler.
    9241153  Deprecated, use :envvar:`FC` instead.
    9251154
    9261155- :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
     1156  Normally, you don't need to set this.
     1157  If you really need to, you can add the directory containing the library to
    9291158  :envvar:`LIBRARY_PATH` and/or :envvar:`LD_LIBRARY_PATH`.
    9301159
    9311160Sage uses the following environment variables when it runs:
    9321161
    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.
     1162- :envvar:`DOT_SAGE` - this is the directory, to which the user has read and
     1163  write access, where Sage stores a number of files.
     1164  The default location is :file:`$HOME/.sage/`.
    9371165
    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``.
     1166- :envvar:`SAGE_STARTUP_FILE` - a file including commands to be executed every
     1167  time Sage starts.
     1168  The default value is :file:`$DOT_SAGE/init.sage`.
    9411169
    9421170- :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.
     1171  ``sage -i <package-name>``, Sage downloads the file from the web, using the
     1172  address ``http://www.sagemath.org/`` by default, or the address given by
     1173  :envvar:`SAGE_SERVER` if it is set.
     1174  If you wish to set up your own server, then note that Sage will search the
     1175  directories:
    9521176
    953 - :envvar:`SAGE_PATH` - a colon-separated list of directories which
    954   Sage searches when trying to locate Python libraries.
     1177  - ``SAGE_SERVER/packages/standard/``,
     1178  - ``SAGE_SERVER/packages/optional/``,
     1179  - ``SAGE_SERVER/packages/experimental/``,
     1180  - and ``SAGE_SERVER/packages/archive/``
    9551181
    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.
     1182  for packages.
     1183  See the script :file:`$SAGE_ROOT/spkg/bin/sage-spkg` for the implementation.
    9591184
    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.
     1185- :envvar:`SAGE_PATH` - a colon-separated list of directories which Sage
     1186  searches when trying to locate Python libraries.
    9631187
    964 - :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used
    965   on Mac OS X to set the :envvar:`DYLD_LIBRARY_PATH`.
     1188- :envvar:`SAGE_BROWSER` - on most platforms, Sage will detect the command to
     1189  run a web browser, but if this doesn't seem to work on your machine, set this
     1190  variable to the appropriate command.
     1191
     1192- :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET` - set this to something non-empty to
     1193  force Sage to set the :envvar:`LD_LIBRARY_PATH` variable before executing
     1194  system commands.
     1195
     1196- :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used on OS X to
     1197  set the :envvar:`DYLD_LIBRARY_PATH` variable.
    9661198
    9671199- :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".
     1200  :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`.
     1201  Set this to the base name of the BLAS library file on your system if you want
     1202  to override the default setting.
     1203  That is, if the relevant file is called :file:`libcblas_new.so` or
     1204  :file:`libcblas_new.dylib`, then set this to ``cblas_new``.
    9731205
    9741206Sage overrides the user's settings of the following variables:
    9751207
    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
     1208- :envvar:`MPLCONFIGDIR` - ordinarily, this variable lets the user set their
     1209  matplotlib config directory.
     1210  Due to incompatibilies in the contents of this directory among different
     1211  versions of matplotlib, Sage overrides the user's setting, defining it
     1212  instead to be :file:`$DOT_SAGE/matplotlib-VER`, with ``VER`` replaced by the
    9811213  current matplotlib version number.
    9821214
    9831215Variables dealing with doctesting:
    9841216
    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).
     1217- :envvar:`SAGE_TIMEOUT` - used for Sage's doctesting: the number of seconds
     1218  to allow a doctest before timing it out.
     1219  If this isn't set, the default is 360 seconds (6 minutes).
    9931220
    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
     1221- :envvar:`SAGE_TIMEOUT_LONG` - used for Sage's doctesting: the number of
     1222  seconds to allow a doctest before timing it out, if tests are run using
     1223  ``sage -t --long``.
     1224  If this isn't set, the default is 1800 seconds (30 minutes).
     1225
     1226- :envvar:`SAGE_PICKLE_JAR` - if you want to update the the standard pickle
     1227  jar, set this to something non-empty and run the doctest suite.
     1228  See the documentation for the functions :func:`picklejar` and
     1229  :func:`unpickle_all` in
     1230  :file:`$SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
    9991231  `here (picklejar)
    10001232  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.picklejar>`_
    10011233  and `here (unpickle_all)
    10021234  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.unpickle_all>`_.
    10031235
    1004 ..
    1005   THIS INDENTED BLOCK IS A COMMENT.  FIX IT ONCE WE UNDERSTAND
    1006   THESE VARIABLES.
     1236.. comment:
     1237    ***************************************************************************
     1238    FIX THIS!
    10071239
    1008   Variables dealing with valgrind and friends:
     1240    Variables dealing with valgrind and friends:
    10091241
    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.
     1242    - :envvar:`SAGE_TIMEOUT_VALGRIND` - used for Sage's doctesting: the
     1243      number of seconds to allow a doctest before timing it out, if tests
     1244      are run using ``??``.  If this isn't set, the default is 1024*1024
     1245      seconds.
    10141246
    1015   - :envvar:`SAGE_VALGRIND` - ?
     1247    - :envvar:`SAGE_VALGRIND` - trigger black magic in Python.
    10161248
    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"
     1249    - :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`,
     1250      :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS` - flags
     1251      used when using valgrind and one of the tools "memcheck", "massif",
     1252      "cachegrind", or "omega"
     1253    ***************************************************************************
     1254
    10211255
    10221256Installation in a Multiuser Environment
    10231257---------------------------------------
    10241258
    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.
     1259This section addresses the question of how a system administrator can install
     1260a single copy of Sage in a multi-user computer network.
    10281261
    10291262System-wide install
    10301263~~~~~~~~~~~~~~~~~~~
    10311264
    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.
     1265#. After building Sage, you may optionally copy or move the entire build tree
     1266   to :file:`/usr/local` or another location.
     1267   If you do this, then you must run ``./sage`` once so that various hardcoded
     1268   locations get updated.
     1269   For this reason, it might be easier to simply build Sage in its final
     1270   location.
    10371271
    1038 #. Make a symbolic link to the ``sage`` script in ``/usr/local/bin``::
     1272#. Make a symbolic link to the ``sage`` script in :file:`/usr/local/bin`::
    10391273
    10401274       ln -s /path/to/sage-x.y.z/sage /usr/local/bin/sage
    10411275
    10421276   Alternatively, copy the Sage script::
    10431277
    10441278       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``.
    10501279
    1051 #. Make sure that all files in the Sage tree are readable by all::
     1280   If you do this, make sure you edit the line::
    10521281
    1053        chmod a+rX -R /usr/local/sage-5.0
     1282       #SAGE_ROOT=/path/to/sage-version
     1283
     1284   at the beginning of the copied ``sage`` script according to the direction
     1285   given there to something like::
     1286
     1287       SAGE_ROOT=<SAGE_ROOT>
     1288
     1289   (note that you have to change ``<SAGE_ROOT>`` above!).
     1290   It is recommended not to edit the original ``sage`` script, only the copy at
     1291   :file:`/usr/local/bin/sage`.
     1292
     1293#. Make sure that all files in the Sage tree are readable by all
     1294   (note that you have to change ``<SAGE_ROOT>`` below!)::
     1295
     1296       chmod a+rX -R <SAGE_ROOT>
    10541297
    10551298#. Optionally, you can test Sage by running::
    10561299
    10571300       make testlong
    1058    
     1301
    10591302   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.
     1303   processes.
     1304   You can also omit ``long`` to skip tests which take a long time.
     1305
     1306Sagetex
     1307~~~~~~~
     1308
     1309To make SageTeX available to your users, see the instructions for
     1310:ref:`installation in a multiuser environment <sagetex_installation_multiuser>`
     1311.
     1312
    10621313
    10631314Some common problems
    10641315--------------------
     
    10661317ATLAS
    10671318~~~~~
    10681319
    1069 Sometimes the ATLAS spkg can fail to build.  Some things to check for:
     1320Sometimes the ATLAS spkg can fail to build.
     1321Some things to check for:
    10701322
    1071 - Make sure that CPU throttling mode (= power-saving mode) is turned off
     1323- Make sure that CPU throttling mode (i.e. power-saving mode) is turned off
    10721324  when building ATLAS.
    10731325
    1074 - Also, the ATLAS build can fail if the system load is too high, and in
     1326- The ATLAS build can also fail if the system load is too high, and in
    10751327  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.
     1328  ``MAKE='make -jNUM'`` with ``NUM`` large.
     1329  If this happens, just try running ``make`` again.
     1330  If ``make`` fails after five or six attempts, report your problem to the
     1331  sage-devel mailing list at http://groups.google.com/group/sage-devel.
    10791332
    1080 Special Notes
    1081 -------------
     1333zn_poly
     1334~~~~~~~
    10821335
    1083 - To make SageTeX available to your users, see the instructions for
    1084   :ref:`installation in a multiuser environment
    1085   <sagetex_installation_multiuser>`.
     1336It has been reported (see :trac:`13947`) that the zn_poly spkg fails to build
     1337on loaded systems, especially on Mac OS X and Cygwin.
     1338If you encounter this problem, you can try to build zn_poly serially before
     1339reissuing ``make``::
    10861340
    1087   **This page was last updated in August 2012 (Sage 5.3).**
     1341    MAKE="make -j1" ./sage -i zn_poly && make
     1342
     1343
     1344**This page was last updated in April 2013 (Sage 5.8).**