Ticket #8263: trac_8263-installation.patch

File trac_8263-installation.patch, 15.6 KB (added by John Palmieri, 13 years ago)
  • doc/en/installation/source.rst

    # HG changeset patch
    # User J. H. Palmieri <palmieri@math.washington.edu>
    # Date 1277692312 25200
    # Node ID 3cbbf0940671698509a0cf670113dad302629aae
    # Parent  b19c0fe552a6f20b4baa37182b333edfedee49f8
    #8263: patch for installation guide
    
    diff -r b19c0fe552a6 -r 3cbbf0940671 doc/en/installation/source.rst
    a b are: 
    166166
    167167Fortran
    168168-------
    169 
     169 
    170170On Linux and Solaris systems, a working Fortran compiler is required
    171171for building Sage from source. If you are using Fortran on a platform
    172172for which Sage does not include g95 binaries, you must use a
    about the Fortran compiler and library l 
    177177    export SAGE_FORTRAN=/exact/path/to/gfortran
    178178    export SAGE_FORTRAN_LIB=/path/to/fortran/libs/libgfortran.so
    179179
    180 Note that the ``SAGE_FORTRAN`` environment variable is supposed to
     180Note that the :envvar:`SAGE_FORTRAN` environment variable is supposed to
    181181impact *only* the Fortran Sage package, otherwise known as the Fortran
    182182spkg. Apart from that, this variable is *not* designed to do anything
    183183at all to other spkg's that use Fortran. For example, the Lapack spkg
    184184uses Fortran, but the compilation process of Lapack should ignore the
    185 ``SAGE_FORTRAN`` environment variable. The ``SAGE_FORTRAN``
     185:envvar:`SAGE_FORTRAN` environment variable. The :envvar:`SAGE_FORTRAN`
    186186environment variable does not mean "build any spkg that uses Fortran
    187187using this Fortran". It means "when installing the Fortran spkg, setup
    188188the ``sage_fortran`` script to run the Fortran compiler specified by
    189 the ``SAGE_FORTRAN`` variable".
     189the :envvar:`SAGE_FORTRAN` variable".
    190190
    191191On Mac OS X, you are not required to have a Fortran compiler on your
    192192system. The Sage source distribution is shipped with a Fortran
    193193compiler for Mac OS X. This Fortran compiler is used, unless you
    194 specify another Fortran compiler via the variable ``SAGE_FORTRAN``.
     194specify another Fortran compiler via the variable :envvar:`SAGE_FORTRAN`.
    195195
    196196On platforms such as AIX, HP-UX, and Solaris, where both 32- and
    19719764-bit builds are supported, the library path variable
    198 ``SAGE_FORTRAN_LIB`` must point to the 32-bit library if you are
    199 building Sage in 32-bit. Also, ``SAGE_FORTRAN_LIB`` must point to a
     198:envvar:`SAGE_FORTRAN_LIB` must point to the 32-bit library if you are
     199building Sage in 32-bit. Also, :envvar:`SAGE_FORTRAN_LIB` must point to a
    20020064-bit library if you are building Sage in 64-bit. For example, on
    201 Solaris both of the variables ``SAGE_FORTRAN`` and
    202 ``SAGE_FORTRAN_LIB`` could be set as follows (you need to check
    203 this)::
     201Solaris both of the variables :envvar:`SAGE_FORTRAN` and
     202:envvar:`SAGE_FORTRAN_LIB` could be set as follows::
    204203
    205204    # SPARC and x86
    206205    SAGE_FORTRAN=/path/to/gcc/install/directory/bin/gfortran
    components do not build if there are spa 
    269268
    270269   This compiles Sage and all dependencies. Note that you do not need
    271270   to be logged in as root, since no files are changed outside of the
    272    ``sage-x.y.z`` directory. [1]_ This command does the usual steps for
     271   ``sage-x.y.z`` directory (with one exception -- the ``.ipythonrc`` directory is created in
     272   your ``HOME`` directory if it doesn't exist).  This command does the usual steps for
    273273   each of the packages, but puts all the results in the local build
    274274   tree. This can take close to an hour on some machines. Depending on the
    275275   architecture of your system (e.g., Celeron, Pentium Mobile, Pentium 4,
    components do not build if there are spa 
    277277   build is successful, you will not see the word ERROR in the last 3-4 lines
    278278   of output.
    279279
    280 .. [1]
    281    There is one exception--the ``.ipythonrc`` directory is created in
    282    your ``HOME`` directory if it doesn't exist.
    283 
    284 
    285280       The directory where you built Sage is NOT hardcoded. You should
    286281       be able to safely move or rename that directory. (It's a bug if
    287282       this is not the case --- unfortunately there is one
    components do not build if there are spa 
    323318   formal requirements for bug reports - just send them; we appreciate
    324319   everything.)
    325320
    326    After starts, try a command:
     321   After Sage starts, try a command:
    327322
    328323   ::
    329324
    components do not build if there are spa 
    394389       > Auf Wiedersehen.
    395390       sage:
    396391
    397 #. Optional: Check the interfaces to any non-included software that
     392#. Optional: Check the interfaces to any other software that
    398393   you have available. Note that each interface calls its
    399394   corresponding program by a particular name: Mathematica is invoked
    400395   by calling ``math``, Maple by calling ``maple``, et cetera. The
    components do not build if there are spa 
    488483
    489484Have fun! Discover some amazing conjectures!
    490485
     486Environment variables
     487---------------------
     488
     489Sage uses several environment variables to control its build process.
     490Most users won't need to use any of these: the build process just
     491works on many platforms.  Building Sage involves building about 100
     492packages, each of which has its own compilation instructions.
     493
     494Here are some of the more commonly used variables affecting the build
     495process:
     496
     497- :envvar:`MAKE` - one common setting for this variable when building
     498  Sage is ``export MAKE='make -jNUM'`` to tell the "make" program to
     499  run NUM jobs in parallel when building individual packages.  (Not
     500  all packages support this, but the ones for which this could be
     501  problematic should automatically disable it.)
     502
     503- :envvar:`SAGE_CHECK` - if this is set to "yes", then during the
     504  build process, run the test suite for each package which has one.
     505
     506- :envvar:`SAGE_PARALLEL_SPKG_BUILD` - set this to "yes" to build
     507  multiple packages in parallel.  This only has an effect if
     508  :envvar:`MAKE` is also set to run several jobs in parallel.  As of
     509  this writing (June 2010), this is still in the experimental stages,
     510  but turning this on can greatly speed up the build process.
     511
     512- :envvar:`SAGE64` - Set this to "yes" to build a 64-bit binary.  This
     513  is required if you want a 64-bit binary but the default for your
     514  platform is to build 32-bit binaries.  It adds the compiler flag
     515  -m64 when compiling programs.  The SAGE64 variable is mainly of use
     516  is on OS X (pre 10.6), Solaris and OpenSolaris, though it will add
     517  the -m64 on any operating system. If you are running version 10.6 of
     518  OS X on a 64-bit machine, then Sage will automatically build a
     519  64-bit binary, so this variable does not need setting.
     520
     521- :envvar:`SAGE_FORTRAN` - see above, the "Fortran" section.
     522
     523- :envvar:`SAGE_FORTRAN_LIB` - see above, the "Fortran" section.
     524
     525- :envvar:`SAGE_DEBUG` - about half a dozen Sage packages use this
     526  variable.  If it is unset (the default) or set to "yes", then
     527  debugging is turned on.  If it is set to anything else, then
     528  debugging is turned off.
     529
     530- :envvar:`SAGE_FAT_BINARY` - to prepare a binary distribution that
     531  will run on the widest range of target machines, set this variable
     532  to "yes" before building Sage::
     533
     534      export SAGE_FAT_BINARY="yes"
     535      make
     536      ./sage -bdist x.y.z-fat
     537
     538Variables to set if you're trying to build Sage with an unusual setup,
     539e.g., an unsupported machine or an unusual compiler:
     540
     541- :envvar:`SAGE_PORT` - if you try to build Sage on a platform which
     542  is recognized as being unsupported (e.g., x86 Solaris, AIX, or
     543  HP-UX), or with a compiler which is unsupported (anything except
     544  gcc), you will see a message saying something like ::
     545
     546        You are attempting to build Sage on IBM's AIX operating system,
     547        which is not a supported platform for Sage yet. Things may or
     548        may not work. If you would like to help port Sage to AIX,
     549        please join the sage-devel discussion list - see
     550        http://groups.google.com/group/sage-devel
     551        The Sage community would also appreciate any patches you submit.
     552       
     553        To get past this message, export the variable SAGE_PORT to
     554        something non-empty.
     555
     556  If this is the situation, follow the directions: set
     557  :envvar:`SAGE_PORT` to something non-empty (and expect to run into
     558  problems).
     559
     560- :envvar:`SAGE_USE_OLD_GCC` - the Sage build process requires version
     561  4.0.1 of gcc.  If the most recent version of gcc is 3.4.x and you
     562  want to try building anyway, then set :envvar:`SAGE_USE_OLD_GCC` to
     563  something nonempty. Expect the build to fail in this case: Sage is
     564  only guaranteed to build using gcc 4.0.1 or later, so if you insist
     565  on working with gcc 3.4.x, you will have to modify some source code
     566  to get things to work.
     567
     568- :envvar:`CFLAG64` - default value "-m64".  If Sage detects that it
     569  should build a 64-bit binary, then it uses this flag when compiling
     570  C code.  Modify it if necessary for your system and C compiler.
     571  This should not be necessary on most systems -- this flag will
     572  typically be set automatically, based on the setting of
     573  :envvar:`SAGE64`, for example.
     574
     575Environment variables dealing with specific Sage packages:
     576
     577- :envvar:`SAGE_ATLAS_LIB` - if you have an installation of ATLAS on
     578  your system and you want Sage to use it instead of building and
     579  installing its own version of ATLAS, set this variable to be the
     580  parent directory of your ATLAS installation: it should have a
     581  subdirectory :file:`lib` containing the files :file:`libatlas.so`,
     582  :file:`liblapack.so`, :file:`libcblas.so`, and
     583  :file:`libf77blas.so`, and it should have a subdirectory
     584  :file:`include/atlas/` containing header files.
     585
     586- :envvar:`SAGE_MATPLOTLIB_GUI` - set this to anything nonempty except
     587  "no", and Sage will attempt to build the graphical backend when it
     588  builds the matplotlib package.
     589
     590- :envvar:`INCLUDE_MPFR_PATCH` - This is used to add a patch to MPFR
     591  to bypass a bug in the memset function affecting sun4v machines with
     592  versions of Solaris earlier than Solaris 10 update 8
     593  (10/09). Earlier versions of Solaris 10 can be patched by applying
     594  Sun patch 142542-01.  Recognized values are:
     595
     596  - ``INCLUDE_MPFR_PATCH=0`` - never include the patch - useful if you
     597    know all sun4v machines Sage will be used are running Solaris
     598    10 update 8 or later, or have been patched with Sun patch
     599    142542-01.
     600
     601  - ``INCLUDE_MPFR_PATCH=1`` - always include the patch, so the binary
     602    will work on a sun4v machine, even if created on an older sun4u
     603    machine.
     604
     605  If this variable is unset, include the patch on sun4v machines only.
     606
     607- :envvar:`SAGE_BINARY_BUILD` - used by the pil package.  If set to
     608  "yes", then force Sage to use the versions of libjpeg, libtiff and
     609  libpng from :file:`$SAGE_ROOT/local/lib`.  Otherwise, allow the use
     610  of the system's versions of these libraries.
     611
     612- :envvar:`SAGE_PIL_NOTK` - used by the pil package.  If set to "yes",
     613  then disable building TK.  If this is not set, then this should be
     614  dealt with automatically: Sage tries to build the pil package with
     615  TK support enabled, but if it runs into problems, it tries building
     616  again with TK disabled.  So only use this variable to force TK to be
     617  disabled.  (Building the pil package is pretty fast -- less than a
     618  minute on many systems -- so allowing it to build twice is not a
     619  serious issue.)
     620
     621Some standard environment variables which you should probably **not**
     622set:
     623
     624- :envvar:`CC` - while some programs allow you to use this to specify
     625  your C compiler, the Sage packages do **not** all recognize this.
     626  In fact, setting this variable for building Sage is likely to cause
     627  the build process to fail.
     628
     629- :envvar:`CXX` - similarly, this will set the C++ complier for some
     630  Sage packages, and similarly, using it is likely quite risky.
     631
     632- :envvar:`CFLAGS`, :envvar:`CXXFLAGS` - the flags for the C compiler
     633  and the C++ compiler, respectively.  The same comments apply to
     634  these: setting them may cause problems, because they are not
     635  universally respected among the Sage packages.
     636
     637Sage uses the following environment variables when it runs:
     638
     639- :envvar:`DOT_SAGE` - this is the directory, to which the user has
     640  read and write access, where Sage stores a number of files.  The
     641  default location is ``~/.sage/``, but you can change that by setting
     642  this variable.
     643
     644- :envvar:`SAGE_STARTUP_FILE` - a file including commands to be
     645  executed every time Sage starts.  The default value is
     646  ``$DOT_SAGE/init.sage``.
     647
     648- :envvar:`SAGE_SERVER` - if you want to install a Sage package using
     649  ``sage -i PKG_NAME``, Sage downloads the file from the web, using
     650  the address ``http://www.sagemath.org/`` by default, or the address
     651  given by :envvar:`SAGE_SERVER` if it is set.  If you wish to set up
     652  your own server, then note that Sage will search the directories
     653  ``SAGE_SERVER/packages/standard/``,
     654  ``SAGE_SERVER/packages/optional/``,
     655  ``SAGE_SERVER/packages/experimental/``, and
     656  ``SAGE_SERVER/packages/archive/`` for packages.  See the script
     657  :file:`$SAGE_ROOT/local/bin/sage-download_package` for the
     658  implementation.
     659
     660- :envvar:`SAGE_PATH` - a colon-separated list of directories which
     661  Sage searches when trying to locate Python libraries.
     662
     663- :envvar:`SAGE_BROWSER` - on most platforms, Sage will detect the
     664  command to run a web browser, but if this doesn't seem to work on
     665  your machine, set this variable to the appropriate command.
     666
     667- :envvar:`SAGE_ORIG_LD_LIBRARY_PATH_SET` - set this to something
     668  nonempty to force Sage to set the :envvar:`LD_LIBRARY_PATH` before
     669  executing system commands.
     670
     671- :envvar:`SAGE_ORIG_DYLD_LIBRARY_PATH_SET` - similar, but only used
     672  on Mac OS X to set the :envvar:`DYLD_LIBRARY_PATH`.
     673
     674- :envvar:`SAGE_CBLAS` - used in the file
     675  :file:`SAGE_ROOT/devel/sage/sage/misc/cython.py`.  Set this to the
     676  base name of the BLAS library file on your system if you want to
     677  override the default setting.  That is, if the relevant file is
     678  called :file:`libcblas_new.so` or :file:`libcblas_new.dylib`, then
     679  set this to "cblas_new".
     680
     681Variables dealing with doctesting:
     682
     683- :envvar:`SAGE_TESTDIR` - a temporary directory used during Sage's
     684  doctesting.  The default is to use the directory ``$DOT_SAGE/tmp``,
     685  but you can override that by setting this variable.
     686
     687- :envvar:`SAGE_TIMEOUT` - used for Sage's doctesting: the number of
     688  seconds to allow a doctest before timing it out.  If this isn't set,
     689  the default is 360 seconds (6 minutes).
     690 
     691- :envvar:`SAGE_TIMEOUT_LONG` - used for Sage's doctesting: the number
     692  of seconds to allow a doctest before timing it out, if tests are run
     693  using ``sage -t --long``.  If this isn't set, the default is 1800
     694  seconds (30 minutes).
     695
     696- :envvar:`SAGE_PICKLE_JAR` - if you want to update the the standard
     697  pickle jar, set this to something nonempty and run the doctest
     698  suite.  See the documentation for the functions :func:`picklejar`
     699  and :func:`unpickle_all` in
     700  :file:`SAGE_ROOT/devel/sage/sage/structure/sage_object.pyx`, online
     701  `here (picklejar)
     702  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.picklejar>`_
     703  and `here (unpickle_all)
     704  <http://sagemath.org/doc/reference/sage/structure/sage_object.html#sage.structure.sage_object.unpickle_all>`_.
     705
     706..
     707  THIS INDENTED BLOCK IS A COMMENT.  FIX IT ONCE WE UNDERSTAND
     708  THESE VARIABLES.
     709
     710  Variables dealing with valgrind and friends:
     711
     712  - :envvar:`SAGE_TIMEOUT_VALGRIND` - used for Sage's doctesting: the
     713    number of seconds to allow a doctest before timing it out, if tests
     714    are run using ``??``.  If this isn't set, the default is 1024*1024
     715    seconds.
     716
     717  - :envvar:`SAGE_VALGRIND` - ?
     718
     719  - :envvar:`SAGE_MEMCHECK_FLAGS`, :envvar:`SAGE_MASSIF_FLAGS`,
     720    :envvar:`SAGE_CACHEGRIND_FLAGS`, :envvar:`SAGE_OMEGA_FLAGS` - flags
     721    used when using valgrind and one of the tools "memcheck", "massif",
     722    "cachegrind", or "omega"
     723
    491724Installation in a Multiuser Environment
    492725---------------------------------------
    493726