Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 282 lines (194 sloc) 9.248 kb
c05927a @nikodemus 0.8.10.61:
nikodemus authored
1 INSTALLING SBCL
2
3 CONTENTS
4
5 1. BINARY DISTRIBUTION
6 1.1. Quick start
4ac05a1 0.9.3.43:
Nathan Froyd authored
7 1.2. Finding ancillary files
c05927a @nikodemus 0.8.10.61:
nikodemus authored
8 1.3. Anatomy of SBCL
9
10 2. SOURCE DISTRIBUTION
11 2.1. Quick start
12 2.2. Customizing SBCL
13 2.3. Troubleshooting
14 2.4. Tracking SBCL sources
15 2.5. Supported platforms
16
17
18 1. BINARY DISTRIBUTION
19
20 1.1. Quick start:
21
e9d20db @nikodemus 1.0.13.29: run-sbcl.sh script
nikodemus authored
22 To run SBCL without installing it, from the top of binary distribution
23 directory:
24
25 $ sh run-sbcl.sh
26
c05927a @nikodemus 0.8.10.61:
nikodemus authored
27 The following command installs SBCL and related documentation under
1baab0b @nikodemus 1.0.33.26: enabled threads by default on x86[-64] Linux
nikodemus authored
28 the "/usr/local" directory (typically run as root):
72bd7d1 1.0.27.49: update platform table, credit me
Gabor Melis authored
29
c05927a @nikodemus 0.8.10.61:
nikodemus authored
30 # INSTALL_ROOT=/usr/local sh install.sh
31
32 You can also install SBCL as a user, under your home directory:
33
34 $ INSTALL_ROOT=/home/me sh install.sh
35
36 In other words, "install.sh" installs SBCL under the directory named
37 by the environment variable "INSTALL_ROOT".
38
6c2c952 0.9.3.54:
Nathan Froyd authored
39 If you install SBCL from binary distribution in other location than
4ac05a1 0.9.3.43:
Nathan Froyd authored
40 "/usr/local", see section 1.2, "Finding ancillary files".
c05927a @nikodemus 0.8.10.61:
nikodemus authored
41
4ac05a1 0.9.3.43:
Nathan Froyd authored
42 1.2. Finding ancillary files
c05927a @nikodemus 0.8.10.61:
nikodemus authored
43
44 The SBCL runtime needs to be able to find the ancillary files
45 associated with it: the "sbcl.core" file, and the contrib modules.
46
80f2223 @nikodemus 0.8.13.41: Require robustness
nikodemus authored
47 Finding core can happen in three ways:
c05927a @nikodemus 0.8.10.61:
nikodemus authored
48
49 1. By default, in a location configured when the system was built.
50 For binary distributions this is in "/usr/local/lib/sbcl".
51
52 2. By environment variable, in the directory named by the
53 environment variable "SBCL_HOME". Example:
54
55 $ export SBCL_HOME=/foo/bar/lib/sbcl
56 $ sbcl
57
58 If your "INSTALL_ROOT" was FOO, then your "SBCL_HOME" is
59 "FOO/lib/sbcl".
60
61 3. By command line option:
62
63 $ sbcl --core /foo/bar/sbcl.core
64
65 The usual, recommended approach is method #1. Method #2 is useful if
66 you're installing SBCL on a system in a non-standard location
67 (e.g. in your user account), instead of installing SBCL on an entire
68 system. Method #3 is mostly useful for testing or other special
69 cases.
70
80f2223 @nikodemus 0.8.13.41: Require robustness
nikodemus authored
71 Contributed modules are primarily looked for in "SBCL_HOME", or the
72 directory the core resides in if "SBCL_HOME" is not set.
73 ASDF:*CENTRAL-REGISTRY* serves as an additional fallback for
74 ASDF-based modules.
75
c05927a @nikodemus 0.8.10.61:
nikodemus authored
76 1.3. Anatomy of SBCL
77
78 The two files that SBCL needs to run, at minimum, are:
79
80 src/runtime/sbcl
81 output/sbcl.core
82
83 In addition, there are a number of modules that extend the basic
84 sbcl functionality, in
85
86 contrib/
87
88 The "src/runtime/sbcl" is a standard executable, built by compiling
89 and linking an ordinary C program. It provides the runtime
90 environment for the running Lisp image, but it doesn't know much
91 about high-level Lisp stuff (like symbols and printing and objects)
92 so it's pretty useless by itself. The "output/sbcl.core" is a dump
93 file written in a special SBCL format which only sbcl understands,
94 and it contains all the high-level Lisp stuff.
95
96 The standard installation procedure, outlined in section 1.1 "Quick
97 start", is to run the "install.sh", which copies all the files to
98 right places, including documentation and contrib-modules that have
99 passed their tests. If you need to install by hand, see "install.sh"
100 for details.
101
4ac05a1 0.9.3.43:
Nathan Froyd authored
102 Documentation consists of a man-page, the SBCL Manual (in info, pdf
c05927a @nikodemus 0.8.10.61:
nikodemus authored
103 and html formats), and a few additional text files.
104
105 2. SOURCE DISTRIBUTION
106
107 2.1. Quick start
108
109 To build SBCL you need a working toolchain and a Common Lisp system
110 (see section 2.5 "Supported platforms"). You also need approximately
111 128 Mb of free RAM+swap.
112
113 To build SBCL using an already installed SBCL:
114
115 $ sh make.sh
116
117 If you don't already have an SBCL binary installed as "sbcl" on your
118 system, you'll need to tell make.sh what Lisp to use as the
4ac05a1 0.9.3.43:
Nathan Froyd authored
119 cross-compilation host. For example, to use CMUCL (assuming has
c05927a @nikodemus 0.8.10.61:
nikodemus authored
120 been installed under its default name "lisp") as the
121 cross-compilation host:
122
b03ad9b @jsnell 0.9.3.74:
jsnell authored
123 $ sh make.sh 'lisp -batch -noinit'
c05927a @nikodemus 0.8.10.61:
nikodemus authored
124
125 The build may take a long time, especially on older hardware. A
126 successful build ends with a message beginning: "The build seems to
127 have finished successfully...".
128
129 To run the regression tests:
130
131 $ cd tests && sh run-tests.sh
132
133 To build documentation:
134
135 $ cd doc/manual && make
136
137 This builds the Info, HTML and PDF documentation from the Texinfo
138 sources. The manual includes documentation string from the build
139 SBCL, but if SBCL itself has not been yet built, but one if found
140 installed documentation strings from the installed version are used.
141
142 Now you should have the same src/runtime/sbcl and output/sbcl.core
143 files that come with the binary distribution, and you can install
144 them as described in the section 1. "BINARY DISTRIBUTION".
145
146 2.2. Customizing SBCL
147
148 You can tweak the *FEATURES* set for the resulting Lisp system,
149 enabling or disabling features like documentation strings, threads,
150 or extra debugging code.
151
152 The preferred way to do this is by creating a file
5580e3e @nikodemus 0.8.10.78:
nikodemus authored
153 "customize-target-features.lisp", containing a lambda expression
154 which is applied to the default *FEATURES* set and which returns the
155 new *FEATURES* set, e.g.
c05927a @nikodemus 0.8.10.61:
nikodemus authored
156
157 (lambda (features)
158 (flet ((enable (x)
159 (pushnew x features))
160 (disable (x)
161 (setf features (remove x features))))
1baab0b @nikodemus 1.0.33.26: enabled threads by default on x86[-64] Linux
nikodemus authored
162 ;; Threading support.
b03ad9b @jsnell 0.9.3.74:
jsnell authored
163 (enable :sb-thread)))
c05927a @nikodemus 0.8.10.61:
nikodemus authored
164
165 This is the preferred way because it lets local changes interact
166 cleanly with CVS changes to the main, global source tree.
167
1baab0b @nikodemus 1.0.33.26: enabled threads by default on x86[-64] Linux
nikodemus authored
168 Some features of interest:
169
170 :SB-THREAD
171 Native threads. Enabled by default on x86[-64] Linux only, also
172 available on x86[-64] Max OS X, x86[-64] FreeBSD, and x86
173 Solaris.
174
175 :SB-UNICODE
176 Unicode support. Enabled by default. Disabling this feature
177 limits characters to the 8-bit ISO-8859-1 set.
178
179 :SB-XREF-FOR-INTERNALS
180 XREF data for SBCL internals. Not enabled by default, increases
181 core size by 5-6mb.
182
c05927a @nikodemus 0.8.10.61:
nikodemus authored
183 A catalog of available features and their meaning can be found in
184 "base-target-features.lisp-expr".
185
186 2.3. Troubleshooting
187
188 "GNU Make not found"
189
190 If the GNU make command is not available under the names "make",
191 "gmake", or "gnumake", then define the environment variable
192 GNUMAKE to a name where it can be found.
193
194 Segfaults on Fedora
195
196 Try disabling exec-shield. The easiest way is to use
b03ad9b @jsnell 0.9.3.74:
jsnell authored
197 setarch: "setarch i386 -R sbcl".
c05927a @nikodemus 0.8.10.61:
nikodemus authored
198
199 Build crashes mysteriously, machine becomes unstable, etc
200
201 You may be running out of memory. Try increasing swap, or
202 building SBCL with fewer other programs running simultaneously.
203
204 Other
205
4ac05a1 0.9.3.43:
Nathan Froyd authored
206 * Check that the host lisp you're building with is known to work as
207 an SBCL build host, and that your operating system is supported.
72bd7d1 1.0.27.49: update platform table, credit me
Gabor Melis authored
208
eaa8a50 @jsnell 0.9.0.37:
jsnell authored
209 * Try to do a build without loading any initialization files
210 for the cross-compilation host (for example
211 "sh make.sh 'sbcl --userinit /dev/null --sysinit /dev/null'").
c05927a @nikodemus 0.8.10.61:
nikodemus authored
212
213 * Some GCC versions are known to have bugs that affect SBCL
214 compilation: if the error you're encountering seems related to
215 files under "src/runtime", down- or upgrading GCC may help.
216
217 * Ask for help on the mailing lists referenced from
218 <http://www.sbcl.org/>.
219
220 2.4. Tracking SBCL sources
221
222 If you want to be on the bleeding edge, you can update your sources
223 to the latest development snapshot (or any previous development
224 snapshot, for that matter) by using anonymous CVS to
225 SourceForge. (This is not recommended if you're just using SBCL as a
226 tool for other work, but if you're interested in working on SBCL
227 itself, it's a good idea.) Follow the "CVS Repository" link on
228 <http://sourceforge.net/projects/sbcl> for instructions.
229
72bd7d1 1.0.27.49: update platform table, credit me
Gabor Melis authored
230 2.5. Supported platforms
c05927a @nikodemus 0.8.10.61:
nikodemus authored
231
b03ad9b @jsnell 0.9.3.74:
jsnell authored
232 Last updated for SBCL 0.9.3.74 (2005-08-20).
c05927a @nikodemus 0.8.10.61:
nikodemus authored
233
234 All of the following platforms are supported in the sense of "should
235 work", but some things like loading foreign object files may lag
4ac05a1 0.9.3.43:
Nathan Froyd authored
236 behind on less-used operating systems.
c05927a @nikodemus 0.8.10.61:
nikodemus authored
237
238 Supported toolchains:
239
240 GNU toolchain
241 Sun toolchain with GCC
242
243 Supported build hosts are:
244
245 SBCL
246 CMUCL
72bd7d1 1.0.27.49: update platform table, credit me
Gabor Melis authored
247 CCL (formerly known as OpenMCL)
ad3beba 0.9.2.38: thread cleanup, paranoid
Gabor Melis authored
248 ABCL (recent versions only)
2b8c64a @csrhodes 1.0.28: release, will be tagged as sbcl_1_0_28
csrhodes authored
249 CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
250 XCL
251
c05927a @nikodemus 0.8.10.61:
nikodemus authored
252
253 Note that every release isn't tested with every possible host
254 compiler. You're most likely to get a clean build with SBCL itself
72bd7d1 1.0.27.49: update platform table, credit me
Gabor Melis authored
255 as host, otherwise CCL on a PPC and CMUCL elsewhere.
c05927a @nikodemus 0.8.10.61:
nikodemus authored
256
257 Supported operating systems and architectures:
258
72bd7d1 1.0.27.49: update platform table, credit me
Gabor Melis authored
259 x86 x86-64 PPC Sparc Alpha MIPS MIPSel
1baab0b @nikodemus 1.0.33.26: enabled threads by default on x86[-64] Linux
nikodemus authored
260 Linux 2.6 X X X X X X X
72bd7d1 1.0.27.49: update platform table, credit me
Gabor Melis authored
261 Darwin (Mac OS X) X X X
262 Solaris X X
263 FreeBSD X X
264 NetBSD X X
78cf750 @nikodemus 0.8.10.81:
nikodemus authored
265 OpenBSD 3.4, 3.5 X
54b3305 @jsnell 0.9.16.17:
jsnell authored
266 Windows X
c05927a @nikodemus 0.8.10.61:
nikodemus authored
267
b6094d5 0.9.3.58:
Nathan Froyd authored
268 Some operating systems are more equal than others: most of the
54b3305 @jsnell 0.9.16.17:
jsnell authored
269 development and testing is done on x86/x86-64 Linux and x86/PPC
270 Mac OS X.
c05927a @nikodemus 0.8.10.61:
nikodemus authored
271
272 If an underprivileged platform is important to you, you can help
b6094d5 0.9.3.58:
Nathan Froyd authored
273 by e.g. testing during the monthly freeze periods, and most
c05927a @nikodemus 0.8.10.61:
nikodemus authored
274 importantly by reporting any problems.
275
fd79e33 @nikodemus 1.0.29.1: fix FILL
nikodemus authored
276 For further support, see Getting Support and Reporting Bugs
277 in the manual, or
278
279 http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
280
281 if you do not have the manual for some reason.
Something went wrong with that request. Please try again.