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=4Gb
133 $ sh make.sh --dynamic-space-size=800Mb
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.)
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:
146 $ sh make.sh --xc-host='lisp -batch -noinit'
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...".
152 To run the regression tests:
154 $ cd tests && sh run-tests.sh
156 To build documentation:
158 $ cd doc/manual && make
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.
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".
169 2.2. Customizing SBCL
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.
175 The preferred way to do this is using commandline arguments to make.sh:
177 --fancy Enables all supported feature enhancements.
178 --with-<feature> Enables a specific feature.
179 --without-<feature> Disables a specific feature.
181 Some features of interest:
183 :SB-THREAD (--with-sb-thread, --without-sb-thread)
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,
189 NOTE: --fancy enables threads on all platforms where they can be
190 built, even if they aren't 100% stable on that platform.
192 :SB-CORE-COMPRESSION (--with-sb-core-compression)
194 Adds zlib as a build-dependency, and makes SBCL able to save
195 compressed cores. Not enabled by default.
197 :SB-XREF-FOR-INTERNALS (--with-sb-xref-for-internals)
199 XREF data for SBCL internals. Not enabled by default, increases
202 :SB-UNICODE (--without-sb-unicode)
204 Unicode support. Enabled by default. Disabling this feature
205 limits characters to the 8-bit ISO-8859-1 set.
207 A catalog of available features and their meaning can be found in
208 "base-target-features.lisp-expr".
210 Please do NOT edit base-target-features.lisp-expr in order to enable
211 or disable build features.
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.
223 Try disabling exec-shield. The easiest way is to use
224 setarch: "setarch i386 -R sbcl".
226 Build crashes mysteriously, machine becomes unstable, etc
228 You may be running out of memory. Try increasing swap, or
229 building SBCL with fewer other programs running simultaneously.
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.
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'").
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.
244 * Ask for help on the mailing lists referenced from
245 <http://www.sbcl.org/>.
247 2.4. Tracking SBCL sources
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.
257 2.5. Supported platforms
259 Last updated for SBCL 0.9.3.74 (2005-08-20).
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.
265 Supported toolchains:
268 Sun toolchain with GCC
270 Supported build hosts are:
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)
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.
284 Supported operating systems and architectures:
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
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
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.
303 For further support, see Getting Support and Reporting Bugs
306 http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
308 if you do not have the manual for some reason.