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 If you don't already have an SBCL binary installed as "sbcl" on your
130 system, you'll need to tell make.sh what Lisp to use as the
131 cross-compilation host. For example, to use CMUCL (assuming has
132 been installed under its default name "lisp") as the
133 cross-compilation host:
135 $ sh make.sh --xc-host='lisp -batch -noinit'
137 The build may take a long time, especially on older hardware. A
138 successful build ends with a message beginning: "The build seems to
139 have finished successfully...".
141 To run the regression tests:
143 $ cd tests && sh run-tests.sh
145 To build documentation:
147 $ cd doc/manual && make
149 This builds the Info, HTML and PDF documentation from the Texinfo
150 sources. The manual includes documentation string from the build
151 SBCL, but if SBCL itself has not been yet built, but one if found
152 installed documentation strings from the installed version are used.
154 Now you should have the same src/runtime/sbcl and output/sbcl.core
155 files that come with the binary distribution, and you can install
156 them as described in the section 1. "BINARY DISTRIBUTION".
158 2.2. Customizing SBCL
160 You can tweak the *FEATURES* set for the resulting Lisp system,
161 enabling or disabling features like documentation strings, threads,
162 or extra debugging code.
164 The preferred way to do this is by creating a file
165 "customize-target-features.lisp", containing a lambda expression
166 which is applied to the default *FEATURES* set and which returns the
167 new *FEATURES* set, e.g.
171 (pushnew x features))
173 (setf features (remove x features))))
174 ;; Threading support.
175 (enable :sb-thread)))
177 This is the preferred way because it lets local changes interact
178 cleanly with CVS changes to the main, global source tree.
180 Some features of interest:
183 Native threads. Enabled by default on x86[-64] Linux only, also
184 available on x86[-64] Max OS X, x86[-64] FreeBSD, x86 Solaris,
188 Unicode support. Enabled by default. Disabling this feature
189 limits characters to the 8-bit ISO-8859-1 set.
191 :SB-XREF-FOR-INTERNALS
192 XREF data for SBCL internals. Not enabled by default, increases
195 A catalog of available features and their meaning can be found in
196 "base-target-features.lisp-expr".
202 If the GNU make command is not available under the names "make",
203 "gmake", or "gnumake", then define the environment variable
204 GNUMAKE to a name where it can be found.
208 Try disabling exec-shield. The easiest way is to use
209 setarch: "setarch i386 -R sbcl".
211 Build crashes mysteriously, machine becomes unstable, etc
213 You may be running out of memory. Try increasing swap, or
214 building SBCL with fewer other programs running simultaneously.
218 * Check that the host lisp you're building with is known to work as
219 an SBCL build host, and that your operating system is supported.
221 * Try to do a build without loading any initialization files
222 for the cross-compilation host (for example
223 "sh make.sh 'sbcl --userinit /dev/null --sysinit /dev/null'").
225 * Some GCC versions are known to have bugs that affect SBCL
226 compilation: if the error you're encountering seems related to
227 files under "src/runtime", down- or upgrading GCC may help.
229 * Ask for help on the mailing lists referenced from
230 <http://www.sbcl.org/>.
232 2.4. Tracking SBCL sources
234 If you want to be on the bleeding edge, you can update your sources
235 to the latest development snapshot (or any previous development
236 snapshot, for that matter) by using anonymous CVS to
237 SourceForge. (This is not recommended if you're just using SBCL as a
238 tool for other work, but if you're interested in working on SBCL
239 itself, it's a good idea.) Follow the "CVS Repository" link on
240 <http://sourceforge.net/projects/sbcl> for instructions.
242 2.5. Supported platforms
244 Last updated for SBCL 0.9.3.74 (2005-08-20).
246 All of the following platforms are supported in the sense of "should
247 work", but some things like loading foreign object files may lag
248 behind on less-used operating systems.
250 Supported toolchains:
253 Sun toolchain with GCC
255 Supported build hosts are:
259 CCL (formerly known as OpenMCL)
260 ABCL (recent versions only)
261 CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
265 Note that every release isn't tested with every possible host
266 compiler. You're most likely to get a clean build with SBCL itself
267 as host, otherwise CCL on a PPC and CMUCL elsewhere.
269 Supported operating systems and architectures:
271 x86 x86-64 PPC Sparc Alpha MIPS MIPSel
272 Linux 2.6 X X X X X X X
273 Darwin (Mac OS X) X X X
280 Some operating systems are more equal than others: most of the
281 development and testing is done on x86/x86-64 Linux and x86/PPC
284 If an underprivileged platform is important to you, you can help
285 by e.g. testing during the monthly freeze periods, and most
286 importantly by reporting any problems.
288 For further support, see Getting Support and Reporting Bugs
291 http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
293 if you do not have the manual for some reason.