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