Skip to content

Commit

Permalink
Trac #27817: remove SAGE_INSTALL_GCC variable
Browse files Browse the repository at this point in the history 
I think with the latest —with-system-* options, it can and should be
removed as superseded.

The branch here updated docs to make SAGE_INSTALL_GCC obsolete and
removed it everywhere, except one place. Alternative means to use
system compilers are explained.

The actual removal from the code will be done in a follow-up ticket.

URL: https://trac.sagemath.org/27817
Reported by: dimpase
Ticket author(s): Dima Pasechnik
Reviewer(s): Matthias Koeppe
  • Loading branch information
Release Manager committed Jun 4, 2019
2 parents b6d3c08 + a9c8ddd commit 575bc56
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 72 deletions.
81 changes: 50 additions & 31 deletions README.md
View file
Expand Up @@ -66,11 +66,13 @@ files installed
has been shown that Sage can be successfully built against other
SSL libraries, with some of its features disabled.


1. Make sure you have the dependencies and 5 GB of free disk space

* __All Linux versions:__ gcc, make, m4, perl, ranlib, and tar (a
* __All Linux versions:__ gcc, make, m4, perl, ranlib, git, and tar (a
matching set of gcc, gfortran and g++ will avoid the compilation
of Sage-specific compilers).
of Sage-specific compilers). It should also be possible to use clang/clang++,
however this is less well-tested.

* __Fedora or RedHat systems:__ the perl-ExtUtils-MakeMaker package.
(install these using your package manager)
Expand All @@ -85,10 +87,22 @@ files installed
When using OS X Mountain Lion or earlier, you need to install the
command line tools from Xcode: run Xcode; then from the File
menu, choose "Preferences", then the "Downloads" tab, and then
"Install" the Command Line Tools.
"Install" the Command Line Tools. You might also have Homebrew or
a similar "Apple's missing package manager" system installed, with
and libraries such gfortran, gmp, etc installed. (However, this
is still experimental as of May 2019).

* __Other platforms:__ See detailed instructions below.

1. It might be desirable, it terms of faster building and better portability,
to install, as system packages, an ever increasing [list of Sage packages](https://trac.sagemath.org/ticket/27330)
which otherwise might have to be built. The following is a list of Sage packages
"replaceable" by system's packages as of Sage release 8.8:
`bzip2`, `curl`, `cmake`, `gcc/clang`, `gf2x`, `gfortran` (usually part of `gcc` installation),
`git`, `gmp`, `libffi`, `patch`, `pcre`, `perl_term_readline_gnu`, `xz/lzma`, `yasm`, `zeromq`, `zlib`.
Details and names of system packages containing these are system-dependent. E.g. on Debian
`bzip2` lives in `libbz2-dev`. More details on this are in Installation manual.

1. Extract the tarball

tar zxvf sage-*.tar.gz
Expand All @@ -113,9 +127,8 @@ Implementation
--------------

Sage has significant components written in the following languages:
C/C++, Python, Cython, Lisp, and Fortran. Lisp (ECL), Python, and Cython
are built as part of Sage and a GNU Fortran (gfortran) binary is
included (OS X only), so you do not need them in order to build Sage.
C/C++, Python, Cython, Lisp, Fortran, and a bit of Perl. Lisp (ECL), Python, and Cython
are built as part of Sage.

Docker Images
-------------
Expand All @@ -133,14 +146,15 @@ More Detailed Instructions to Build from Source

* __Linux:__ See quick instructions above.

* __OS X:__ Make sure you have Xcode version >= 2.4, i.e. `gcc -v` should
output build >= 5363. If you don't, go to https://developer.apple.com/
sign up, and download the free Xcode package. Only OS X >= 10.4 is
supported.
* __OS X:__ (a.k.a __MacOS__) Make sure you have a recent Xcode version.
If you don't, go to https://developer.apple.com/,
sign up, and download the free Xcode package. Usually, Xcode's command line
tools suffice to build Sage, although several times new releases of Xcode broke this.
Only OS X >= 10.4 is supported, and (as of May 2019) we only test Sage on OS X >= 10.6.

* __Solaris and OpenSolaris:__ Building Sage on these platforms is more
tricky than on Linux or OS X. For details on how to build Sage on
these platforms, see [our wiki](https://wiki.sagemath.org/solaris).
these platforms, see [our wiki](https://wiki.sagemath.org/solaris) (outdated as of May 2019).

* __Windows:__ [Download and install VirtualBox](https://www.virtualbox.org/wiki/Downloads),
and then download the [Sage virtual appliance](https://wiki.sagemath.org/SageAppliance).
Expand Down Expand Up @@ -256,17 +270,18 @@ someone there will have some helpful suggestions.
Supported Compilers
-------------------

Sage includes a GCC (_GNU Compiler Collection_) package. In order to
build Sage, you need a C compiler which can build GCC and its
prerequisites. gcc version 4.0.1 or later should probably work. On
Solaris or OpenSolaris, building with the Sun compiler should also work.
Sage includes a GCC (_GNU Compiler Collection_) package. However,
it almost always better to use C, C++ and Fortran compilers
already available one the system. To force using specific compilers,
set environment variables `CC`, `CXX`, and `FC` (for C, C++, and Fortran compilers,
respectively) to the desired values,
and run `./configure`. E.g. `CC=clang CXX=clang++ FC=gfortran ./configure`
will configure Sage to be built with Clang C/C++ compilers and Fortran
compiler gfortran.

The GCC package in Sage is not always installed. It is determined
automatically whether it needs to be installed. You can override this
by setting the environment variable `SAGE_INSTALL_GCC=yes` (to force
installation of GCC) or `SAGE_INSTALL_GCC=no` (to disable installation of
GCC). If you don't want to install GCC, you need to have recent
versions of gcc, g++ and gfortran; moreover, the versions must be equal.
It is determined automatically whether Sage's GCC package, or just its part containing
Fortran compiler `gfortran` needs to be installed. This can be overwritten
by running `./configure` with option `--without-system-gcc`.

There are some known problems with old assemblers, in particular when
building the ECM package. You should ensure that your assembler
Expand All @@ -291,7 +306,8 @@ SAGE_ROOT Root directory (sage-x.y.z in Sage tarball)
│ ├── bin Executables
│ ├── include C/C++ headers
│ ├── lib Shared libraries
│ ├── share Databases, architecture-independent data
│ ├── share Databases, architecture-independent data, docs
│ └── doc Viewable docs of Sage and of some components
│ └── var
│ ├── sage List of installed packages
│ └── tmp Temporary files when building Sage
Expand All @@ -302,12 +318,14 @@ SAGE_ROOT Root directory (sage-x.y.z in Sage tarball)
│ ├── atlas-3.10.1.p7.log
│ …
│ └── zn_poly-0.9.p11.log
├── m4 M4 macros for configure
│ ├── *.m4
├── Makefile Running "make" uses this file
├── README.md This file
├── sage Script to start Sage
├── src All of Sage source (not third-party packages)
│ ├── bin Scripts that Sage uses internally
│ ├── doc Sage documentation
│ ├── doc Sage documentation sources
│ └── sage The Sage library source code
├── upstream Source tarballs of packages
│ ├── atlas-3.10.1.tar.bz2
Expand Down Expand Up @@ -356,8 +374,8 @@ in order to build `build/make/Makefile` since it's a prerequisite for most of
Sage's make targets.

The `configure` script itself, if it is not already built, can be generated by
running the `bootstrap` script. The top-level `Makefile` also takes care of
this automatically.
running the `bootstrap` script (the latter requires _GNU autotools_ being installed).
The top-level `Makefile` also takes care of this automatically.

To summarize, running a command like `make python2` at the top-level of the
source tree goes something like this:
Expand All @@ -377,14 +395,15 @@ source tree goes something like this:
Relocation
----------

You *should* be able to move the `sage-x.y.z/` directory anywhere you
want. If you copy the sage script or make a symbolic link to it, you
It used to be possible to move the `sage-x.y.z/` directory anywhere you
want, however, this is no longer supported.
If you copy the sage script or make a symbolic link to it, you
should modify the script to reflect this (as instructed at the top of
the script). It is best if the path to Sage does not have any spaces in
it.
the script). It is important that the path to Sage does not have any spaces
and non-ASCII characters in it.

For a system-wide installation, as root you can move the `sage-x.y.z/`
directory to a system-wide directory. Afterwards, you need to start up
For a system-wide installation, you have to build Sage as a "normal" user
and then as root you can change permissions. Afterwards, you need to start up
Sage as root at least once prior to using the system-wide Sage as a
normal user. See the [Installation Guide](https://doc.sagemath.org/html/en/installation/source.html#installation-in-a-multiuser-environment)
for further information.
Expand Down
104 changes: 63 additions & 41 deletions src/doc/en/installation/source.rst
View file
Expand Up @@ -92,9 +92,8 @@ computer:
- A **C/C++ compiler**: Since SageMath builds its own GCC if needed,
a wide variety of C/C++ compilers is supported.
Many GCC versions work,
from as old as version 3.4.3 to the most recent release.
from as old as version 4.8 (but we recommend at least 5.1) to the most recent release.
Clang also works.
On Solaris systems, the Sun compiler should also work.
See also `Using alternative compilers`_.
- **make**: GNU make, version 3.80 or later. Version 3.82 or later is recommended.
- **m4**: GNU m4 1.4.2 or later (non-GNU or older versions might also work).
Expand Down Expand Up @@ -133,10 +132,18 @@ development files.
Fortran and compiler suites
###########################

Sage also needs a Fortran compiler.
The only configuration currently supported is matching versions of the
C, C++ and Fortran compilers from the
`GNU Compiler Collection (GCC) <https://gcc.gnu.org/>`_.
Sage installation also needs a Fortran compiler. Officially we support
gfortran from `GNU Compiler Collection (GCC) <https://gcc.gnu.org/>`_.
If C and C++ compilers also come from there (i.e., gcc and g++), their versions
should match.
Alternatively, one may use C and C++ compilers from
`Clang: a C language family frontend for LLVM <https://clang.llvm.org/>`_,
and thus matching versions of
clang, clang++ , along with a recent gfortran. (Flang (or other LLVM-based
Fortran compilers) are not officially supported, however it is possible to
to build Sage using flang, with some extra efforts needed to set various flags;
this is work in progress at the moment (May 2019)).

Therefore, if you plan on using your own GCC compilers, then make sure that
their versions match.

Expand All @@ -148,9 +155,8 @@ or simply a missing Fortran compiler.
In any case, you always need at least a C/C++ compiler to build the GCC
package and its prerequisites before the compilers it provides can be used.

Note that you can always override this behavior through the environment
variable :envvar:`SAGE_INSTALL_GCC`, see :ref:`section_compilers` and
:ref:`section_envvar`.
Note that you can always override this behavior through the configure
options `--without-system-gcc` and `--with-system-gcc`, see :ref:`section_compilers`.

Other notes
^^^^^^^^^^^
Expand Down Expand Up @@ -197,14 +203,17 @@ on the command line. If it gives an error (or returns nothing), then
either ``perl`` is not installed, or it is installed but not in your
`PATH <https://en.wikipedia.org/wiki/PATH_%28variable%29>`_.

Linux prerequisite installation
Linux recommended installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On Linux systems (e.g., Ubuntu, Redhat, etc), ``ar`` and ``ranlib`` are in the
`binutils <https://www.gnu.org/software/binutils/>`_ package.
The other programs are usually located in packages with their respective names.
Assuming you have sufficient privileges, you can install the ``binutils`` and
other necessary components.
other necessary/standard components. The lists provided below are longer than
the minimal prerequisites, which are basically ``binutils``, ``gcc``/``clang``, ``make``,
``tar``, but there is no real need to build compilers and other standard tools
and libraries on a modern Linux system, in order to be able to build Sage.
If you do not have the privileges to do this, ask your system administrator to
do this, or build the components from source code.
The method of installing additional software varies from distribution to
Expand All @@ -213,26 +222,29 @@ distribution, but on a `Debian <https://www.debian.org/>`_ based system (e.g.
you would use
`apt-get <https://en.wikipedia.org/wiki/Advanced_Packaging_Tool>`_::

# debian
$ sudo apt-get install binutils gcc make m4 perl tar git openssl libssl-dev

# redhat
$ sudo yum install binutils gcc make m4 perl tar git \
perl-ExtUtils-MakeMaker openssl openssl-devel
to install all general requirements, or, if you don't want Sage to build its
own GCC::

# debian
$ sudo apt-get install binutils gcc g++ gfortran make m4 perl tar \
git openssl libssl-dev

# redhat
$ sudo yum install binutils gcc gcc-c++ gcc-gfortran make m4 perl \
tar git perl-ExtUtils-MakeMaker openssl openssl-devel
(These examples suppose that you choose to use a systemwide OpenSSL
library. This was tested on Ubuntu 12.04.2.)
# debian (Stretch or newer) / ubuntu
$ sudo apt-get install binutils pixz gcc g++ gfortran make m4 perl tar \
git patch openssl libssl-dev libz-dev bc libbz2-dev liblzma-dev libgmp-dev \
libffi-dev libgf2x-dev libcurl4-openssl-dev curl yasm

# redhat / fedora / centos
$ sudo yum install binutils xz gcc gcc-c++ gcc-gfortran make m4 perl \
tar git patch perl-ExtUtils-MakeMaker openssl openssl-devel zlib-devel \
bzip2 bzip2-devel xz-devel gmp gmp-devel libcurl-devel curl yasm

(These examples suppose that you choose to use a systemwide OpenSSL library.)
In addition, if you don't want Sage to build other packages that might be available from
your OS, cf. the growing list of such packages on :trac:`27330`, install::

# debian / ubuntu
$ sudo apt-get install libntl-dev libmpfr-dev libmpc-dev libflint-dev \
libpcre3-dev libgd-dev \
cmake libterm-readline-gnu-perl ninja-build librw-dev # not for standard Sage spkgs

# redhat / fedora / centos
$ sudo yum install ntl-devel mpfr-devel libmpc-devel \
cmake perl-Term-ReadLine-Gnu ninja-build rw-devel # not for standard Sage spkgs

On other Linux systems, you might use
`rpm <https://en.wikipedia.org/wiki/RPM_Package_Manager>`_,
`yum <https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified>`_,
Expand Down Expand Up @@ -324,16 +336,29 @@ Using alternative compilers
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sage developers tend to use fairly recent versions of GCC.
Nonetheless, the Sage build process should succeed with any reasonable C/C++ compiler.
Nonetheless, the Sage build process on Linux
should succeed with any reasonable C/C++ compiler;
(we do not recommend GCC older than version 5.1).
This is because Sage will build GCC first (if needed) and then use that newly
built GCC to compile Sage.

If you don't want this and want to try building Sage with a different set of
compilers,
you need to set the environment variable :envvar:`SAGE_INSTALL_GCC` to ``no``.
Make sure you have C, C++, and Fortran compilers installed!
you need to pass Sage's ``./configure`` compiler names, via environment
variables ``CC``, ``CXX``, and ``FC``, for C, C++, and Fortran compilers,
respectively, e.g. if you C compiler is ``clang``, your C++ compiler is ``clang++``,
and your Fortran compiler is ``flang`` then you would need to run::

$ CC=clang CXX=clang++ FC=flang ./configure

before running ``make``. It is recommended that you inspect the output of ``./configure``
in order to check that Sage will not try to build GCC. Namely, there should be lines like::

Building all of Sage with Clang is currently not supported, see :trac:`12426`.
gcc-7.2.0 will not be installed (configure check)
...
gfortran-7.2.0 will not be installed (configure check)

indicating that Sage will no attempt to build ``gcc/g++/gfortran``.

If you are interested in working on support for commercial compilers from
`HP <http://docs.hp.com/en/5966-9844/ch01s03.html>`_,
Expand Down Expand Up @@ -385,6 +410,8 @@ Sage notebook.
Notebook additional features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**attention: Sage's notebook is deprecated. Use Jupyter notebook instead**

By default, the Sage notebook uses the
`HTTP <https://en.wikipedia.org/wiki/HTTP>`_
protocol when you type the command ``notebook()``.
Expand Down Expand Up @@ -981,12 +1008,7 @@ Here are some of the more commonly used variables affecting the build process:
So when this variable is empty or unset, Sage uses a default of
``!python2,!python3``.

- :envvar:`SAGE_INSTALL_GCC` - by default, Sage will automatically detect
whether to install the `GNU Compiler Collection (GCC) <https://gcc.gnu.org/>`_
package or not (depending on whether C, C++, and Fortran compilers are present
and the versions of those compilers).
Setting ``SAGE_INSTALL_GCC=yes`` will force Sage to install GCC.
Setting ``SAGE_INSTALL_GCC=no`` will prevent Sage from installing GCC.
- :envvar:`SAGE_INSTALL_GCC` - **Obsolete, do not use, to be removed**

- :envvar:`SAGE_INSTALL_CCACHE` - by default Sage doesn't install ccache,
however by setting ``SAGE_INSTALL_CCACHE=yes`` Sage will install ccache.
Expand Down

0 comments on commit 575bc56

Please sign in to comment.