1 IF YOU HAVE A BINARY DISTRIBUTION:
3 The two files that SBCL needs to run are sbcl and sbcl.core.
9 sbcl is a standard executable, built by compiling and linking an
10 ordinary C program. It provides the runtime environment for the
11 running Lisp image, but it doesn't know much about high-level Lisp
12 stuff (like symbols and printing and objects) so it's pretty useless
13 by itself. sbcl.core is a dump file written in a special SBCL format
14 which only sbcl understands, and it contains all the high-level Lisp
17 In order to get a usable system, you need to run sbcl in a way that
18 it can find sbcl.core. There are three ways for it to find
20 1. by default, in /usr/lib/sbcl.core or /usr/local/lib/sbcl.core
21 2. by environment variable:
22 $ export SBCL_HOME=/foo/bar/
24 3. by command line option:
25 $ sbcl --core /foo/bar/sbcl.core"
26 The usual, recommended approach is method #1. Method #2 is useful if
27 you're installing SBCL on a system in your user account, instead of
28 installing SBCL on an entire system. Method #3 is mostly useful for
29 testing or other special cases.
31 So: the standard installation procedure is
32 1. Copy sbcl.core to /usr/lib or /usr/local/lib.
33 2. Copy sbcl to /usr/bin or /usr/local/bin.
34 3. Optionally copy sbcl.1 to /usr/man/man1 or /usr/local/man/man1.
35 The script install.sh does these for you (choosing the /usr/local
36 subdirectory) in each case.
39 IF YOU HAVE A SOURCE DISTRIBUTION:
41 This software has been built successfully on these systems:
42 cpu = x86 (Intel 386 or higher, or compatibles like the AMD K6)
43 os = Debian GNU/Linux 2.1 with libc >= 2.1
44 host lisp = CMU CL 2.4.17
45 host lisp = SBCL itself
47 host lisp = SBCL itself
48 os = FreeBSD 3.4 or 4.0
50 host lisp = SBCL itself
52 host lisp = SBCL itself
53 It is known not to build under CLISP, because CLISP doesn't support
54 MAKE-LOAD-FORM. Reports of other systems that it works on, or help in
55 making it run on more systems, would be appreciated.
57 CAUTION CAUTION CAUTION CAUTION CAUTION
58 SBCL, like CMU CL, overcommits memory. That is, it
59 asks the OS for more virtual memory address space than
60 it actually intends to use, and the OS is expected to
61 optimistically give it this address space even if the OS
62 doesn't have enough RAM+swap to back it up. This works
63 fine as long as SBCL's memory usage pattern is sparse
64 enough that the OS can actually implement the requested
65 VM usage. Unfortunately, if the OS runs out of RAM+swap to
66 implement the requested VM usage, things get bad. On many
67 systems, including the Linux 2.2.13 kernel that I used for
68 development of SBCL up to version 0.6.0, the kernel kills
69 processes more-or-less randomly when it runs out of
70 resources. You may think your Linux box is very stable, but
71 it is unlikely to be stable if this happens.:-| So be sure
72 to have enough memory available when you build the system.
73 (This can be considered a bug in SBCL, or a bug in the
74 Unix overcommitment-of-memory architecture, or both. It's
75 not clear what the best fix is. On the SBCL side, Peter Van
76 Eynde has a lazy-allocation patch for CMU CL that lets
77 it run without overcommitting memory, and that could be
78 ported to SBCL, but unfortunately that might introduce
79 new issues, e.g. alien programs allocating memory in the
80 address space that SBCL thinks of as its own, and later
81 getting trashed when SBCL lazily allocates the memory.
82 On the OS side, there might be some way to address the
83 problem with quotas, I don't know.)
85 To build the system binaries:
86 0. If you want to be on the bleeding edge, you can update your
87 sources to the latest development snapshot (or any previous
88 development snapshot, for that matter) by using anonymous CVS
89 to SourceForge. (This is not recommended if you're just using SBCL
90 as a tool for other work, but if you're interested in working on
91 SBCL itself, it's a good idea.) Follow the "CVS Repository" link on
92 <http://sourceforge.net/projects/sbcl> for instructions.
93 1. Make sure that you have enough RAM+swap to build SBCL, as
94 per the CAUTION note above. (As of version 0.6.0, the most
95 memory-intensive operation in make.sh is the second call to
96 GENESIS, which makes the Lisp image grow to nearly 128 Mb RAM+swap.
97 This will probably be reduced somewhat in some later version
98 by allowing cold load of byte-compiled files, so that the cold
99 image can be smaller.)
100 2. If the GNU make command is not available under the name "gmake",
101 then define the environment variable GNUMAKE to a name where it can
103 3. If you like, you can edit the base-target-features.lisp-expr file
104 to customize the resulting Lisp system. By enabling or disabling
105 features in this file, you can create a smaller system, or one
106 with extra code for debugging output or error-checking or other things.
107 4. Run "sh make.sh" in the same directory where you unpacked the
108 tarball. If you don't already have a SBCL binary installed
109 as "sbcl" in your path, you'll need to tell make.sh what Lisp
110 system to use as the cross-compilation host. (To use CMU CL
111 as the cross-compilation host, run "sh make.sh 'lisp -batch'",
112 assuming CMU CL has been installed under its default name "lisp".)
113 5. Wait. This can be a slow process. On my test machines, the
114 wall clock time for a build of sbcl-0.6.7 was approximately
115 1.5 hours on a 450MHz K6/3 with 248Mb RAM, running RH Linux 6.2;
116 4 hours on a 200MHz Pentium (P54C) with 64Mb RAM, running FreeBSD 4.0;
117 13 hours on a 133MHz Pentium (P54C) with 48Mb RAM, running OpenBSD 2.6.
118 Around the 48Mb mark, the build process is starved for RAM:
119 on my 48Mb OpenBSD machine with nothing else running, it
120 spent about 2/3 of its wall clock time swapping. Anything which
121 substantially increases memory use, like running X11, Emacs, or,
122 God forbid, Netscape, can increase the build time substantially.
124 Now you should have the same src/runtime/sbcl and output/sbcl.core
125 files that come with the binary distribution, and you can install
126 them as in the "IF YOU HAVE A BINARY DISTRIBUTION" instructions (above).
128 To convert the DocBook version of the system documentation (files
129 ending in .sgml) to more-readable form (HTML or text):
130 DocBook is an abstract markup system based on SGML. It's intended
131 to be automatically translated to other formats. Tools to do this
132 exist on the web, and are becoming increasingly easy to find as
133 more free software projects move their documentation to DocBook.
134 Any one of these systems should work with the SBCL documentation.
135 If you'd like to have the documentation produced in the same
136 format as appears in the binary distribution, and you have
137 the jade binary and Norman Walsh's modular DSSSL stylesheets
138 installed, you can try the doc/make-doc.sh script. Otherwise,
139 your formatted copy of the SBCL documentation should have the
140 same content as in the binary distribution, but details of
141 presentation will probably vary.