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