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:
184 Native threads. Enabled by default on x86[-64] Linux only, also
185 available on x86[-64] Max OS X, x86[-64] FreeBSD, x86 Solaris,
188 NOTE: --fancy enables threads on all platforms where they can
189 be built, even if they aren't 100% stable on that platform.
192 Adds zlib as a build-dependency, and makes SBCL able to save
193 compressed cores. Not enabled by default.
195 :SB-XREF-FOR-INTERNALS
196 XREF data for SBCL internals. Not enabled by default, increases
200 Unicode support. Enabled by default. Disabling this feature
201 limits characters to the 8-bit ISO-8859-1 set.
203 A catalog of available features and their meaning can be found in
204 "base-target-features.lisp-expr".
206 Please do NOT edit base-target-features.lisp-expr in order to enable
207 or disable build features.
213 If the GNU make command is not available under the names "make",
214 "gmake", or "gnumake", then define the environment variable
215 GNUMAKE to a name where it can be found.
219 Try disabling exec-shield. The easiest way is to use
220 setarch: "setarch i386 -R sbcl".
222 Build crashes mysteriously, machine becomes unstable, etc
224 You may be running out of memory. Try increasing swap, or
225 building SBCL with fewer other programs running simultaneously.
229 * Check that the host lisp you're building with is known to work as
230 an SBCL build host, and that your operating system is supported.
232 * Try to do a build without loading any initialization files
233 for the cross-compilation host (for example
234 "sh make.sh 'sbcl --userinit /dev/null --sysinit /dev/null'").
236 * Some GCC versions are known to have bugs that affect SBCL
237 compilation: if the error you're encountering seems related to
238 files under "src/runtime", down- or upgrading GCC may help.
240 * Ask for help on the mailing lists referenced from
241 <http://www.sbcl.org/>.
243 2.4. Tracking SBCL sources
245 If you want to be on the bleeding edge, you can update your sources
246 to the latest development snapshot (or any previous development
247 snapshot, for that matter) by using anonymous CVS to
248 SourceForge. (This is not recommended if you're just using SBCL as a
249 tool for other work, but if you're interested in working on SBCL
250 itself, it's a good idea.) Follow the "CVS Repository" link on
251 <http://sourceforge.net/projects/sbcl> for instructions.
253 2.5. Supported platforms
255 Last updated for SBCL 0.9.3.74 (2005-08-20).
257 All of the following platforms are supported in the sense of "should
258 work", but some things like loading foreign object files may lag
259 behind on less-used operating systems.
261 Supported toolchains:
264 Sun toolchain with GCC
266 Supported build hosts are:
270 CCL (formerly known as OpenMCL)
271 ABCL (recent versions only)
272 CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
276 Note that every release isn't tested with every possible host
277 compiler. You're most likely to get a clean build with SBCL itself
278 as host, otherwise CCL on a PPC and CMUCL elsewhere.
280 Supported operating systems and architectures:
282 x86 x86-64 PPC Sparc Alpha MIPS MIPSel
283 Linux 2.6 X X X X X X X
284 Darwin (Mac OS X) X X X
291 Some operating systems are more equal than others: most of the
292 development and testing is done on x86/x86-64 Linux and x86/PPC
295 If an underprivileged platform is important to you, you can help
296 by e.g. testing during the monthly freeze periods, and most
297 importantly by reporting any problems.
299 For further support, see Getting Support and Reporting Bugs
302 http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
304 if you do not have the manual for some reason.