runtime/cheneygc.c: Use binding-stack-pointer access macro.
[sbcl.git] / INSTALL
1 INSTALLING SBCL
2
3   CONTENTS
4
5     1. BINARY DISTRIBUTION
6     1.1. Quick start
7     1.2. Finding ancillary 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   To run SBCL without installing it, from the top of binary distribution
23   directory:
24
25     $ sh run-sbcl.sh
26
27   The following command installs SBCL and related documentation under
28   the "/usr/local" directory (typically run as root):
29
30     # INSTALL_ROOT=/usr/local sh install.sh
31
32   You can also install SBCL as a user, under your home directory:
33
34     $ INSTALL_ROOT=/home/me sh install.sh
35
36   In other words, "install.sh" installs SBCL under the directory named
37   by the environment variable INSTALL_ROOT.
38
39   If INSTALL_ROOT is not specified, SBCL is installed into location
40   configured at build-time: for official binary distributions under
41   "/usr/local" directory.
42
43   If you install SBCL from binary distribution in other location than
44   "/usr/local", see section 1.2, "Finding ancillary files".
45
46 1.2. Finding ancillary files
47
48   The SBCL runtime needs to be able to find the ancillary files
49   associated with it: the "sbcl.core" file, and the contrib modules.
50
51   Finding core can happen in three ways:
52
53     1. By default, in a location configured when the system was built.
54        For binary distributions this is in "/usr/local/lib/sbcl".
55
56     2. By environment variable, in the directory named by the
57        environment variable "SBCL_HOME". Example:
58
59          $ export SBCL_HOME=/foo/bar/lib/sbcl
60          $ sbcl
61
62        If your "INSTALL_ROOT" was FOO, then your "SBCL_HOME" is
63        "FOO/lib/sbcl".
64
65     3. By command line option:
66
67          $ sbcl --core /foo/bar/sbcl.core
68
69   The usual, recommended approach is method #1. Method #2 is useful if
70   you're installing SBCL on a system in a non-standard location
71   (e.g. in your user account), instead of installing SBCL on an entire
72   system.  Method #3 is mostly useful for testing or other special
73   cases.
74
75   Contributed modules are primarily looked for in "SBCL_HOME", or the
76   directory the core resides in if "SBCL_HOME" is not set.
77   ASDF:*CENTRAL-REGISTRY* serves as an additional fallback for
78   ASDF-based modules.
79
80 1.3. Anatomy of SBCL
81
82   The two files that SBCL needs to run, at minimum, are:
83
84     src/runtime/sbcl
85     output/sbcl.core
86
87   In addition, there are a number of modules that extend the basic
88   sbcl functionality, in
89
90     contrib/
91
92   The "src/runtime/sbcl" is a standard executable, built by compiling
93   and linking an ordinary C program. It provides the runtime
94   environment for the running Lisp image, but it doesn't know much
95   about high-level Lisp stuff (like symbols and printing and objects)
96   so it's pretty useless by itself. The "output/sbcl.core" is a dump
97   file written in a special SBCL format which only sbcl understands,
98   and it contains all the high-level Lisp stuff.
99
100   The standard installation procedure, outlined in section 1.1 "Quick
101   start", is to run the "install.sh", which copies all the files to
102   right places, including documentation and contrib-modules that have
103   passed their tests. If you need to install by hand, see "install.sh"
104   for details.
105
106   Documentation consists of a man-page, the SBCL Manual (in info, pdf
107   and html formats), and a few additional text files.
108
109 2. SOURCE DISTRIBUTION
110
111 2.1. Quick start
112
113   To build SBCL you need a working toolchain and a Common Lisp system
114   (see section 2.5 "Supported platforms"). You also need approximately
115   128 Mb of free RAM+swap.
116
117   To build SBCL using an already installed SBCL:
118
119     $ sh make.sh
120
121   To configure SBCL to install to a non-standard location, you can use
122   the --prefix option:
123
124     $ sh make.sh --prefix=/opt/mysbcl
125
126   This also sets the default SBCL_HOME to prefix/lib/sbcl/ for the
127   built binaries.
128
129   To configure SBCL with a non-standard default dynamic-space size,
130   use the --dynamic-space-size option:
131
132     $ sh make.sh --dynamic-space-size=4Gb
133     $ sh make.sh --dynamic-space-size=800Mb
134
135   If mega- or gigabytes are not specified, the number is taken to be
136   in megabytes. The standard default is 512Mb for 32-bit systems, and
137   1Gb for 64-bit systems (with the exception of OpenBSD where 444Mb
138   are used to fit under default ulimits.)
139
140   If you don't already have an SBCL binary installed as "sbcl" on your
141   system, you'll need to tell make.sh what Lisp to use as the
142   cross-compilation host. For example, to use CMUCL (assuming has
143   been installed under its default name "lisp") as the
144   cross-compilation host:
145
146     $ sh make.sh --xc-host='lisp -batch -noinit'
147
148   The build may take a long time, especially on older hardware. A
149   successful build ends with a message beginning: "The build seems to
150   have finished successfully...".
151
152   To run the regression tests:
153
154     $ cd tests && sh run-tests.sh
155
156   To build documentation:
157
158     $ cd doc/manual && make
159
160   This builds the Info, HTML and PDF documentation from the Texinfo
161   sources. The manual includes documentation string from the build
162   SBCL, but if SBCL itself has not been yet built, but one if found
163   installed documentation strings from the installed version are used.
164
165   Now you should have the same src/runtime/sbcl and output/sbcl.core
166   files that come with the binary distribution, and you can install
167   them as described in the section 1. "BINARY DISTRIBUTION".
168
169 2.2. Customizing SBCL
170
171   You can tweak the *FEATURES* set for the resulting Lisp system,
172   enabling or disabling features like documentation strings, threads,
173   or extra debugging code.
174
175   The preferred way to do this is using commandline arguments to make.sh:
176
177     --fancy                    Enables all supported feature enhancements.
178     --with-<feature>           Enables a specific feature.
179     --without-<feature>        Disables a specific feature.
180
181   Some features of interest:
182
183     :SB-THREAD (--with-sb-thread, --without-sb-thread)
184
185       Native threads. Enabled by default on x86[-64] Linux only, also
186       available on x86[-64] Max OS X, x86[-64] FreeBSD, x86 Solaris,
187       and PPC Linux.
188
189       NOTE: --fancy enables threads on all platforms where they can be
190       built, even if they aren't 100% stable on that platform.
191
192     :SB-CORE-COMPRESSION (--with-sb-core-compression)
193
194       Adds zlib as a build-dependency, and makes SBCL able to save
195       compressed cores. Not enabled by default.
196
197     :SB-XREF-FOR-INTERNALS (--with-sb-xref-for-internals)
198
199       XREF data for SBCL internals. Not enabled by default, increases
200       core size by 5-6mb.
201
202     :SB-UNICODE (--without-sb-unicode)
203
204       Unicode support. Enabled by default. Disabling this feature
205       limits characters to the 8-bit ISO-8859-1 set.
206
207   A catalog of available features and their meaning can be found in
208   "base-target-features.lisp-expr".
209
210   Please do NOT edit base-target-features.lisp-expr in order to enable
211   or disable build features.
212
213 2.3. Troubleshooting
214
215   "GNU Make not found"
216
217     If the GNU make command is not available under the names "make",
218     "gmake", or "gnumake", then define the environment variable
219     GNUMAKE to a name where it can be found.
220
221   Segfaults on Fedora
222
223     Try disabling exec-shield. The easiest way is to use
224     setarch: "setarch i386 -R sbcl".
225
226   Build crashes mysteriously, machine becomes unstable, etc
227
228     You may be running out of memory. Try increasing swap, or
229     building SBCL with fewer other programs running simultaneously.
230
231   Other
232
233     * Check that the host lisp you're building with is known to work as
234       an SBCL build host, and that your operating system is supported.
235
236     * Try to do a build without loading any initialization files
237       for the cross-compilation host (for example
238       "sh make.sh 'sbcl --userinit /dev/null --sysinit /dev/null'").
239
240     * Some GCC versions are known to have bugs that affect SBCL
241       compilation: if the error you're encountering seems related to
242       files under "src/runtime", down- or upgrading GCC may help.
243
244     * Ask for help on the mailing lists referenced from
245       <http://www.sbcl.org/>.
246
247 2.4. Tracking SBCL sources
248
249   If you want to be on the bleeding edge, you can update your sources
250   to the latest development snapshot (or any previous development
251   snapshot, for that matter) by using anonymous CVS to
252   SourceForge. (This is not recommended if you're just using SBCL as a
253   tool for other work, but if you're interested in working on SBCL
254   itself, it's a good idea.) Follow the "CVS Repository" link on
255   <http://sourceforge.net/projects/sbcl> for instructions.
256
257 2.5. Supported platforms
258
259   Last updated for SBCL 0.9.3.74 (2005-08-20).
260
261   All of the following platforms are supported in the sense of "should
262   work", but some things like loading foreign object files may lag
263   behind on less-used operating systems.
264
265   Supported toolchains:
266
267     GNU toolchain
268     Sun toolchain with GCC
269
270   Supported build hosts are:
271
272     SBCL
273     CMUCL
274     CCL (formerly known as OpenMCL)
275     ABCL (recent versions only)
276     CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
277     XCL
278     
279
280     Note that every release isn't tested with every possible host
281     compiler.  You're most likely to get a clean build with SBCL itself
282     as host, otherwise CCL on a PPC and CMUCL elsewhere.
283
284   Supported operating systems and architectures:
285
286                            x86 x86-64 PPC Sparc Alpha MIPS MIPSel
287     Linux 2.6               X     X    X    X     X     X     X
288     Darwin (Mac OS X)       X     X    X
289     Solaris                 X               X
290     FreeBSD                 X     X
291     NetBSD                  X          X
292     OpenBSD 3.4, 3.5        X
293     Windows                 X
294
295     Some operating systems are more equal than others: most of the
296     development and testing is done on x86/x86-64 Linux and x86/PPC
297     Mac OS X.
298
299     If an underprivileged platform is important to you, you can help
300     by e.g. testing during the monthly freeze periods, and most
301     importantly by reporting any problems.
302
303     For further support, see Getting Support and Reporting Bugs
304     in the manual, or
305
306       http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
307
308     if you do not have the manual for some reason.