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