Ticket #11081: 11081-install-from-source-Additional-information.patch

File 11081-install-from-source-Additional-information.patch, 23.2 KB (added by drkirkby, 10 years ago)

Additioanl information, addressing reviewer comments. To be applied after 11081-install-from-source.patch

  • doc/en/installation/source.rst

    # HG changeset patch
    # User David Kirkby <david.kirkby@onetel.net>
    # Date 1301881526 -3600
    # Node ID b209299d7bde80999b373971fc3bc1e7f9240c3d
    # Parent  837f67c11453b4fc45671f6ca6f32f88bdc16e4d
    #11081 Additional information to add to the manual about installing Sage from source.
    
    diff -r 837f67c11453 -r b209299d7bde doc/en/installation/source.rst
    a b  
    1 
    21Install from Source Code
    32========================
    43
    54More familiarity with computers may be required to build Sage from
    6 source. If you do have all the pre-requisite tools, the process should
    7 be completely painless. It would take your computer a while to
    8 compile Sage from source, though you don't have to watch. Compiling
    9 Sage from source has the major advantage that you have the latest
     5the `source code <http://en.wikipedia.org/wiki/Source_code>`_. If you do have all the
     6pre-requisite tools, the process should
     7be completely painless. It will take your computer a while to
     8compile Sage from the source code, although you don't have to watch. Compiling
     9Sage from the source code has the major advantage that you have the latest
    1010version of Sage with which you can change absolutely any part
    11 or the programs on which Sage depends. Also, some parts of Sage
    12 will be optimised for your particular computer, so will run faster
    13 than a binary that you have downloaded. You can also recompile Sage.
     11or the programs on which Sage depends. You can also recompile Sage.
     12Also, some parts of Sage will be optimised for your particular computer,
     13so will run faster than a binary that you have downloaded.
    1414
    15 See http://wiki.sagemath.org/SupportedPlatforms for the list of
    16 platforms on which Sage is supported and the level of support
    17 for these systems.
     15Sage is supported on a number of
     16`Linux <http://en.wikipedia.org/wiki/Linux>`_
     17, Mac `OS X <http://www.apple.com/macosx/>`_ , Sun/Oracle `Solaris <http://www.oracle.com/solaris>`_ and
     18`OpenSolaris <http://en.wikipedia.org/wiki/OpenSolaris>`_
     19releases, but Sage is not supported on all versions of Linux, OS X,
     20Solaris or OpenSolaris. Depending on the `operating system <http://en.wikipedia.org/wiki/Operating_system>`_, Sage works
     21with `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
     22installs on `Microsoft Windows <http://en.wikipedia.org/wiki/Microsoft_Windows>`_, although Sage can be used on Windows
     23with the aid of a  `virtual machine <http://en.wikipedia.org/wiki/Virtual_machine>`_ .
     24Go to http://www.sagemath.org/download-windows.html
     25to download a version of Sage for Windows. See http://wiki.sagemath.org/SupportedPlatforms
     26for the list of platforms on which Sage is supported and the level of support
     27for these systems. You will also find details about `ports <http://en.wikipedia.org/wiki/Computer_port_%28software%29>`_
     28to other operating systems or processors which may be taking place.
    1829
    19 Assumptions: You have a computer with about 2 GB of free
    20 disk space running one of the supported operating systems listed at
     30Assumptions: You have a computer with about 2.5 GB of free
     31disk space running one of the supported version of an
     32operating system listed at
    2133http://wiki.sagemath.org/SupportedPlatforms
    2234The following standard
    23 command-line development tools must be installed on your computer
    24 (under OS X they all come with XCode):
     35command-line development tools must be installed on your computer.
     36(Under OS X they all come with `Xcode <http://developer.apple.com/xcode/>`_, with the exception of the
     37`Fortran <http://en.wikipedia.org/wiki/Fortran>`_ compiler ``gfortran``.
     38However, Sage includes an `executable <http://en.wikipedia.org/wiki/Executable>`_
     39Fortran compiler for OS X, so there is no need to install
     40a Fortran compiler on OS X):
    2541
    2642::
    2743
    28        gcc        (Version 4.0.1 or higher)
    29        g++        (Version 4.0.1 or higher)
    30        gfortran   (Version 4.0.1 or higher)
    31        make       (The GNU version)
    32        m4
    33        perl       (Version 5.8.0 or higher)
     44       gcc        (Version 4.0.1 or later)
     45       g++        (Version 4.0.1 or later)
     46       gfortran   (Version 4.0.1 or later)
     47       make       (GNU make, version 3.80 or later)
     48       m4         
     49       perl       (Version 5.8.0 or later)
    3450       ranlib
    35        tar        (The GNU version)
     51       tar        (GNU tar, version 1.17 or later)
    3652       ssh-keygen (Needed to run the notebook in secure mode)
    3753       latex      (Highly recommended, though not strictly required)
    3854
     55The programs ``gcc``, ``g++`` and ``gfortran`` are all part of the `GNU Compiler Collection (GCC) <http://gcc.gnu.org/>`_.
    3956To check if you have ``m4`` installed, for example, type ``command -v m4``
    40 at a command line. If it gives an error (or returns nothing), then
    41 either ``m4`` is not installed, or it is installed but not in your PATH
    42 (On Solaris, ``m4`` resides in ``/usr/ccs/bin``).
    43 It is highly recommended that you have LaTeX
     57on the command line. If it gives an error (or returns nothing), then
     58either ``m4`` is not installed, or it is installed but not in your
     59`PATH <http://en.wikipedia.org/wiki/PATH_%28variable%29>`_
     60(On Solaris 10, ``m4`` resides in ``/usr/ccs/bin``).
     61It is highly recommended that you have `Latex <http://en.wikipedia.org/wiki/LaTeX>`_
    4462installed, but it is not required. If you don't have ``ssh-keygen`` on your
    4563local system, then you cannot run the notebook in secure mode, which the uses
    46 encrypted HTTPS protocol. To run it in secure mode, run the command
    47 ``notebook(secure=True)``
    48 instead of ``notebook()``, which uses the HTTP protocol.
     64encrypted `HTTPS <http://en.wikipedia.org/wiki/HTTP_Secure>`_ protocol. To run the notebook in secure mode, type the command
     65``notebook(secure=True)`` instead of ``notebook()``. Unless ``notebook(secure=True)``
     66is used, the notebook uses the less secure `HTTP <http://en.wikipedia.org/wiki/HTTP>`_ protocol
    4967
    50 In OS X, make sure you have XCode version at least 2.4, i.e., ``gcc -v``
    51 should output build at least 5363. If you don't, go to
    52 http://developer.apple.com/ sign up, and download the free Xcode
    53 package.
     68In OS X, make sure you have a recent version of `Xcode <http://developer.apple.com/xcode/>`_.
     69See http://wiki.sagemath.org/SupportedPlatforms to find out what
     70version(s) of Xcode are supported. You can get the latest Xcode
     71from http://developer.apple.com/xcode/, but may have to pay a small
     72fee in order to download this.
    5473
    55 On a Debian-based system (e.g., Ubuntu), ranlib is in the binutils
    56 package. On a newly installed Ubuntu system (this was tested on
    57 Ubuntu 9.04), you can install the above commands as follows:
     74On Linux systems (e.g., Ubuntu, Redhat etc), ``ranlib`` is in the
     75`Binutils <http://www.gnu.org/software/binutils/>`_ package.
     76Assuming you have sufficient privileges,
     77you can install the ``binutils`` and other necessary components. If you
     78do not have the privilegesto do this, ask your system
     79administrator to do this, or build the components from source
     80code. The method of installing additional software varies from
     81distribution to distribution
     82but 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:
    5883
    5984::
    6085
    6186     sudo apt-get install build-essential m4 gfortran
    6287
     88(this was tested on Ubuntu 9.04).
     89
     90On other Linux systems you might use `rpm <http://en.wikipedia.org/wiki/RPM_Package_Manager>`_,
     91`yum <http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified>`_ or other package manager. On
     92Solaris you would use ``pkgadd`` and on OpenSolaris use ``ipf``. Check
     93the documentation for your particular operating system.
     94
    6395The LaTeX package and a PDF previewer are optional but they can be
    6496installed using
    6597
     
    71103which is quite easy, though a rather time-consuming process. 
    72104
    73105(You must have the GNU version of ``make`` installed and it must be the first
    74 ``make`` in your PATH. On Solaris, a version of GNU ``make`` may be found
     106``make`` in your PATH. On Solaris 10, a version of GNU ``make`` may be found
    75107at ``/usr/sfw/bin/gmake`` but you will need to copy it somewhere else
    76 and rename it to ``make``. The same is true for GNU tar - there is a version
    77 called ``gtar`` in ``/usr/sfw/bin`` but it will need to be copied somwhere
     108and rename it to ``make``. The same is true for GNU ``tar`` - there is a version
     109called ``gtar`` in ``/usr/sfw/bin`` but it will need to be copied somewhere
    78110else and renamed to ``tar``.
    79111
    80112For Solaris, it is recommended you create a directory ``$HOME/bins-for-sage`` and
    81113put the GNU versions of ``tar`` and ``make`` in that directory. Then ensure that
    82114``$HOME/bins-for-sage`` is first in your PATH. That's because Sage also needs
    83 ``/usr/ccs/bin`` in your PATH to get programs like ``ar`` and ``ranlib`,
     115``/usr/ccs/bin`` in your PATH to execute programs like ``ar`` and ``ranlib`,
    84116but ``/usr/ccs/bin`` has the Sun/Oracle versions of ``make`` and ``tar``
    85 which are unsuitable for buidling Sage. For more information on
     117which are unsuitable for building Sage. For more information on
    86118building Sage on Solaris, see http://wiki.sagemath.org/solaris
    87119
    88 Although some of Sage is written in Python, you do not need Python
     120Although some of Sage is written in `Python <http://www.python.org/>`_, you do not need Python
    89121pre-installed on your computer, since the Sage installation
    90 includes everything you need. When the installation program is run,
     122includes virtually everything you need. When the Sage installation program is run,
    91123it will check that you have each of the above-listed prerequisites,
    92 and inform you of any that are missing.
     124and inform you of any that are missing, or have unsuitable verisons.
    93125
    94 -  If you want to use Tcl/Tk libraries in Sage,
    95    do the following preferably before compilation.
     126-  If you want to use `Tcl/Tk <http://www.tcl.tk/>`_ libraries in Sage,
     127   do the following before compiling Sage.
    96128   Sage's Python will automatically recognize your system's
    97129   install of Tcl/Tk if it exists. You need to install the
    98130   Tcl/Tk development libraries though, not just the Tck/Tk base.
    99131
    100    On Ubuntu, this is the command::
     132   On `Ubuntu <http://www.ubuntu.com/>`_, this is the command::
    101133
    102134       sudo apt-get install tk8.5-dev    # or the latest version available
    103135
    104    Now you can install Sage and Sage's Python will automatically
    105    recognize your system's install of Tcl/Tk. If you forgot
     136   Now you can install Sage, If you forgot
    106137   and installed Sage first anyway, all is not lost.
    107138   Just issue the command::
    108139
     
    122153
    123154-  Sage developers tend to use fairly recent versions of gcc, but
    124155   Sage should compile with any gcc of at least version 4.0.1
    125    If you are interested in working on support for compilers
    126    from HP, IBM, Intel, Sun/Oracle etc,
     156   If you are interested in working on support for commerical compilers
     157   from `HP <http://docs.hp.com/en/5966-9844/ch01s03.html>`_,
     158   `IBM <http://www-01.ibm.com/software/awdtools/xlcpp/>`_,
     159   `Intel <http://software.intel.com/en-us/articles/intel-compilers/>`_,
     160   `Sun/Oracle <http://www.oracle.com/technetwork/server-storage/solarisstudio/overview/index.html>`_ etc,
     161   or the open-source `Clang <http://clang.llvm.org/>`_,
    127162   please email the sage-devel mailing list, otherwise known as the
    128163   sage-devel Google group at
    129164   http://groups.google.com/group/sage-devel
    130165
    131 -  ``perl`` is required because both the NTL and PARI
    132    configuration scripts are written in Perl. R also needs perl.
    133 
    134 
    135 
    136166After extracting the Sage tarball, the subdirectory ``spkg`` contains
    137167the source distributions for everything on which Sage depends. We
    138168emphasize that all of this software is included with Sage, so you
    139169do not have to worry about trying to download and install any one
    140170of these packages (such as GAP, for example) yourself.
    141171
    142 On tests using various Linux computer systems, the known problems
    143 are:
    144 
    145 
    146 -  Does not build with gcc 4.3.0 yet, but work is ongoing to fix
    147    that.
    148 
    149 -  Moving the build after compiling breaks the PARI Galois fields
    150    database, which appears to be hardcoded into the PARI binary.
    151    (Somebody help fix this!)
    152 
    153 
    154172Fortran
    155173-------
    156174 
    157 On Linux and Solaris systems, a working Fortran compiler is required
     175On Linux, Solaris and OpenSolaris systems, a working Fortran compiler is required
    158176for building Sage from source. If you are using Fortran on a platform
    159 for which Sage does not include g95 binaries, you must use a
    160 system-wide gfortran. You need to explicitly tell the Sage build process
     177for which Sage does not include g95 binaries, you must use
     178``gfortran``, which may be installed system wide (e.g in /usr or
     179/usr/local) or your own private copy.  You need to explicitly
     180tell the Sage build process
    161181about the Fortran compiler and library location. Do this by typing ::
    162182
    163183    export SAGE_FORTRAN=/exact/path/to/gfortran
     
    179199compiler for Mac OS X. This Fortran compiler is used, unless you
    180200specify another Fortran compiler via the variable :envvar:`SAGE_FORTRAN`.
    181201
    182 On platforms such as AIX, HP-UX, and Solaris, where both 32- and
     202On operating systems such as `AIX <http://en.wikipedia.org/wiki/IBM_AIX>`_,
     203`HP-UX <http://en.wikipedia.org/wiki/HP-UX>`_, and Solaris, where both 32-bit and
    18320464-bit builds are supported, the library path variable
    184205:envvar:`SAGE_FORTRAN_LIB` must point to the 32-bit library if you are
    185206building Sage in 32-bit. Also, :envvar:`SAGE_FORTRAN_LIB` must point to a
     
    202223    # 64-bit x64
    203224    SAGE_FORTRAN_LIB=/path/to/gcc/install/directory/lib/amd64/libgfortran.so
    204225
     226(It should be noted that Sage is not supported on AIX or HP-UX, although some
     227efforts have been made to `port Sage to AIX <http://wiki.sagemath.org/AIX>`_ and
     228to `port Sage to HP-UX <http://wiki.sagemath.org/HP-UX>`_.)
    205229
    206230Steps to Install from Source
    207231----------------------------
     
    244268#. Optional (but highly recommended): Read the ``README.txt`` file
    245269   there.
    246270
     271#. On OSX 10.4, OS 10.5, Solaris 10 and OpenSolaris, if you wish to
     272   build a 64-bit version of Sage, then assuming your computer and
     273   operating system are 64-bit, type
     274
     275   ::
     276
     277           SAGE64=yes
     278           export SAGE64
     279   
     280   It should be noted that at the time of writing (April 2011), 64-bit
     281   builds of Sage on both Solaris 10 and OpenSolaris are not very stable,
     282   so you are advised not to set ``SAGE64`` to ``yes``. This will then
     283   create stable 32-bit versions of Sage.
     284   See http://wiki.sagemath.org/SupportedPlatforms  and
     285   http://wiki.sagemath.org/solaris for the latest information, as
     286   work is ongoing to resolve the 64-bit Solaris & OpenSolaris problems.
     287
    247288#. Type
    248289
    249290   ::
     
    254295   to be logged in as root, since no files are changed outside of the
    255296   ``sage-x.y.z`` directory (with one exception -- the ``.ipythonrc``
    256297   directory is created in your ``HOME`` directory if it doesn't exist).
    257    This command does the usual steps for each of the packages, but puts
    258    all the results in the local build tree. This can take close to an hour
    259    on some machines. Depending on the architecture of your system (e.g.,
    260    Celeron, Pentium Mobile, Pentium 4, etc.), it can take over three hours
    261    to build Sage from source. If the build is successful, you will not see
     298   In fact, **it is inadvisable to build Sage as root**, as the root account
     299   should only be used when absolutely necessary, as mis-typed commands
     300   can have serious consequences if you are logged in as root.  There has been a bug
     301   `reported <http://trac.sagemath.org/sage_trac/ticket/9551/>`_ in Sage
     302   which would have overwritten a system file had the user been logged in
     303   as root.
     304
     305   Typing ``make`` does the usual steps for each of the packages, but puts
     306   all the results in the local build tree. Depending on the architecture of your system (e.g.,
     307   Celeron, Pentium Mobile, Pentium 4, SPARC, etc.), it can take over three hours
     308   to build Sage from source. On slower older hardware it can take over
     309   a day to build Sage. If the build is successful, you will not see
    262310   the word ERROR in the last 3-4 lines of output.
    263311
    264        The directory where you built Sage is NOT hardcoded. You should
    265        be able to safely move or rename that directory. (It's a bug if
    266        this is not the case --- unfortunately there is one
    267        bug which hasn't yet been fixed along these lines, namely the PARI
    268        install hard-codes the location of the "galois data" files. Fixes
    269        welcome!)
     312   If the build of Sage fails, then type the following from the directory
     313   where you typed ``make``.
    270314
     315   ::
    271316
    272    After you build Sage, you may optionally copy or move the entire
    273    build tree to ``/usr/local``. You might also copy the ``sage-*/sage``
    274    script to ``/usr/local/bin/`` and edit ``ROOT="....."`` at the top of
    275    that file.
     317            grep "An error occurred" spkg/logs/*
     318 
     319   then paste the contents of the log file(s) with errors to the Sage
     320   support newsgroup http://groups.google.com/group/sage-support
     321   If the log files are very large (and many are), then don't paste
     322   the whole file, but make sure to include any error messages.
     323
     324   The directory where you built Sage is NOT hardcoded. You should
     325   be able to safely move or rename that directory. (It's a bug if
     326   this is not the case)
    276327
    277328#. To start Sage, change into the Sage home directory and type:
    278329
     
    281332             ./sage
    282333
    283334   You should see the Sage prompt, which will look something like this
    284    (starting the first time can take a few minutes):
     335   (starting the first time should take well under a minute, but can
     336   take several minutes if the file system is slow or busy. Since Sage
     337   opens a lot of files, it is preferable to install Sage on a fast file
     338   system if this is possible.):
    285339
    286340   ::
    287341
     
    295349   Just starting successfully tests that many of the components built
    296350   correctly. If the above is not displayed (e.g., if you get a
    297351   massive traceback), please report the problem, e.g., to
    298    http://groups.google.com/group/sage-support . Please include in
    299    your email the file ``install.log``. It would also be helpful to
    300    include the type of operating system you have and the version
    301    number (and date) of the copy of Sage you are using. (There are no
     352   http://groups.google.com/group/sage-support .
     353   It would also be helpful to
     354   include the type of operating system (Linux, OS X, Solaris or OpenSolaris),
     355   the version and date of that operating system and the version
     356   number of the copy of Sage you are using. (There are no
    302357   formal requirements for bug reports - just send them; we appreciate
    303358   everything.)
    304359
     
    375430
    376431#. Optional: Check the interfaces to any other software that
    377432   you have available. Note that each interface calls its
    378    corresponding program by a particular name: Mathematica is invoked
    379    by calling ``math``, Maple by calling ``maple``, et cetera. The
     433   corresponding program by a particular name:
     434   `Mathematica <http://www.wolfram.com/mathematica/>`_ is invoked
     435   by calling ``math``, `Maple <http://www.maplesoft.com/>`_ by calling ``maple``, etc. The
    380436   easiest way to change this name or perform other customizations is
    381437   to create a redirection script in ``$SAGE_ROOT/local/bin``. Sage
    382438   inserts this directory at the front of your PATH, so your script
     
    447503   Alternatively, from within ``$SAGE_ROOT``, you can type
    448504   ``make test`` to run all the standard test code.  This can take
    449505   from 25 minutes to several hours, depending on your hardware. On
    450    very old hardware building Sage can take several days!
     506   very old hardware building and testing Sage can take several days!
    451507
    452508#. Optional: Install optional Sage packages and databases. Type
    453509   ``sage -optional`` to see a list or visit
     
    725781System-wide install
    726782~~~~~~~~~~~~~~~~~~~
    727783
    728 This is a compilation of posts to the Sage support list - in
    729 particular those of Luis Finotti.
     784#. After you build Sage, you may optionally copy or move the entire
     785   build tree to ``/usr/local``.
    730786
    731 **Note from David Kirkby.** I would suggest the root account should
    732 only be used when absolutely necessary - that would not include
    733 building programs like Sage. When logged in as root, one mis-typed command can
    734 leave your system totally unbootable and lose all your data. Also, a mistake
    735 in the Sage souce code could
    736 overwrite your system files, as `documented here <http://trac.sagemath.org/sage_trac/ticket/9551/>`_. If you build Sage as root, you do so at your own risk.
    737 
    738 #. Unpack the current Sage tarball (we shall assume it is
    739    ``sage-4.6.2.tar``) at, e.g., ``/usr/local/`` and compile it as root.
    740    Assuming you are in a root shell and the tarball is in your current
    741    directory, type:
    742 
    743    ::
    744 
    745        cp sage-4.6.2.tar /usr/local
    746        cd /usr/local
    747        tar xvf sage-4.6.2.tar
    748        cd sage-4.6.2/
    749        make
    750 
    751     (Comment: It's better to build in place.  It's a bug if anything goes
    752     wrong when relocating the entire tarball -- unfortunately there
    753     is one bug I haven't fixed along these lines, namely the
    754     PARI install hard-codes the location of the "galois data" files.
    755     (Fixes welcome!).)
    756 
    757 #. Make sure to modify the line with the ``.....``"'s at the top of the
    758    ``sage`` script. In other words, edit ``SAGE_ROOT="....."`` to say
    759    ``SAGE_ROOT="/usr/local/sage-4.6.2"``.
    760 
    761 #. There are some initial files that have to be created during the
    762    first run of Sage. Try starting up Sage once as root (or, to be
     787#. There are some initial files that have to be created the first time
     788   Sage is run. Try starting up Sage once as root (or, to be
    763789   more thorough, try ``make test`` as root to run all the standard test
    764790   code). You can stop the tests by pressing ``ctrl-z`` followed by
    765791   typing ``kill %1`` (assuming you had no other jobs in the
     
    771797
    772798       cp /usr/local/sage-4.6.2/sage /usr/local/bin/
    773799
    774    You make a copy instead of a symlink, since upgrading with
    775    ``sage -upgrade`` overwrites ``/usr/local/sage-4.6.2/sage``, hence
    776    deleting the ``ROOT=...`` part of that file.
    777 
    778800   Make sure that all files in ``/usr/local/sage-4.6.2`` are readable by
    779801   all:
    780802
     
    788810
    789811
    790812-  (Found by Dorian Raymer) Sage will not build if you have only
    791    bison++. You should uninstall bison++ and install bison.
     813   bison++. You should uninstall bison++ and install `bison <http://www.gnu.org/software/bison/>`_.
    792814
    793815-  (Found by Peter Jipsen) If you get an error like
    794816
     
    798820            cannot restore segment prot after reloc:
    799821       Permission denied
    800822
    801    then your SELinux configuration is preventing Sage from launching. To
     823   then your `SELinux <http://fedoraproject.org/wiki/SELinux>`_ configuration is preventing Sage from launching. To
    802824   rectify this issue, you can either change the default security
    803825   context for Sage (??) or disable SELinux altogether by setting the
    804826   line ``SELINUX=disabled`` in your ``/etc/sysconfig/selinux`` file.
     
    806828- To make SageTeX available to your users, see the instructions for
    807829  :ref:`installation in a multiuser environment
    808830  <sagetex_installation_multiuser>`.
     831
     832  **This page was last updated in April 2011**