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

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

Mercurial patch for changes to documentation. I hope this is an improvement, and hope requested changes don't drag on for a long time.

  • doc/en/installation/source.rst

    # HG changeset patch
    # User David Kirkby <david.kirkby@onetel.net>
    # Date 1301407867 -3600
    # Node ID 9e3f5e6c45b7689c6719c3febd19b68e43c4fcf9
    # Parent  4fbd7d43079b02f3dd0a31af6e699c479cd26193
    #11081 Update the "Install from Source Code" section of the Sage Installation Guide
    
    diff -r 4fbd7d43079b -r 9e3f5e6c45b7 doc/en/installation/source.rst
    a b  
    55More familiarity with computers may be required to build Sage from
    66source. If you do have all the pre-requisite tools, the process should
    77be completely painless. It would take your computer a while to
    8 compiled Sage from source, though you don't have to watch. Compiling
     8compile Sage from source, though you don't have to watch. Compiling
    99Sage from source 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. You can also recompile Sage.
     11or the programs on which Sage depends. Also, some parts of Sage
     12will be optimised for your particular computer, so will run faster
     13than a binary that you have downloaded. You can also recompile Sage.
    1214
    13 As of this writing, Sage is known to work on Linux (32-bit x86, 64-bit
    14 x86-64, IA64, or 32-bit PPC) and OS X (10.4, 10.5, 10.6, PPC or
    15 x86, 32-bit only). (See http://wiki.sagemath.org/SupportedPlatforms
    16 for the latest information.)
    17 
    18     **Solaris? FreeBSD? OS X 10.5 in 64 bit mode?**: Complete compilation
    19     of Sage is currently not supported on Solaris or \*BSD. It is
    20     possible to compile most of Sage on Solaris machines and to fill in
    21     the extra parts using standard packages; please email sage-devel if
    22     you desperately need to run Sage on Solaris. We do plan to fully
    23     support Solaris - it's a very important platform. Work is ongoing.
    24 
    25     **Sage on FreeBSD**: The binaries can be run with the help of Linux
    26     emulation. We are working on a fully native port and the number of
    27     issues that need to be fixed are relatively small compared to the
    28     other ports.
    29 
    30     We hope to support OS X 10.5 in 64-bit mode in our next
    31     release. You can find some instructions to build Sage on OS X 10.5
    32     in 64-bit mode at
    33     http://mvngu.wordpress.com/2009/09/02/compile-sage-4-1-in-64-bit-mode-on-os-x-10-5-8/
    34 
     15See http://wiki.sagemath.org/SupportedPlatforms for the list of
     16platforms on which Sage is supported and the level of support
     17for these systems.
    3518
    3619Assumptions: You have a computer with about 2 GB of free
    37 disk space running Linux (32-bit or 64-bit), Mac OS X 10.4, 10.5, or
    38 10.6 with XCode. In particular, under Linux the following standard
     20disk space running one of the supported operating systems listed at
     21http://wiki.sagemath.org/SupportedPlatforms
     22The following standard
    3923command-line development tools must be installed on your computer
    4024(under OS X they all come with XCode):
    4125
    4226::
    4327
    44        gcc
    45        g++
    46        gfortran
    47        make
     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)
    4832       m4
    49        perl
     33       perl       (Version 5.8.0 or higher)
    5034       ranlib
    51        tar
    52        readline and its development headers
    53        ssh-keygen -- needed to run the notebook in secure mode.
    54        latex -- highly recommended, though not strictly required
     35       tar        (The GNU version)
     36       ssh-keygen (Needed to run the notebook in secure mode)
     37       latex      (Highly recommended, though not strictly required)
    5538
    56 To check if you have ``m4`` installed, for example, type ``which m4``
     39To check if you have ``m4`` installed, for example, type ``command -v m4``
    5740at a command line. If it gives an error (or returns nothing), then
    58 it is not installed. It is highly recommended that you have LaTeX
    59 installed, but not required. If you don't have ``ssh-keygen`` on your
    60 local system, then you cannot run the notebook in secure mode. To
    61 run it in insecure mode, run the command ``notebook(secure=False)``
    62 instead of ``notebook()``.
     41either ``m4`` is not installed, or it is installed but not in your PATH
     42(On Solaris, ``m4`` resides in ``/usr/ccs/bin``).
     43It is highly recommended that you have LaTeX
     44installed, but it is not required. If you don't have ``ssh-keygen`` on your
     45local system, then you cannot run the notebook in secure mode, which the uses
     46encrypted HTTPS protocol. To run it in secure mode, run the command
     47``notebook(secure=True)``
     48instead of ``notebook()``, which uses the HTTP protocol.
    6349
    6450In OS X, make sure you have XCode version at least 2.4, i.e., ``gcc -v``
    6551should output build at least 5363. If you don't, go to
    6652http://developer.apple.com/ sign up, and download the free Xcode
    67 package. Only OS X :math:`$\geq 10.4$` is supported. This will give
    68 you all of the above commands.
     53package.
    6954
    7055On a Debian-based system (e.g., Ubuntu), ranlib is in the binutils
    7156package. On a newly installed Ubuntu system (this was tested on
     
    7560
    7661     sudo apt-get install build-essential m4 gfortran
    7762
    78 It is recommended that you install the readline package and its
    79 corresponding development headers. These packages make it easier to
    80 work with the Sage command line interface by providing text editing
    81 features at the command line level. On a Debian or Ubuntu system, use
    82 the following commands to install the readline library and its
    83 development headers:
    84 
    85 ::
    86 
    87     sudo apt-get install readline-common libreadline-dev
    88 
    8963The LaTeX package and a PDF previewer are optional but they can be
    9064installed using
    9165
     
    9367
    9468    sudo apt-get install texlive xpdf evince xdvi
    9569
    96 (You must have the GNU version of ``make`` installed.
    97 For example, Sage won't build on a FreeBSD install that doesn't
    98 have the optional GNU version of ``make`` installed as well
    99 (and named ``make``).)
     70On other systems it might be necessary to install TeX Live from source code,
     71which is quite easy, though a rather time-consuming process. 
     72
     73(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
     75at ``/usr/sfw/bin/gmake`` but you will need to copy it somewhere else
     76and rename it to ``make``. The same is true for GNU tar - there is a version
     77called ``gtar`` in ``/usr/sfw/bin`` but it will need to be copied somwhere
     78else and renamed to ``tar``.
     79
     80For Solaris, it is recommended you create a directory ``$HOME/bins-for-sage`` and
     81put the GNU versions of ``tar`` and ``make`` in that directory. Then ensure that
     82``$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`,
     84but ``/usr/ccs/bin`` has the Sun/Oracle versions of ``make`` and ``tar``
     85which are unsuitable for buidling Sage. For more information on
     86building Sage on Solaris, see http://wiki.sagemath.org/solaris
    10087
    10188Although some of Sage is written in Python, you do not need Python
    10289pre-installed on your computer, since the Sage installation
     
    119106   and installed Sage first anyway, all is not lost.
    120107   Just issue the command::
    121108
    122        sage -f python-2.5.2.p8    # or the latest version available
     109       sage -f  python-2.6.4.p9    # or the latest version available
    123110
    124111   after installing the Tcl/Tk development libraries as above.
    125112   If
     
    133120
    134121   does not raise an ``ImportError`` then it worked.
    135122
    136 -  Sage is currently being developed using GCC version 4.3.x, and
    137    is likely to compile fine with other GCC versions in the 4.x
    138    series. It does not work with older GCC releases. If you are
    139    interested in working on support for Intel or Sun's CC compiler,
     123-  Sage developers tend to use fairly recent versions of gcc, but
     124   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,
    140127   please email the sage-devel mailing list, otherwise known as the
    141128   sage-devel Google group at
    142129   http://groups.google.com/group/sage-devel
    143130
    144 One reason ``perl`` is required is that both the NTL and PARI
    145    configuration scripts are written in Perl.
     131``perl`` is required because both the NTL and PARI
     132   configuration scripts are written in Perl. R also needs perl.
    146133
    147134
    148135
     
    170157On Linux and Solaris systems, a working Fortran compiler is required
    171158for building Sage from source. If you are using Fortran on a platform
    172159for which Sage does not include g95 binaries, you must use a
    173 system-wide gFortran. For example, Solaris 10 does not ship with any
    174 Fortran binaries. You need to explicitly tell the Sage build process
     160system-wide gfortran. You need to explicitly tell the Sage build process
    175161about the Fortran compiler and library location. Do this by typing ::
    176162
    177163    export SAGE_FORTRAN=/exact/path/to/gfortran
     
    295281             ./sage
    296282
    297283   You should see the Sage prompt, which will look something like this
    298    (starting the first time can take a few seconds):
     284   (starting the first time can take a few minutes):
    299285
    300286   ::
    301287
    302288       $ sage
    303289       ----------------------------------------------------------------------
    304        | SAGE Version 3.1, Release Date: 2008-08-16                         |
     290       | Sage Version 4.6, Release Date: 2010-10-30                         |
    305291       | Type notebook() for the GUI, and license() for information.        |
    306292       ----------------------------------------------------------------------
    307293       sage:
     
    359345   ::
    360346
    361347       sage: gap_console()
    362        GAP4, Version: 4.4.6 of 02-Sep-2005, x86_64-unknown-linux-gnu-gcc
     348       GAP4, Version: 4.4.12 of 17-Dec-2008, i386-pc-solaris2.11-gcc
    363349       gap> 2+2;
    364350       4
    365351       [ctrl-d]
     
    378364
    379365       sage: singular_console()
    380366                            SINGULAR                             /  Development
    381         A Computer Algebra System for Polynomial Computations   /   version 3-0-1
     367        A Computer Algebra System for Polynomial Computations   /   version 3-1-1
    382368                                                              0<
    383             by: G.-M. Greuel, G. Pfister, H. Schoenemann        \   October 2005
     369            by: G.-M. Greuel, G. Pfister, H. Schoenemann        \   Feb 2010
    384370       FB Mathematik der Universitaet, D-67653 Kaiserslautern    \
    385371       // ** executing /usr/local/sage/sage-0.8.2/bin/LIB/.singularrc
    386372       [ctrl-d]
     
    451437     Now typing ``sage`` within your terminal emulator should start
    452438     Sage.
    453439
    454 #. Optional: Test the install by typing ``./sage -testall``. This
     440#. Optional, but highly recommended: Test the install by typing ``./sage -testall``. This
    455441   runs most examples in the source code and makes sure that they run
    456442   exactly as claimed. To test all examples, use
    457443   ``./sage -testall -optional -long``; this will run examples that take
     
    460446   likely fail because they assume that a database is installed.
    461447   Alternatively, from within ``$SAGE_ROOT``, you can type
    462448   ``make test`` to run all the standard test code.  This can take
    463    from 30 minutes to an hour or longer.
    464 
    465 #. Optional: The directory ``spkg/build`` contains intermediate code
    466    that is used to build sage. Type ``make clean`` to delete it and a
    467    few other directories (e.g., ``spkg/archive`` and ``devel/old``). This
    468    is safe and will save you about 500 MB of disk space. You may wish to
    469    type this periodically.
     449   from 25 minutes to several hours, depending on your hardware. On
     450   very old hardware building Sage can take several days!
    470451
    471452#. Optional: Install optional Sage packages and databases. Type
    472453   ``sage -optional`` to see a list or visit
     
    503484
    504485- :envvar:`SAGE_PARALLEL_SPKG_BUILD` - set this to "yes" to build
    505486  multiple packages in parallel.  This only has an effect if
    506   :envvar:`MAKE` is also set to run several jobs in parallel.  As of
    507   this writing (June 2010), this is still in the experimental stages,
    508   but turning this on can greatly speed up the build process.
     487  :envvar:`MAKE` is also set to run several jobs in parallel.
    509488
    510 - :envvar:`SAGE64` - Set this to "yes" to build a 64-bit binary.  This
    511   is required if you want a 64-bit binary but the default for your
    512   platform is to build 32-bit binaries.  It adds the compiler flag
     489- :envvar:`SAGE64` - Set this to "yes" to build a 64-bit binary on platforms
     490  which default to 32-bit, even though they can build 64-bit binaries. 
     491  It adds the compiler flag
    513492  -m64 when compiling programs.  The SAGE64 variable is mainly of use
    514493  is on OS X (pre 10.6), Solaris and OpenSolaris, though it will add
    515494  the -m64 on any operating system. If you are running version 10.6 of
     
    560539e.g., an unsupported machine or an unusual compiler:
    561540
    562541- :envvar:`SAGE_PORT` - if you try to build Sage on a platform which
    563   is recognized as being unsupported (e.g., x86 Solaris, AIX, or
     542  is recognized as being unsupported (e.g. AIX, or
    564543  HP-UX), or with a compiler which is unsupported (anything except
    565544  gcc), you will see a message saying something like ::
    566545
     
    581560- :envvar:`SAGE_USE_OLD_GCC` - the Sage build process requires version
    582561  4.0.1 of gcc.  If the most recent version of gcc is 3.4.x and you
    583562  want to try building anyway, then set :envvar:`SAGE_USE_OLD_GCC` to
    584   something nonempty. Expect the build to fail in this case: Sage is
     563  something non-empty. Expect the build to fail in this case: Sage is
    585564  only guaranteed to build using gcc 4.0.1 or later, so if you insist
    586565  on working with gcc 3.4.x, you will have to modify some source code
    587566  to get things to work.
     
    598577  :file:`libf77blas.so`, and it should have a subdirectory
    599578  :file:`include/atlas/` containing header files.
    600579
    601 - :envvar:`SAGE_MATPLOTLIB_GUI` - set this to anything nonempty except
     580- :envvar:`SAGE_MATPLOTLIB_GUI` - set this to anything non-empty except
    602581  "no", and Sage will attempt to build the graphical backend when it
    603582  builds the matplotlib package.
    604583
     
    680659  your machine, set this variable to the appropriate command.
    681660
    682661- :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET` - set this to something
    683   nonempty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before
     662  non-empty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before
    684663  executing system commands.
    685664
    686665- :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used
     
    709688  seconds (30 minutes).
    710689
    711690- :envvar:`SAGE_PICKLE_JAR` - if you want to update the the standard
    712   pickle jar, set this to something nonempty and run the doctest
     691  pickle jar, set this to something non-empty and run the doctest
    713692  suite.  See the documentation for the functions :func:`picklejar`
    714693  and :func:`unpickle_all` in
    715694  :file:`SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
     
    746725System-wide install
    747726~~~~~~~~~~~~~~~~~~~
    748727
    749 This is a compilation of posts to the Sage support list (in
    750 particular those of Luis Finotti).
     728This is a compilation of posts to the Sage support list - in
     729particular those of Luis Finotti.
    751730
     731**Note from David Kirkby.** I would suggest the root account should
     732only be used when absolutely necessary - that would not include
     733building programs like Sage. When logged in as root, one mis-typed command can
     734leave your system totally unbootable and lose all your data. Also, a mistake
     735in the Sage souce code could
     736overwrite 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.
    752737
    753738#. Unpack the current Sage tarball (we shall assume it is
    754    ``sage-2.5.2.tar``) at, e.g., ``/usr/local/`` and compile it as root.
     739   ``sage-4.6.2.tar``) at, e.g., ``/usr/local/`` and compile it as root.
    755740   Assuming you are in a root shell and the tarball is in your current
    756741   directory, type:
    757742
    758743   ::
    759744
    760        cp sage-2.5.2.tar /usr/local
     745       cp sage-4.6.2.tar /usr/local
    761746       cd /usr/local
    762        tar xvf sage-2.5.2.tar
    763        cd sage-2.5.2/
     747       tar xvf sage-4.6.2.tar
     748       cd sage-4.6.2/
    764749       make
    765750
    766751    (Comment: It's better to build in place.  It's a bug if anything goes
    767752    wrong when relocating the entire tarball -- unfortunately there
    768753    is one bug I haven't fixed along these lines, namely the
    769754    PARI install hard-codes the location of the "galois data" files.
    770     (Fixes welcome!))
     755    (Fixes welcome!).)
    771756
    772757#. Make sure to modify the line with the ``.....``"'s at the top of the
    773758   ``sage`` script. In other words, edit ``SAGE_ROOT="....."`` to say
    774    ``SAGE_ROOT="/usr/local/sage-2.5.2"``.
     759   ``SAGE_ROOT="/usr/local/sage-4.6.2"``.
    775760
    776761#. There are some initial files that have to be created during the
    777762   first run of Sage. Try starting up Sage once as root (or, to be
     
    784769
    785770   ::
    786771
    787        cp /usr/local/sage-2.5.2/sage /usr/local/bin/
     772       cp /usr/local/sage-4.6.2/sage /usr/local/bin/
    788773
    789774   You make a copy instead of a symlink, since upgrading with
    790    ``sage -upgrade`` overwrites ``/usr/local/sage-2.5.2/sage``, hence
     775   ``sage -upgrade`` overwrites ``/usr/local/sage-4.6.2/sage``, hence
    791776   deleting the ``ROOT=...`` part of that file.
    792777
    793    Make sure that all files in ``/usr/local/sage-2.5.2`` are readable by
     778   Make sure that all files in ``/usr/local/sage-4.6.2`` are readable by
    794779   all:
    795780
    796781   ::
    797782
    798        chmod a+rX -R /usr/local/sage-2.5.2
     783       chmod a+rX -R /usr/local/sage-4.6.2
    799784
    800785
    801786Special Notes