INSTALL

   1 IF YOU HAVE A BINARY DISTRIBUTION:
   2
   3 The two files that SBCL needs to run are sbcl and sbcl.core.
   4 They are in
   5         src/runtime/sbcl
   6 and
   7         output/sbcl.core
   8
   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.
  16
  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:
  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/
  23      $ sbcl
  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.
  30
  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.
  37
  38
  39 IF YOU HAVE A SOURCE DISTRIBUTION:
  40
  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
  46                 os = RedHat Linux 6.2
  47                         host lisp = SBCL itself
  48                 os = FreeBSD 3.4 or 4.0
  49                         host lisp = CMU CL
  50                         host lisp = SBCL itself
  51                 os = OpenBSD 2.6
  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.
  56
  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.)
  84
  85 To build the system binaries:
  86   1. Make sure that you have enough RAM+swap to build SBCL, as
  87      per the CAUTION note above. (As of version 0.6.0, the most
  88      memory-intensive operation in make.sh is the second call to
  89      GENESIS, which makes the Lisp image grow to nearly 128 Mb RAM+swap.
  90      This will probably be reduced somewhat in some later version
  91      by allowing cold load of byte-compiled files, so that the cold
  92      image can be smaller.)
  93   2. If the GNU make command is not available under the name "gmake",
  94      then define the environment variable GNUMAKE to a name where it can
  95      be found.
  96   3. If you like, you can edit the base-features.lisp-expr file
  97      to customize the resulting Lisp system. By enabling or disabling
  98      features in this file, you can create a smaller system, or one
  99      with extra code for debugging output or error-checking or other things.
 100   4. Run "sh make.sh" in the same directory where you unpacked the
 101      tarball. If you don't already have a SBCL binary installed
 102      as "sbcl" in your path, you'll need to tell make.sh what Lisp
 103      system to use as the cross-compilation host. (To use CMU CL
 104      as the cross-compilation host, run "sh make.sh 'lisp -batch'",
 105      assuming CMU CL has been installed under its default name "lisp".)
 106   5. Wait. This can be a slow process. On my test machines, the
 107      wall clock time for a build of sbcl-0.6.7 was approximately
 108        1.5 hours on a 450MHz K6/3 with 248Mb RAM, running RH Linux 6.2;
 109        4 hours on a 200MHz Pentium (P54C) with 64Mb RAM, running FreeBSD 4.0;
 110        13 hours on a 133MHz Pentium (P54C) with 48Mb RAM, running OpenBSD 2.6.
 111      Around the 48Mb mark, the build process is starved for RAM:
 112      on my 48Mb OpenBSD machine with nothing else running, it
 113      spent about 2/3 of its wall clock time swapping. Anything which
 114      substantially increases memory use, like running X11, Emacs, or,
 115      God forbid, Netscape, can increase the build time substantially.
 116
 117 Now you should have the same src/runtime/sbcl and output/sbcl.core
 118 files that come with the binary distribution, and you can install
 119 them as in the "IF YOU HAVE A BINARY DISTRIBUTION" instructions (above).
 120
 121 To convert the DocBook version of the system documentation (files
 122 ending in .sgml) to more-readable form (HTML or text):
 123   DocBook is an abstract markup system based on SGML. It's intended
 124   to be automatically translated to other formats. Tools to do this
 125   exist on the web, and are becoming increasingly easy to find as
 126   more free software projects move their documentation to DocBook.
 127   Any one of these systems should work with the SBCL documentation.
 128   If you'd like to have the documentation produced in the same
 129   format as appears in the binary distribution, and you have
 130   the jade binary and Norman Walsh's modular DSSSL stylesheets
 131   installed, you can try the doc/make-doc.sh script. Otherwise,
 132   your formatted copy of the SBCL documentation should have the
 133   same content as in the binary distribution, but details of
 134   presentation will probably vary.