7 1.2. Finding ancillary files
10 2. SOURCE DISTRIBUTION
14 2.4. Tracking SBCL sources
15 2.5. Supported platforms
18 1. BINARY DISTRIBUTION
22 To run SBCL without installing it, from the top of binary distribution
27 The following command installs SBCL and related documentation under
28 the "/usr/local" directory (typically run as root):
30 # INSTALL_ROOT=/usr/local sh install.sh
32 You can also install SBCL as a user, under your home directory:
34 $ INSTALL_ROOT=/home/me sh install.sh
36 In other words, "install.sh" installs SBCL under the directory named
37 by the environment variable INSTALL_ROOT.
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.
43 If you install SBCL from binary distribution in other location than
44 "/usr/local", see section 1.2, "Finding ancillary files".
46 1.2. Finding ancillary files
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.
51 Finding core can happen in three ways:
53 1. By default, in a location configured when the system was built.
54 For binary distributions this is in "/usr/local/lib/sbcl".
56 2. By environment variable, in the directory named by the
57 environment variable "SBCL_HOME". Example:
59 $ export SBCL_HOME=/foo/bar/lib/sbcl
62 If your "INSTALL_ROOT" was FOO, then your "SBCL_HOME" is
65 3. By command line option:
67 $ sbcl --core /foo/bar/sbcl.core
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
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
82 The two files that SBCL needs to run, at minimum, are:
87 In addition, there are a number of modules that extend the basic
88 sbcl functionality, in
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.
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"
106 Documentation consists of a man-page, the SBCL Manual (in info, pdf
107 and html formats), and a few additional text files.
109 2. SOURCE DISTRIBUTION
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.
117 To build SBCL using an already installed SBCL:
121 To configure SBCL to install to a non-standard location, you can use
124 $ sh make.sh --prefix=/opt/mysbcl
126 This also sets the default SBCL_HOME to prefix/lib/sbcl/ for the
129 To configure SBCL with a non-standard default dynamic-space size,
130 use the --dynamic-space-size option:
132 $ sh make.sh --dynamic-space-size=1Gb
133 $ sh make.sh --dynamic-space-size=500Mb
135 If mega- or gigabytes are not specified, the number is taken to be
136 in megabytes. The standard default is platform specific.
138 If you don't already have an SBCL binary installed as "sbcl" on your
139 system, you'll need to tell make.sh what Lisp to use as the
140 cross-compilation host. For example, to use CMUCL (assuming has
141 been installed under its default name "lisp") as the
142 cross-compilation host:
144 $ sh make.sh --xc-host='lisp -batch -noinit'
146 The build may take a long time, especially on older hardware. A
147 successful build ends with a message beginning: "The build seems to
148 have finished successfully...".
150 To run the regression tests:
152 $ cd tests && sh run-tests.sh
154 To build documentation:
156 $ cd doc/manual && make
158 This builds the Info, HTML and PDF documentation from the Texinfo
159 sources. The manual includes documentation string from the build
160 SBCL, but if SBCL itself has not been yet built, but one if found
161 installed documentation strings from the installed version are used.
163 Now you should have the same src/runtime/sbcl and output/sbcl.core
164 files that come with the binary distribution, and you can install
165 them as described in the section 1. "BINARY DISTRIBUTION".
167 2.2. Customizing SBCL
169 You can tweak the *FEATURES* set for the resulting Lisp system,
170 enabling or disabling features like documentation strings, threads,
171 or extra debugging code.
173 The preferred way to do this is by creating a file
174 "customize-target-features.lisp", containing a lambda expression
175 which is applied to the default *FEATURES* set and which returns the
176 new *FEATURES* set, e.g.
180 (pushnew x features))
182 (setf features (remove x features))))
183 ;; Threading support.
184 (enable :sb-thread)))
186 This is the preferred way because it lets local changes interact
187 cleanly with CVS changes to the main, global source tree.
189 Some features of interest:
192 Native threads. Enabled by default on x86[-64] Linux only, also
193 available on x86[-64] Max OS X, x86[-64] FreeBSD, x86 Solaris,
197 Unicode support. Enabled by default. Disabling this feature
198 limits characters to the 8-bit ISO-8859-1 set.
200 :SB-XREF-FOR-INTERNALS
201 XREF data for SBCL internals. Not enabled by default, increases
204 A catalog of available features and their meaning can be found in
205 "base-target-features.lisp-expr".
211 If the GNU make command is not available under the names "make",
212 "gmake", or "gnumake", then define the environment variable
213 GNUMAKE to a name where it can be found.
217 Try disabling exec-shield. The easiest way is to use
218 setarch: "setarch i386 -R sbcl".
220 Build crashes mysteriously, machine becomes unstable, etc
222 You may be running out of memory. Try increasing swap, or
223 building SBCL with fewer other programs running simultaneously.
227 * Check that the host lisp you're building with is known to work as
228 an SBCL build host, and that your operating system is supported.
230 * Try to do a build without loading any initialization files
231 for the cross-compilation host (for example
232 "sh make.sh 'sbcl --userinit /dev/null --sysinit /dev/null'").
234 * Some GCC versions are known to have bugs that affect SBCL
235 compilation: if the error you're encountering seems related to
236 files under "src/runtime", down- or upgrading GCC may help.
238 * Ask for help on the mailing lists referenced from
239 <http://www.sbcl.org/>.
241 2.4. Tracking SBCL sources
243 If you want to be on the bleeding edge, you can update your sources
244 to the latest development snapshot (or any previous development
245 snapshot, for that matter) by using anonymous CVS to
246 SourceForge. (This is not recommended if you're just using SBCL as a
247 tool for other work, but if you're interested in working on SBCL
248 itself, it's a good idea.) Follow the "CVS Repository" link on
249 <http://sourceforge.net/projects/sbcl> for instructions.
251 2.5. Supported platforms
253 Last updated for SBCL 0.9.3.74 (2005-08-20).
255 All of the following platforms are supported in the sense of "should
256 work", but some things like loading foreign object files may lag
257 behind on less-used operating systems.
259 Supported toolchains:
262 Sun toolchain with GCC
264 Supported build hosts are:
268 CCL (formerly known as OpenMCL)
269 ABCL (recent versions only)
270 CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
274 Note that every release isn't tested with every possible host
275 compiler. You're most likely to get a clean build with SBCL itself
276 as host, otherwise CCL on a PPC and CMUCL elsewhere.
278 Supported operating systems and architectures:
280 x86 x86-64 PPC Sparc Alpha MIPS MIPSel
281 Linux 2.6 X X X X X X X
282 Darwin (Mac OS X) X X X
289 Some operating systems are more equal than others: most of the
290 development and testing is done on x86/x86-64 Linux and x86/PPC
293 If an underprivileged platform is important to you, you can help
294 by e.g. testing during the monthly freeze periods, and most
295 importantly by reporting any problems.
297 For further support, see Getting Support and Reporting Bugs
300 http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
302 if you do not have the manual for some reason.