Ticket #9226: README.txt

File README.txt, 10.8 KB (added by drkirkby, 11 years ago)

Suggested revised README.txt

Line 
1Hello,
2
3This README.txt describes build instructions for Sage. If you downloaded
4a binary, you do not need to do anything; just execute
5
6    ./sage
7
8from the command line. If you downloaded the sources, please read
9below on how to build Sage and work around common issues.
10
11
12---------------------------------------------------------------------------
13
14    Sage: Open Source Mathematical Software
15
16       "Creating a Viable Open Source Alternative to
17          Magma, Maple, Mathematica, and Matlab"
18
19    Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
20    William Stein and the Sage Development Team
21
22    Distributed under the terms of the GNU General Public License (GPL)
23
24                  http://www.sagemath.org
25
26    If you have questions, do not hesitate to email the sage-support list
27
28         http://groups.google.com/group/sage-support
29
30    AUTHORS: Over 200 people have contributed code to Sage. Please see
31    one of the websites above for a list. In many cases, documentation
32    for modules and functions list the authors.
33
34---------------------------------------------------------------------------
35
36
37QUICK INSTRUCTIONS TO BUILD FROM SOURCE
38---------------------------------------
39
40The following steps briefly outline the process of building Sage from
41source. See below for more detailed instructions.
42
431. Make sure you have the dependencies and 2.5 GB of free disk space.
44
45   Linux (install these using your package manager):
46
47       GCC, g++, make, m4, perl, ranlib, and tar.
48
49   OS X: XCode.  WARNING: If "gcc -v" outputs 4.0.0, you *must*
50         upgrade XCode (free from Apple), since that version of GCC is
51         very broken.
52
53   Microsoft Windows: Not supported yet.
54
55   NOTE: On some operating systems, it might be necessary to install
56   gas/as, gld/ld, gnm/nm. On most platforms, these are automatically
57   installed when you install the programs listed above. Only OS X
58   >= 10.4.x and certain Linux distributions are 100% supported. See
59   below for a complete list.
60
612. Extract the tarball:
62
63       tar -xvf sage-*.tar
64
653. cd into the Sage directory and type make:
66
67       cd sage-*
68       make
69
70   That's it! Everything is automatic and non-interactive.
71
72
73SELINUX
74--------
75
76On Linux, if you get this error message:
77
78    " restore segment prot after reloc: Permission denied "
79
80the problem is probably related to SELinux. See the following URL for
81further information:
82
83    http://www.ittvis.com/services/techtip.asp?ttid=3092
84
85
86OFFICIALLY SUPPORTED PLATFORMS
87------------------------------
88
89Building of Sage from source is regularly tested on (minimal installs
90of) the following platforms:
91
92  PROCESSOR        OPERATING SYSTEM
93  x86              32-bit Linux -- Debian, Ubuntu, CentOS (=Red Hat),
94                                   Fedora, openSUSE, Mandriva, Arch
95  x86_64           64-bit Linux -- Debian, Ubuntu, CentOS (=Red Hat),
96                                   Fedora, openSUSE, Mandriva, Arch
97  IA-64 Itanium 2  64-bit Linux -- Red Hat, SUSE
98  x86              Apple Mac OS X 10.4.x, 10.5.x, 10.6.x
99  PPC              Apple Mac OS X 10.4.x, 10.5.x, 10.6.x
100  SPARC            Solaris 10 03/05 or later
101                   (Sage currently builds as a 32-bit application on SPARC)
102
103Use Sage on Microsoft Windows via VMware.  Active work to port Sage to
104Cygwin (Windows) is in progress.
105
106
107NOT OFFICIALLY SUPPORTED, BUT NEARLY WORKS
108------------------------------------------
109
110  PROCESSOR  OPERATING SYSTEM
111  x86_64     Solaris 10           (64-bit)
112  x86_64     OpenSolaris          (64-bit)
113  SPARC      Solaris 10           (64-bit)
114
115
116NOT SUPPORTED
117-------------
118
119  * AIX
120  * FreeBSD
121  * Gentoo Linux -- though Sage will probably work fine
122  * HP-UX
123  * Microsoft Windows (via Cygwin) -- active port in progress
124  * Microsoft Windows (via Visual Studio C++)
125  * OpenSolaris
126
127There is some effort to port Sage to FreeBSD and HP-UX. We like all of
128the above operating systems, but just haven't had the time to make
129Sage work well on them. Help wanted! Please send an email to
130
131    http://groups.google.com/group/sage-devel
132
133if you are interested in helping port Sage to any of the above
134platforms.
135
136
137FORTRAN
138-------
139
140To build Sage on any platform except OS X, you must use a system-wide
141gfortran compiler.  Sometimes you need to explicitly tell the Sage
142build process about the Fortran compiler and library location. Do this
143by typing
144
145    export SAGE_FORTRAN=/exact/path/to/gfortran
146    export SAGE_FORTRAN_LIB=/path/to/fortran/libs/libgfortran.so
147
148Note that the SAGE_FORTRAN environment variable is supposed to impact
149*only* the Fortran Sage package, otherwise known as the Fortran
150spkg. Apart from that, this variable is *not* designed to do anything
151at all to other spkg's that use Fortran. For example, the Lapack spkg
152uses Fortran, but the compilation process of Lapack should ignore the
153SAGE_FORTRAN environment variable. The SAGE_FORTRAN environment
154variable does not mean "build any spkg that uses Fortran using this
155Fortran". It means "when installing the Fortran spkg, setup the
156sage_fortran script to run the Fortran specified by the SAGE_FORTRAN
157variable".
158
159
160IMPLEMENTATION
161--------------
162
163Sage has significant components written in the following languages:
164C/C++, Python, Cython, Lisp, and Fortran. Lisp (ECL) and Python are
165built as part of Sage and a GNU Fortran (gfortran) binary is included
166(OS X only), so you do not need them in order to build Sage.
167
168
169MORE DETAILED INSTRUCTIONS TO BUILD FROM SOURCE
170-----------------------------------------------
171
1721. Make sure you have about 2.5 GB of free disk space.
173
1742. Linux: Install GCC, g++, m4, ranlib, and make. The build should
175   work fine on openSUSE, Fedora, Ubuntu, etc. If it doesn't, we want
176   to know!
177
178   OS X: Make sure you have XCode version >= 2.4, i.e. "gcc -v" should
179         output build >= 5363. If you don't, go to
180
181              http://developer.apple.com/
182
183         sign up, and download the free XCode package. Only
184         OS X >= 10.4 is supported.
185
186   Windows: Download and install VirtualBox, install Linux into it, etc.
187
1883. Extract the Sage source tarball and cd into a directory with no
189   spaces in it. If you have a machine with 4 processors, say, type
190   the following to configure the build script to perform a parallel
191   compilation of Sage using 4 jobs:
192
193       export MAKE="make -j4"
194
195   To start the build, type
196
197       make
198
199   If you want to run the test suite for each individual spkg as it is
200   installed, type
201
202       export SAGE_CHECK="yes"
203
204   before starting the Sage build. This will run each test suite and
205   will raise an error if any failures occur.
206
2074. Wait about 1 hour to 14 days, depending on your computer (it took
208   about 2 weeks to build Sage on the Google G1 Android cell phone).
209
2105. Type ./sage to try it out.
211
2126. OPTIONAL: Start Sage and run the command
213
214       install_scripts("/usr/local/bin/")   # change /usr/local/bin/
215
216   Type "install_scripts?" in Sage for more details about what this
217   command does.
218
2197. OPTIONAL: Type "make test" to test all examples in the
220   documentation (over 93,000 lines of input!) -- this takes from 30
221   minutes to several hours. Don't get too disturbed if there are 2 to
222   3 failures, but always feel free to email the section of test.log
223   that contains errors to this mailing list:
224
225       http://groups.google.com/group/sage-support
226
227   If there are numerous failures, there was a serious problem with
228   your build.
229
2308. OPTIONAL: Documentation -- If you want to (try to) build the
231   documentation, run "sage -docbuild help" for instructions. The HTML
232   version of the documentation is built during the compilation
233   process of Sage and resides in the directory
234
235       SAGE_ROOT/devel/sage/doc/output/html
236
237   LaTeX is required to build the PDF version of the documentation.
238
2399. OPTIONAL: GAP -- It is highly recommended that you install the
240   optional GAP database by typing
241
242       ./sage -optional
243
244   then installing (with ./sage -i) the package whose name begins with
245   database_gap. This will download the package from
246   sage.math.washington.edu and install it. While you're at it, you
247   might install other databases of interest to you.
248
24910. OPTIONAL: It is recommended that you have both LaTeX and the
250    ImageMagick tools (e.g. the "convert" command) installed since
251    some plotting functionality benefits from it.
252
253
254SUPPORTED COMPILERS
255-------------------
256
257 * Sage needs a version of GCC that is at least version 4.0.1
258   that is configured with support for at least the C, C++
259   and Fortran languages, although as noted above, a Fortran
260   compiler is not needed on OS X.
261 * The versions of the C compiler (gcc), C++ compiler (g++)
262   and Fortran compiler (gfortran), must all be identical.
263 * Sage has never been built without using the GCC compiler.
264
265
266RELOCATION
267----------
268
269You *should* be able to move the sage-x.y.z directory anywhere you
270want. If you copy the sage script or make a symbolic link to it, you
271should modify the script to reflect this (as instructed at the top of
272the script). It is best if the path to Sage does not have any spaces in
273it.
274
275For a system-wide installation, as root you can move the sage-x.y.z
276directory to a system-wide directory. Afterwards, you need to start
277up Sage as root at least once prior to using the system-wide Sage
278as a normal user. See the Installation Guide for further
279information on performing a system-wide installation.
280
281If you find anything that doesn't work correctly after you moved the
282directory, please email http://groups.google.com/group/sage-support
283
284
285REDISTRIBUTION
286--------------
287
288Your local Sage install is almost exactly the same as any "developer"
289install. You can make changes to documentation, source, etc., and very
290easily package up the complete results for redistribution just like we do.
291
2921. You can make your own source tarball (sage-x.y.z.tar) of Sage by
293   typing "sage -sdist x.y.z", where the version is whatever you want.
294   The result is placed in SAGE_ROOT/dist.
295
2962. You can make a binary distribution with the packages you have
297   installed by typing "sage -bdist x.y.z". The result is placed in
298   the SAGE_ROOT/dist directory.
299
3003. Fat Binaries: To make a binary that will run on the widest range of
301   target machines, set the SAGE_FAT_BINARY environment variable to
302   "yes" before building Sage:
303
304       export SAGE_FAT_BINARY="yes"
305       make
306       ./sage -bdist x.y.z-fat
307
308
309CHANGES TO INCLUDED SOFTWARE
310----------------------------
311
312All software included with Sage is copyright by the respective authors
313and released under an open source license that is "GPL version 3 or
314later"q compatible. See the file COPYING.txt for more details.
315
316Each spkg in SAGE_ROOT/spkg/standard/ is a bzip'd tarball. You can
317extract it with
318
319    tar -jxvf name-*.spkg
320
321Inside the spkg, there is a file SPKG.txt that details all changes
322made to the given package for inclusion with Sage. The inclusion of
323such a file detailing changes is specifically required by some of the
324packages included with Sage (e.g. for GAP).