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