1.0.4.101: new STRING-OUTPUT-STREAM implementation
[sbcl/simd.git] / INSTALL
blob050e67f71b0f59a43eb66563f245366b4e0be187
1 INSTALLING SBCL
3   CONTENTS
5     1. BINARY DISTRIBUTION
6     1.1. Quick start
7     1.2. Finding ancillary files
8     1.3. Anatomy of SBCL
10     2. SOURCE DISTRIBUTION
11     2.1. Quick start
12     2.2. Customizing SBCL
13     2.3. Troubleshooting
14     2.4. Tracking SBCL sources
15     2.5. Supported platforms
18 1. BINARY DISTRIBUTION
20 1.1. Quick start:
22   The following command installs SBCL and related documentation under
23   the "/usr/local" directory:
24   
25     # INSTALL_ROOT=/usr/local sh install.sh
27   You can also install SBCL as a user, under your home directory:
29     $ INSTALL_ROOT=/home/me sh install.sh
31   In other words, "install.sh" installs SBCL under the directory named
32   by the environment variable "INSTALL_ROOT".
34   If you install SBCL from binary distribution in other location than
35   "/usr/local", see section 1.2, "Finding ancillary files".
37 1.2. Finding ancillary files
39   The SBCL runtime needs to be able to find the ancillary files
40   associated with it: the "sbcl.core" file, and the contrib modules.
42   Finding core can happen in three ways:
44     1. By default, in a location configured when the system was built.
45        For binary distributions this is in "/usr/local/lib/sbcl".
47     2. By environment variable, in the directory named by the
48        environment variable "SBCL_HOME". Example:
50          $ export SBCL_HOME=/foo/bar/lib/sbcl
51          $ sbcl
53        If your "INSTALL_ROOT" was FOO, then your "SBCL_HOME" is
54        "FOO/lib/sbcl".
56     3. By command line option:
58          $ sbcl --core /foo/bar/sbcl.core
60   The usual, recommended approach is method #1. Method #2 is useful if
61   you're installing SBCL on a system in a non-standard location
62   (e.g. in your user account), instead of installing SBCL on an entire
63   system.  Method #3 is mostly useful for testing or other special
64   cases.
66   Contributed modules are primarily looked for in "SBCL_HOME", or the
67   directory the core resides in if "SBCL_HOME" is not set.
68   ASDF:*CENTRAL-REGISTRY* serves as an additional fallback for
69   ASDF-based modules.
71 1.3. Anatomy of SBCL
73   The two files that SBCL needs to run, at minimum, are:
75     src/runtime/sbcl
76     output/sbcl.core
78   In addition, there are a number of modules that extend the basic
79   sbcl functionality, in
81     contrib/
83   The "src/runtime/sbcl" is a standard executable, built by compiling
84   and linking an ordinary C program. It provides the runtime
85   environment for the running Lisp image, but it doesn't know much
86   about high-level Lisp stuff (like symbols and printing and objects)
87   so it's pretty useless by itself. The "output/sbcl.core" is a dump
88   file written in a special SBCL format which only sbcl understands,
89   and it contains all the high-level Lisp stuff.
91   The standard installation procedure, outlined in section 1.1 "Quick
92   start", is to run the "install.sh", which copies all the files to
93   right places, including documentation and contrib-modules that have
94   passed their tests. If you need to install by hand, see "install.sh"
95   for details.
97   Documentation consists of a man-page, the SBCL Manual (in info, pdf
98   and html formats), and a few additional text files.
100 2. SOURCE DISTRIBUTION
102 2.1. Quick start
104   To build SBCL you need a working toolchain and a Common Lisp system
105   (see section 2.5 "Supported platforms"). You also need approximately
106   128 Mb of free RAM+swap.
108   To build SBCL using an already installed SBCL:
110     $ sh make.sh
112   If you don't already have an SBCL binary installed as "sbcl" on your
113   system, you'll need to tell make.sh what Lisp to use as the
114   cross-compilation host. For example, to use CMUCL (assuming has
115   been installed under its default name "lisp") as the
116   cross-compilation host:
118     $ sh make.sh 'lisp -batch -noinit'
120   The build may take a long time, especially on older hardware. A
121   successful build ends with a message beginning: "The build seems to
122   have finished successfully...".
124   To run the regression tests:
126     $ cd tests && sh run-tests.sh
128   To build documentation:
130     $ cd doc/manual && make
132   This builds the Info, HTML and PDF documentation from the Texinfo
133   sources. The manual includes documentation string from the build
134   SBCL, but if SBCL itself has not been yet built, but one if found
135   installed documentation strings from the installed version are used.
137   Now you should have the same src/runtime/sbcl and output/sbcl.core
138   files that come with the binary distribution, and you can install
139   them as described in the section 1. "BINARY DISTRIBUTION".
141 2.2. Customizing SBCL
143   You can tweak the *FEATURES* set for the resulting Lisp system,
144   enabling or disabling features like documentation strings, threads,
145   or extra debugging code.
147   The preferred way to do this is by creating a file
148   "customize-target-features.lisp", containing a lambda expression
149   which is applied to the default *FEATURES* set and which returns the
150   new *FEATURES* set, e.g.
152     (lambda (features)
153       (flet ((enable (x)
154                (pushnew x features))
155              (disable (x)
156                (setf features (remove x features))))
157         ;; Threading support, available only on x86/x86-64 Linux, x86 Solaris
158         ;; and x86 Mac OS X (experimental).
159         (enable :sb-thread)))
161   This is the preferred way because it lets local changes interact
162   cleanly with CVS changes to the main, global source tree.
164   A catalog of available features and their meaning can be found in
165   "base-target-features.lisp-expr".
167 2.3. Troubleshooting
169   "GNU Make not found"
171     If the GNU make command is not available under the names "make",
172     "gmake", or "gnumake", then define the environment variable
173     GNUMAKE to a name where it can be found.
175   Segfaults on Fedora
177     Try disabling exec-shield. The easiest way is to use
178     setarch: "setarch i386 -R sbcl".
180   Build crashes mysteriously, machine becomes unstable, etc
182     You may be running out of memory. Try increasing swap, or
183     building SBCL with fewer other programs running simultaneously.
185   Other
187     * Check that the host lisp you're building with is known to work as
188       an SBCL build host, and that your operating system is supported.
189       
190     * Try to do a build without loading any initialization files
191       for the cross-compilation host (for example
192       "sh make.sh 'sbcl --userinit /dev/null --sysinit /dev/null'").
194     * Some GCC versions are known to have bugs that affect SBCL
195       compilation: if the error you're encountering seems related to
196       files under "src/runtime", down- or upgrading GCC may help.
198     * Ask for help on the mailing lists referenced from
199       <http://www.sbcl.org/>.
201 2.4. Tracking SBCL sources
203   If you want to be on the bleeding edge, you can update your sources
204   to the latest development snapshot (or any previous development
205   snapshot, for that matter) by using anonymous CVS to
206   SourceForge. (This is not recommended if you're just using SBCL as a
207   tool for other work, but if you're interested in working on SBCL
208   itself, it's a good idea.) Follow the "CVS Repository" link on
209   <http://sourceforge.net/projects/sbcl> for instructions.
211 2.5. Supported platforms 
213   Last updated for SBCL 0.9.3.74 (2005-08-20).
215   All of the following platforms are supported in the sense of "should
216   work", but some things like loading foreign object files may lag
217   behind on less-used operating systems.
219   Supported toolchains:
221     GNU toolchain
222     Sun toolchain with GCC
224   Supported build hosts are:
226     SBCL
227     CMUCL
228     OpenMCL
229     CLISP (recent versions only)
230     ABCL (recent versions only)
232     Note that every release isn't tested with every possible host
233     compiler.  You're most likely to get a clean build with SBCL itself
234     as host, otherwise OpenMCL on a PPC and CMUCL elsewhere.
236   Supported operating systems and architectures:
238                            x86 PPC Alpha Sparc HPPA MIPS MIPSel x86-64
239     Linux 2.2, 2.4, 2.6     X   X    X     X    X    X     X      X
240     FreeBSD                 X
241     OpenBSD 3.4, 3.5        X
242     NetBSD                  X
243     Solaris                 X              X
244     Tru64                            X
245     Darwin (Mac OS X)       X   X
246     Windows                 X
248     Some operating systems are more equal than others: most of the
249     development and testing is done on x86/x86-64 Linux and x86/PPC
250     Mac OS X.
252     If an underprivileged platform is important to you, you can help
253     by e.g. testing during the monthly freeze periods, and most
254     importantly by reporting any problems.
256     If you need support beyond what is available on the mailing lists,
257     see "Consultants" in the "SUPPORT" file.