Ticket #14465: 14465_review.patch

File 14465_review.patch, 10.7 KB (added by jdemeyer, 8 years ago)
  • doc/en/installation/source.rst

    # HG changeset patch
    # User Jeroen Demeyer <jdemeyer@cage.ugent.be>
    # Date 1367139342 -7200
    # Node ID 30a6b0e6b90ed63c3925667241ea98d76733ed39
    # Parent  195538e07751aadd7a0f6769e6ec122f586cb672
    Install Sage from source: documentation review patch
    
    diff --git a/doc/en/installation/source.rst b/doc/en/installation/source.rst
    a b  
    2222you can change absolutely any part of Sage or the programs on which it depends,
    2323and recompile the modified parts.
    2424
     25`Download the Sage source code <http://www.sagemath.org/download-source.html>`_.
     26If you changed your mind, you can also download a
     27`binary distribution <http://www.sagemath.org/download.html>`_
     28for some operating systems.
     29
    2530Supported platforms
    2631-------------------
    2732
     33See http://wiki.sagemath.org/SupportedPlatforms for the full list of platforms
     34on which Sage is supported and the level of support for these systems.
     35
    2836Sage is supported on a number of `Linux <http://en.wikipedia.org/wiki/Linux>`_,
    2937Mac `OS X <http://www.apple.com/macosx/>`_ ,
    3038Sun/Oracle `Solaris <http://www.oracle.com/solaris>`_
    3139and `OpenSolaris <http://en.wikipedia.org/wiki/OpenSolaris>`_ releases,
    32 but Sage is not supported on all versions of Linux, OS X, Solaris or
    33 OpenSolaris.
    34 Depending on the
    35 `operating system <http://en.wikipedia.org/wiki/Operating_system>`_,
    36 Sage works with `x86 <http://en.wikipedia.org/wiki/X86>`_,
    37 `x86_64 <http://en.wikipedia.org/wiki/X86-64>`_,
    38 `PowerPC <http://en.wikipedia.org/wiki/PowerPC>`_,
    39 `ARM <http://en.wikipedia.org/wiki/ARM_architecture>`_,
    40 or `SPARC <http://en.wikipedia.org/wiki/SPARC>`_ processors.
     40but not necessarily all versions of these operating systems.
    4141There is no native version of Sage which installs on
    4242`Microsoft Windows <http://en.wikipedia.org/wiki/Microsoft_Windows>`_,
    4343although Sage can be used on Windows with the aid of a
    4444`virtual machine <http://en.wikipedia.org/wiki/Virtual_machine>`_
    4545or the `Cygwin <http://cygwin.com/>`_ Linux API layer.
    46 Go to http://www.sagemath.org/download-windows.html to download a binary
    47 version of Sage for Windows.
    4846
    49 See http://wiki.sagemath.org/SupportedPlatforms for the full list of platforms
    50 on which Sage is supported and the level of support for these systems.
    51 You will also find details about
     47On the `list of supported platforms <http://wiki.sagemath.org/SupportedPlatforms>`_,
     48you can find details about
    5249`ports <http://en.wikipedia.org/wiki/Computer_port_%28software%29>`_
    5350to other operating systems or processors which may be taking place.
    5451
    55 
    5652Prerequisites
    5753-------------
    5854
     
    8581their versions match.
    8682Alternatively, Sage includes a GCC package, so that C, C++ and Fortran
    8783compilers will be built when the build system detects that it is needed,
    88 e.g., non-GCC compilers, or mismatching versions of the GCC compilers,
    89 versions of the GCC compilers known to miscompile some Sage's dependencies,
     84e.g., non-GCC compilers, or
     85versions of the GCC compilers known to miscompile some components of Sage,
    9086or simply a missing C++ or Fortran compiler.
    9187Whatsoever, you always need at least a C compiler to build the GCC package and
    9288its prerequisites before the compilers it provides can be used.
     
    434430   a few tens of minutes to several hours to build Sage from source.
    435431   On really slow hardware, it can even take a few days to build Sage.
    436432
    437    If the build is successful, you will not see the word ``ERROR`` in the last
    438    3-4 lines of output.
    439433   Each component of Sage has its own build log, saved in
    440434   :file:`SAGE_ROOT/logs/pkgs`.
    441    In particular, if the build of Sage fails, then you can type the following
    442    from the directory where you typed ``make``::
    443 
    444             grep -li "^Error installing" logs/pkgs/*
    445 
    446    Then paste the contents of the log file(s) with errors to the Sage support
     435   If the build of Sage fails, you will see a message mentioning which
     436   package(s) failed to build and the location of the log file for each
     437   failed package.
     438   If this happens, then paste the contents of these log file(s)
     439   to the Sage support
    447440   newsgroup at http://groups.google.com/group/sage-support.
    448441   If the log files are very large (and many are), then don't paste the whole
    449442   file, but make sure to include any error messages.
     
    491484       sage: 2 + 2
    492485       4
    493486
    494    Try something more complicated, which uses the
    495    `FLINT <http://www.flintlib.org/>`_ C library::
     487   Or something slightly more complicated::
    496488
    497        sage: GF(7)(x^7)
     489       sage: factor(2005)
    498490       5 * 401
    499491
    500    Try something simple that uses the `GAP <http://www.gap-system.org/>`_,
    501    `Maxima <http://maxima.sourceforge.net/>`_,
    502    `PARI/GP <http://pari.math.u-bordeaux.fr/>`_ and
    503    `Singular <http://www.singular.uni-kl.de/>`_ interfaces::
    504492
    505        sage: gap('2+2')
    506        4
    507        sage: maxima('2+2')
    508        4
    509        sage: pari('2+2')
    510        4
    511        sage: gp('2+2')
    512        4
    513        sage: singular('2+2')
    514        4
     493#. Optional, but highly recommended:
     494   Test the install by typing ``./sage --testall``.
     495   This runs most examples in the source code and makes sure that they run
     496   exactly as claimed.
     497   To test all examples, use ``./sage --testall --optional=all --long``;
     498   this will run examples that take a long time, and those that depend on
     499   optional packages and software, e.g., Mathematica or Magma.
     500   Some (optional) examples will therefore likely fail.
    515501
    516    (For those familiar with GAP: Sage automatically builds a GAP "workspace"
    517    during installation, so the response time from this GAP command is
    518    relatively fast.
    519    For those familiar with GP/PARI, the ``pari`` command creates an object
    520    directly in the PARI C library, and the ``gp`` command creates an object in
    521    the GP interpreter.)
     502   Alternatively, from within :file:`$SAGE_ROOT`, you can type ``make test``
     503   (respectively ``make ptest``) to run all the standard test code serially
     504   (respectively in parallel).
    522505
    523    Try running GAP, GP, Maxima, or Singular, from Sage:
     506   Testing the Sage library can take from half an hour to several hours,
     507   depending on your hardware.
     508   On slow hardware building and testing Sage can even take several days!
    524509
    525    .. skip
    526 
    527    ::
    528 
    529        sage: gap_console()
    530         ┌───────┐   GAP, Version 4.5.7 of 14-Dec-2012 (free software, GPL)
    531         │  GAP  │   http://www.gap-system.org
    532         └───────┘   Architecture: x86_64-unknown-linux-gnu-gcc-default64
    533         Libs used:  gmp, readline
    534         Loading the library and packages ...
    535         Packages:   GAPDoc 1.5.1
    536         Try '?help' for help. See also  '?copyright' and  '?authors'
    537        gap> 2+2;
    538        4
    539        gap>
    540        [CTRL+D]
    541 
    542    .. skip
    543 
    544    ::
    545 
    546        sage: gp_console()
    547        Reading GPRC: .../sage-5.8/local/etc/gprc.expect ...Done.
    548        
    549                   GP/PARI CALCULATOR Version 2.5.3 (development git-6fd07f9)
    550                  amd64 running linux (x86-64/GMP-5.0.2 kernel) 64-bit version
    551                compiled: Apr 10 2013, gcc-4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5)
    552                         (readline v6.2 enabled, extended help enabled)
    553        
    554                             Copyright (C) 2000-2011 The PARI Group
    555        
    556        PARI/GP is free software, covered by the GNU General Public License, and comes
    557        WITHOUT ANY WARRANTY WHATSOEVER.
    558        
    559        Type ? for help, \q to quit.
    560        Type ?12 for how to get moral (and possibly technical) support.
    561        
    562        parisize = 8000000, primelimit = 500509
    563        ? 2+2
    564        %1 = 4
    565        ?
    566        [CTRL+D]
    567 
    568    .. skip
    569 
    570    ::
    571 
    572        sage: maxima_console()
    573        ;;; Loading #P".../sage-5.8/local/lib/ecl/sb-bsd-sockets.fas"
    574        ;;; Loading #P".../sage-5.8/local/lib/ecl/sockets.fas"
    575        ;;; Loading #P".../sage-5.8/local/lib/ecl/defsystem.fas"
    576        ;;; Loading #P".../sage-5.8/local/lib/ecl/cmp.fas"
    577        Maxima 5.29.1 http://maxima.sourceforge.net
    578        using Lisp ECL 12.12.1
    579        Distributed under the GNU Public License. See the file COPYING.
    580        Dedicated to the memory of William Schelter.
    581        The function bug_report() provides bug reporting information.
    582        (%i1) 2+2;
    583        (%o1)                                  4
    584        (%i2)
    585        [CTRL+D]
    586 
    587    .. skip
    588 
    589    ::
    590 
    591        sage: singular_console()
    592                             SINGULAR                                 /  Development
    593         A Computer Algebra System for Polynomial Computations       /   version 3-1-5
    594                                                                   0<
    595         by: W. Decker, G.-M. Greuel, G. Pfister, H. Schoenemann     \   Jul 2012
    596        FB Mathematik der Universitaet, D-67653 Kaiserslautern        \
    597        > 2+2;
    598        4
    599        >
    600        [CTRL+D]
    601510
    602511#. Optional:
    603512   Check the interfaces to any other software that you have available.
     
    609518   to create a redirection script in :file:`$SAGE_ROOT/local/bin`.
    610519   Sage inserts this directory at the front of your :envvar:`PATH`, so your
    611520   script may need to use an absolute path to avoid calling itself; also, your
    612    script should use ``$*`` to pass along all of its arguments.
     521   script should pass along all of its arguments.
    613522   For example, a ``maple`` script might look like::
    614523
    615524       #!/bin/sh
    616525
    617        /etc/maple10.2/maple.tty $*
     526       exec /etc/maple10.2/maple.tty "$@"
    618527
    619528#. Optional:
    620529   There are different possibilities to make using Sage a little easier:
     
    669578     Having done so, quit your terminal emulator and restart it.
    670579     Now typing ``sage`` within your terminal emulator should start Sage.
    671580
    672 #. Optional, but highly recommended:
    673    Test the install by typing ``./sage --testall``.
    674    This runs most examples in the source code and makes sure that they run
    675    exactly as claimed.
    676    To test all examples, use ``./sage --testall --optional --long``;
    677    this will run examples that take a long time, and those that depend on
    678    optional packages and software, e.g., Mathematica or Magma.
    679    Some (optional) examples will therefore likely fail.
    680 
    681    Alternatively, from within :file:`$SAGE_ROOT`, you can type ``make test``
    682    (respectively ``make ptest``) to run all the standard test code serially
    683    (respectively in parallel).
    684 
    685    Testing the Sage library can take from half an hour to several hours,
    686    depending on your hardware.
    687    On slow hardware building and testing Sage can even take several days!
    688 
    689581#. Optional:
    690582   Install optional Sage packages and databases.
    691583   Type ``sage --optional`` to see a list of them (this requires an Internet
     
    13861278    MAKE="make -j1" ./sage -i zn_poly && make
    13871279
    13881280
    1389 **This page was last updated in April 2013 (Sage 5.8).**
     1281**This page was last updated in April 2013 (Sage 5.9).**