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   To run SBCL without installing it, from the top of binary distribution
  23   directory:
  24
  25     $ sh run-sbcl.sh
  26
  27   The following command installs SBCL and related documentation under
  28   the "/usr/local" directory (typically run as root):
  29
  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
  39   If you install SBCL from binary distribution in other location than
  40   "/usr/local", see section 1.2, "Finding ancillary files".
  41
  42 1.2. Finding ancillary files
  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
  47   Finding core can happen in three ways:
  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
  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
  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
 102   Documentation consists of a man-page, the SBCL Manual (in info, pdf
 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
 119   cross-compilation host. For example, to use CMUCL (assuming has
 120   been installed under its default name "lisp") as the
 121   cross-compilation host:
 122
 123     $ sh make.sh 'lisp -batch -noinit'
 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
 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.
 156
 157     (lambda (features)
 158       (flet ((enable (x)
 159                (pushnew x features))
 160              (disable (x)
 161                (setf features (remove x features))))
 162         ;; Threading support.
 163         (enable :sb-thread)))
 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
 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, x86 Solaris,
 173       and PPC Linux.
 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
 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
 197     setarch: "setarch i386 -R sbcl".
 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
 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.
 208
 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'").
 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
 230 2.5. Supported platforms
 231
 232   Last updated for SBCL 0.9.3.74 (2005-08-20).
 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
 236   behind on less-used operating systems.
 237
 238   Supported toolchains:
 239
 240     GNU toolchain
 241     Sun toolchain with GCC
 242
 243   Supported build hosts are:
 244
 245     SBCL
 246     CMUCL
 247     CCL (formerly known as OpenMCL)
 248     ABCL (recent versions only)
 249     CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
 250     XCL
 251
 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
 255     as host, otherwise CCL on a PPC and CMUCL elsewhere.
 256
 257   Supported operating systems and architectures:
 258
 259                            x86 x86-64 PPC Sparc Alpha MIPS MIPSel
 260     Linux 2.6               X     X    X    X     X     X     X
 261     Darwin (Mac OS X)       X     X    X
 262     Solaris                 X               X
 263     FreeBSD                 X     X
 264     NetBSD                  X          X
 265     OpenBSD 3.4, 3.5        X
 266     Windows                 X
 267
 268     Some operating systems are more equal than others: most of the
 269     development and testing is done on x86/x86-64 Linux and x86/PPC
 270     Mac OS X.
 271
 272     If an underprivileged platform is important to you, you can help
 273     by e.g. testing during the monthly freeze periods, and most
 274     importantly by reporting any problems.
 275
 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.