INSTALL

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