1 IF YOU HAVE A BINARY DISTRIBUTION:
3 The two files that SBCL needs to run, at minimum, are sbcl and sbcl.core.
8 In addition, there are a number of modules that extend the basic sbcl
12 sbcl is a standard executable, built by compiling and linking an
13 ordinary C program. It provides the runtime environment for the
14 running Lisp image, but it doesn't know much about high-level Lisp
15 stuff (like symbols and printing and objects) so it's pretty useless
16 by itself. sbcl.core is a dump file written in a special SBCL format
17 which only sbcl understands, and it contains all the high-level Lisp
20 In order to get a usable system, you need to run sbcl in a way that
21 it can find sbcl.core. There are three ways for it to find
24 1. by default, in /usr/lib/sbcl/sbcl.core or /usr/local/lib/sbcl/sbcl.core
25 (depending on the SBCL_HOME C preproccessor #define at compile-time)
26 2. by environment variable:
27 $ export SBCL_HOME=/foo/bar/lib/sbcl
29 3. by command line option:
30 $ sbcl --core /foo/bar/sbcl.core"
32 The usual, recommended approach is method #1. Method #2 is useful if
33 you're installing SBCL on a system in a non-standard location (e.g. in
34 your user account), instead of installing SBCL on an entire system.
35 Method #3 is mostly useful for testing or other special cases.
37 So: the standard installation procedure is
38 1. Copy sbcl.core to /usr/lib or /usr/local/lib.
39 2. Copy sbcl to /usr/bin or /usr/local/bin.
40 3. Copy the contrib modules that you're using (if any) to the same place
42 4. Optionally copy sbcl.1 to /usr/man/man1 or /usr/local/man/man1.
44 The script install.sh does all of this for you, including compilation
45 of all contrib modules it can find, and installation of all those that
46 pass their tests. You should set the INSTALL_ROOT environment
47 variable to /usr or /usr/local as appropriate before starting
50 # INSTALL_ROOT=/usr/local sh install.sh
52 $ INSTALL_ROOT=/home/me/sbcl sh install.sh
53 (if your INSTALL_ROOT is XYZ, SBCL_HOME should be set to
56 IF YOU HAVE A SOURCE DISTRIBUTION:
58 This software has been built successfully on these systems:
59 cpu = x86 (Intel 386 or higher, or compatibles like the AMD K6)
60 os = Debian GNU/Linux 2.1 with libc >= 2.1
61 host lisp = CMU CL 2.4.17
62 host lisp = SBCL itself
63 host lisp = CLISP CVS as of end of April
65 host lisp = SBCL itself
66 os = FreeBSD 3.4 or 4.0
68 host lisp = SBCL itself
69 os = OpenBSD 2.6, 2.7, 2.8, 2.9, and 3.0
70 host lisp = SBCL itself
72 os = Debian GNU/Linux 2.2 with libc >= 2.1
73 host lisp = SBCL itself
75 host lisp = SBCL itself
77 os = Debian GNU/Linux 2.2 with libc >= 2.2
78 host lisp = SBCL itself
80 host lisp = SBCL itself
82 os = Debian GNU/Linux 2.2 with libc >= 2.1
83 host lisp = OpenMCL 0.12
84 host lisp = SBCL itself
86 host lisp = OpenMCL 0.13.6
87 host lisp = SBCL itself
89 os = Debian GNU/Linux 3.0
90 host lisp = SBCL itself
92 Reports of other systems that it works on (or doesn't work on, for
93 that matter), or help in making it run on more systems, would be
96 CAUTION CAUTION CAUTION CAUTION CAUTION
97 SBCL, like CMU CL, overcommits memory. That is, it
98 asks the OS for more virtual memory address space than
99 it actually intends to use, and the OS is expected to
100 optimistically give it this address space even if the OS
101 doesn't have enough RAM+swap to back it up. This works
102 fine as long as SBCL's memory usage pattern is sparse
103 enough that the OS can actually implement the requested
104 VM usage. Unfortunately, if the OS runs out of RAM+swap to
105 implement the requested VM usage, things get bad. On many
106 systems, including the Linux 2.2.13 kernel that I used for
107 development of SBCL up to version 0.6.0, the kernel kills
108 processes more-or-less randomly when it runs out of
109 resources. You may think your Linux box is very stable, but
110 it is unlikely to be stable if this happens.:-| So be sure
111 to have enough memory available when you build the system.
112 (This can be considered a bug in SBCL, or a bug in the
113 Unix overcommitment-of-memory architecture, or both. It's
114 not clear what the best fix is. On the SBCL side, Peter Van
115 Eynde has a lazy-allocation patch for CMU CL that lets
116 it run without overcommitting memory, and that could be
117 ported to SBCL, but unfortunately that might introduce
118 new issues, e.g. alien programs allocating memory in the
119 address space that SBCL thinks of as its own, and later
120 getting trashed when SBCL lazily allocates the memory.
121 On the OS side, there might be some way to address the
122 problem with quotas, I don't know.)
124 To build the system binaries:
125 0. If you want to be on the bleeding edge, you can update your
126 sources to the latest development snapshot (or any previous
127 development snapshot, for that matter) by using anonymous CVS
128 to SourceForge. (This is not recommended if you're just using SBCL
129 as a tool for other work, but if you're interested in working on
130 SBCL itself, it's a good idea.) Follow the "CVS Repository" link on
131 <http://sourceforge.net/projects/sbcl> for instructions.
132 1. Make sure that you have enough RAM+swap to build SBCL, as
133 per the CAUTION note above. (As of version 0.6.0, the most
134 memory-intensive operation in make.sh is the second call to
135 GENESIS, which makes the Lisp image grow to around 128 Mb RAM+swap.
136 2. If the GNU make command is not available under the names "gmake"
137 or "make", then define the environment variable GNUMAKE to a name
138 where it can be found.
139 3. If you like, you can tweak the *FEATURES* set for the resulting
140 Lisp system, enabling or disabling features like documentation
141 strings, threads, or extra debugging code (see
142 "base-target-features.lisp-expr" for a list of recognized
143 *FEATURES*). The preferred way to do this is by creating a file
144 "customize-target-features.lisp", containing a lambda expression
145 which is applied to the default *FEATURES* set and which returns
146 the new *FEATURES* set, e.g.
151 (This is the preferred way because it lets local changes interact
152 cleanly with CVS changes to the main, global source tree.)
153 4. Run "sh make.sh" in the same directory where you unpacked the
154 tarball. If you don't already have a SBCL binary installed
155 as "sbcl" in your path, you'll need to tell make.sh what Lisp
156 system to use as the cross-compilation host. (To use CMU CL
157 as the cross-compilation host, run "sh make.sh 'lisp -batch'",
158 assuming CMU CL has been installed under its default name "lisp".)
159 5. Wait. This can be a slow process. On my test machines, the
160 wall clock time for a build of sbcl-0.6.7 was approximately
161 1.5 hours on a 450MHz K6/3 with 248Mb RAM, running RH Linux 6.2;
162 4 hours on a 200MHz Pentium (P54C) with 64Mb RAM, running FreeBSD 4.0;
163 13 hours on a 133MHz Pentium (P54C) with 48Mb RAM, running OpenBSD 2.6.
164 Around the 48Mb mark, the build process is starved for RAM:
165 on my 48Mb OpenBSD machine with nothing else running, it
166 spent about 2/3 of its wall clock time swapping.
168 Now you should have the same src/runtime/sbcl and output/sbcl.core
169 files that come with the binary distribution, and you can install
170 them as in the "IF YOU HAVE A BINARY DISTRIBUTION" instructions (above).
172 To convert the DocBook version of the system documentation (files
173 ending in .sgml) to more-readable form (HTML or text):
174 DocBook is an abstract markup system based on SGML. It's intended
175 to be automatically translated to other formats. Tools to do this
176 exist on the web, and are becoming increasingly easy to find as
177 more free software projects move their documentation to DocBook.
178 Any one of these systems should work with the SBCL documentation.
179 If you'd like to have the documentation produced in the same
180 format as appears in the binary distribution, and you have
181 the jade binary and Norman Walsh's modular DSSSL stylesheets
182 installed, you can try the doc/make-doc.sh script. Otherwise,
183 your formatted copy of the SBCL documentation should have the
184 same content as in the binary distribution, but details of
185 presentation will probably vary.