3 Install from Source Code

More familiarity with computers may be required to build SAGE from source. If you do have all the tools, the process should be completely painless (but it will take your computer a while, though you don't have to watch), and has the major advantage that you have the latest version of SAGE, and you can change absolutely any part of SAGE or the programs on which it depends and recompile.

Note: Solaris? FreeBSD?: Complete compilation of SAGE is currently not supported on Solaris or *BSD. It is possible to compile most of SAGE on Solaris machines and to fill in the extra parts using standard packages; please email wstein@gmail.com or sage-devel if you desparately need to run SAGE on Solaris.

Assumptions: You have a computer with about 850 megabytes disk space free running Linux (32-bit or 64-bit) or OS X with development tools. (Alternatively, you can use Windows and coLinux--but note that the result will just be exactly what the binary install in the previous section gave you, so why bother?) In particular, the following standard command-line development tools must be installed on your box:

   gcc  (with C++ support)
   lexx (or flex)
   make
   m4 
   perl
   ranlib
   tar
   yacc (or bison)  -- relatively recent version.
   latex -- highly recommended, though not strictly required

To check if you have m4 installed, for example, type which m4 at a command line. If it gives an error (or returns nothing), then it is not installed. Note that bison is the free version of yacc, and flex is the free version of lexx. It is very highly recommended that you have latex installed, but not required.

In OS X, make sure you have XCode version at least 2.4, i.e., gcc -v should output build at least 5363. If you don't, go to http://developer.apple.com/ sign up, and download the free Xcode package. Only OS X $\geq 10.4$ is supported. This will give you all of the above commands.

On a Debian-based system (e.g., Ubuntu), ranlib is in the binutils package. On a newly installed Ubuntu system, you can install the above commands as follows:

  sudo apt-get install gcc-4.0-base
  sudo apt-get install make
  sudo apt-get install m4
  sudo apt-get install bison
  sudo apt-get install flex
  sudo apt-get install tar
  sudo apt-get install perl
  sudo apt-get install binutils
  sudo apt-get install gcc
  sudo apt-get install libstdc++6-dev
  sudo apt-get install g++

The LaTeX package and a pdf previewer are optional but they can be installed using

  sudo apt-get install tex-common 
  sudo apt-get install tetex-base 
  sudo apt-get install kpdf

Note: You must have the GNU version of make installed. For example, SAGE won't build on a FreeBSD install that doesn't have the optional GNU version of make installed as well (and named make).

Although some of SAGE is written in Python, you do not need Python pre-installed on your computer, since the SAGE installation includes everything you need. When the installation program is run, it will check that you have each of the above-listed prerequisites, and inform you of any that are missing.

Note:

SAGE is currently being developed using GCC Version 4.0.3, and is likely to compile fine with GCC Version 3.2.x and newer (it is tested somewhat sporadically with old compilers). Work is also being done by David Kirkby (david.kirkby@onetel.net) and Wilson Cheung (wcheung@ucsd.edu) to support Sun's CC compiler. (Nobody has yet worked on support for Intel's proprietary compiler, but if you are interested in this, please email me at wstein@gmail.com.)
One reason perl is required is that both the NTL and PARI configuration scripts are written in perl.

After extracting the SAGE tarball, the subdirectory source contains the source distributions for everything on which SAGE depends. We emphasize that all of this software is included with SAGE , so you do not have to worry about trying to download and install any one of these packages (such as GAP, for example) yourself.

Note: On tests using various Linux computer systems the known problems are:

SAGE doesn't compile under GCC 4.1.0 as of 2006-04-13.
SAGE does not compile under GCC 2.x, and no support for this is planned.
Moving the SAGE build after compiling breaks the PARI Galois fields database, which appears to be hardcoded into the PARI binary. (Somebody help fix this!)

3.1 Steps to Install from Source

Installation from source is (potentially) very easy, because the distribution contains (essentially) everything on which SAGE depends.

Note: Make sure there are no spaces in the directory name under which you build SAGE. Running SAGE from a directory with spaces in it is supported but discouraged. Building is not possible, since several of the components of SAGE do not build if there are spaces in the path.

Download the file sage-*.tar from
```
  http://modular.math.washington.edu/SAGE/dist/src/index.html
```
or from the scipy mirror,
```
  http://sage.scipy.org/sage/dist/src/
```
This tarfile contains the source code for SAGE and the source for all programs on which SAGE depends. Download it into a subdirectory of your home directory into which you want to install SAGE. Note that this file is not compressed; it's just a plain tarball (which happens to be full of compressed files).
Extract:
```
      tar xvf sage-x.y.z.tar
```
This creates a directory sage-x.y.z.
Change into that directory
```
      cd sage-x.y.z
```
This is SAGE's home directory.
Optional (but highly recommended): Read the README.txt file there.
Type
```
      make
```
This compiles SAGE and all dependencies. Note that you do not need to be logged in as root, since no files are changed outside of the sage-x.y.z directory.¹ This command does the usual steps for each of the packages, but puts all the results in the local build tree. This can take close to an hour on some machines. If successful, you will not see the word ERROR in the last 3-4 lines of output.

Note: The directory where you built SAGE is NOT hardcoded into any part of SAGE. You should be able to safely move or rename that directory. (It's a bug if this is not the case - unfortunately there is one bug which hasn't yet been fixed along these lines, namely the PARI install hard-codes the location of the "galois data" files. Fixes welcome!)

After you build SAGE, you may optionally copy or move the entire build tree to /usr/local. You might also copy the sage-*/sage script to /usr/local/bin/ and edit ROOT="....." at the top of that file.
To start SAGE change into the SAGE home directory and type:
```
      ./sage
```
You should see the SAGE prompt, which will look something like this (starting SAGE the first time can take a few seconds):
```
$ sage
-------------------------------------------------------------------
|  SAGE Version 0.10.1, Build Date: 2005-12-20-2026               |
|  Distributed under the terms of the GNU General Public License  |
|  For help type <object>?, <object>??, %magic, or help           |
-------------------------------------------------------------------
sage:
```
Just starting SAGE successfully tests that many of the components built correctly. If the above is not displayed (e.g., if you get a massive traceback), please report the problem, e.g., to sage-forum@lists.sourceforge.net. Please include in your email the file install.log. It would also be helpful to include the type of operating system you have and the version number (and date) of the copy of SAGE you are using. (There are no formal requirements for bug reports - just send them; we appreciate everything.)
After SAGE starts, try a command:
```
sage: 2 + 2
4
```
Try something more complicated, which uses the PARI C library:
```
sage: factor(2005)
5 * 401
```
Try something simple that uses the Gap, Singular, Maxima and GP/PARI interfaces:
```
sage: gap('2+2')
4
sage: gp('2+2')
4
sage: maxima('2+2')
4
sage: singular('2+2')
4
sage: pari('2+2')
4
```
(For those familiar with GAP: SAGE automatically builds a GAP ``workspace'' during installation, so the response time from this GAP command is relatively fast. For those familiar with GP/PARI, the gp command creates an object in the GP interpreter, and the pari command creates an object directly in the PARI C-library.)
Try running Gap, Singular or GP from SAGE:
```
sage: gap_console()
GAP4, Version: 4.4.6 of 02-Sep-2005, x86_64-unknown-linux-gnu-gcc
gap> 2+2;
4
[ctrl-d]
```
```
sage: gp_console()
...
[ctrl-d]
```
```
sage: singular_console()
                     SINGULAR                             /  Development
 A Computer Algebra System for Polynomial Computations   /   version 3-0-1
                                                       0<
     by: G.-M. Greuel, G. Pfister, H. Schoenemann        \   October 2005
FB Mathematik der Universitaet, D-67653 Kaiserslautern    \
// ** executing /usr/local/sage/sage-0.8.2/bin/LIB/.singularrc
[ctrl-d]
> Auf Wiedersehen.
sage:
```
Optional: Check the interfaces to any non-included software that you have available. Note that each interface calls its corresponding program by a particular name: Mathematica is invoked by calling math, Maple by calling maple, et cetera. The easiest way to change this name or perform other customizations is to create a redirection script in $SAGE_ROOT/local/bin. SAGE inserts this directory at the front of your PATH, so your script may need to use an absolute path to avoid calling itself; also, your script should use $* to pass along all of its arguments. For example, a maple script might look like:
```
#!/bin/sh

/etc/maple10.2/maple.tty $*
```
Optional: Different possibilities to make using SAGE a little easier:
- Copy <SAGE_ROOT>/sage to a location in your PATH. If you do this, make sure and edit the line with the ....'s at the top of the sage script.
- For KDE users, create a bash script sage containing the lines
```
#!/bin/bash
konsole -T "sage" -e <SAGE_ROOT>/sage
```
  which you make executable (chmod a+x sage) and put in your path somewhere. (Note that you have to change <SAGE_ROOT> above!) You can also make a KDE desktop icon with this as the command (under the Application tab of the Properties of the icon, which you get my right clicking the mouse on the icon).
- for bash shell users, type echo $PATH and cp sage <your-path-dir> into one of these directories, or else add this bin directory to your PATH variable, e.g., if you use the bash shell, add the line
```
PATH="<sage-home-dir>/bin":$PATH
export PATH
```
  in your .bashrc file (if it exists; if not, make one). After doing this and logging out and in again, typing sage at a shell prompt should start SAGE.
Optional: Test the install by typing ./sage -testall. This runs most examples in the source code and makes sure that they run exactly as claimed. To test all examples, use ./sage -testall -optional -long; this will run examples that take a long time, and those that depend on optional packages and software, e.g., Mathematica or Magma. Some (optional) examples will likely fail because they assume that a database is installed.
Optional: The directory spkg/build contains intermediate code that is used to build sage. Type make clean to delete it and a few other directories (e.g., spkg/archive and devel/old). This is safe and will save you about 500MB disk space. You may wish to type this periodically.
Optional: Install optional SAGE packages and databases. Type sage -optional to see a list or visit http://modular.math.washington.edu/sage/packages/optional/, and sage -i <package name> to automatically download and install a given package.
Optional: Run the install_scripts command from in SAGE to create gp, singular, gap, etc., scripts in your PATH. Type install_scripts? in SAGE for details.

Have fun! Discover some amazing conjectures!

3.2 Installation in a Multiuser Environment

This section addresses the question of how a system administrator can install a single copy of SAGE in a multi-user computer network.

3.2.1 System-wide install

This is a compilation of posts to the SAGE support list (in particular those of Luis Finotti).

Unpack the current SAGE tarball (we shall assume it is sage-1.2.0.tar) at, e.g., /usr/local/ and compile it as root. Assuming you are in a root shell and the tarball is in your current directory, type:
```
cp sage-1.2.0.tar /usr/local
cd /usr/local
tar xvf sage-1.2.0.tar 
cd sage-1.2.0/
make
```
Comment: It's better to build in place. It's a bug if anything goes wrong when relocating the entire tarball - unfortunately there is one bug I haven't fixed along these lines, namely the PARI install hard-codes the location of the "galois data" files. (Fixes welcome!)

Make sure to modify the line with the ``....."'s at the top of the sage script. In other words, edit SAGE_ROOT="....." to say SAGE_ROOT="/usr/local/sage-1.2.0".

There are some initial files that have to be created during the first run of SAGE. Try starting up SAGE once as root (or, to be more thorough, try make test as root to run all the standard test code). You can stop the tests by pressing ctrl-z followed by typing kill %1 (assuming you had no other jobs in the background of that shell).

Make a copy of the sage script in /usr/local/bin:
```
cp /usr/local/sage-1.2.0/sage /usr/local/bin/
```
You make a copy instead of a symlink, since upgrading SAGE (with sage -upgrade) overwrites /usr/local/sage-1.2.0/sage, hence deleting the ROOT=... part of that file.
Make sure that all files in /usr/local/sage-1.2.0 are readable by all:
```
chmod a+r -R /usr/local/sage-1.2.0
```

3.3 Special Notes

(Found by Dorian Raymer) SAGE will not build if you have only bison++. You should uninstall bison++ and install bison.
(Found by Peter Jipsen) If you get an error like
```
ImportError: /home/jipsen/Desktop/sage-1.3.3.1/local/lib/libpari-gmp.so.2: 
     cannot restore segment prot after reloc: 
Permission denied
```
then your SELinux configuration is preventing SAGE from launching. To rectify this issue, you can either change the default security context for SAGE (??) or disable SELinux altogether by setting the line SELINUX=disabled in your /etc/sysconfig/selinux file.

Footnotes

... directory.¹: There is one exception--the .ipythonrc directory is created in your HOME directory if it doesn't exist.

See About this document... for information on suggesting changes.