INSTALLING SBCL

  CONTENTS

    1. BINARY DISTRIBUTION
    1.1. Quick start
    1.2. Anatomy of SBCL
    1.3. Finding ancillary files

    2. SOURCE DISTRIBUTION
    2.1. Quick start
    2.2. Customizing SBCL
    2.3. Troubleshooting
    2.4. Tracking SBCL sources
    2.5. Supported platforms


1. BINARY DISTRIBUTION

1.1. Quick start:

  To run SBCL without installing it, from the top of binary distribution
  directory:

    $ sh run-sbcl.sh

  The following command installs SBCL and related documentation under
  the "/usr/local" directory (typically run as root):

    # INSTALL_ROOT=/usr/local sh install.sh

  You can also install SBCL as a user, under your home directory:

    $ INSTALL_ROOT=/home/me sh install.sh

  That is, "install.sh" installs SBCL under the directory named by the
  environment variable INSTALL_ROOT.

  If INSTALL_ROOT is not specified, SBCL is installed into location
  configured at build-time: for official binary distributions under
  "/usr/local" directory.

1.2. Anatomy of SBCL

  The two files that SBCL needs to run, at minimum, are

    src/runtime/sbcl
    output/sbcl.core

  In addition, there are a number of modules that extend the basic
  SBCL functionality, in

    contrib/

  The "src/runtime/sbcl" file is a standard executable, built by
  compiling and linking an ordinary C program. It provides the runtime
  environment for the running Lisp image, but it doesn't know much
  about high-level Lisp stuff (like symbols and printing and objects)
  so it's pretty useless by itself. The "output/sbcl.core" file is a
  dump file written in a special SBCL format that only SBCL
  understands, and it contains all the high-level Lisp stuff.

  The standard installation procedure, outlined in section 1.1 "Quick
  start", is to run "install.sh", which copies all the files to right
  places, including documentation and contrib modules that have passed
  their tests. If you need to install by hand, see "install.sh" for
  details.

  Documentation consists of a man page, the SBCL Manual (in info, pdf
  and html formats), and a few additional text files.

1.3. Finding ancillary files

  The SBCL runtime needs to be able to find the ancillary files
  associated with it: the "sbcl.core" file, and the contrib modules.

  Finding sbcl.core can happen in the following ways:

    If the --core runtime option is specified, then its value is used.
    Example:

        $ sbcl --core /foo/bar/sbcl.core

    Else, the runtime looks for sbcl.core in the following directories
    until the first match.

    - The directory denoted by the SBCL_HOME environment variable if
      it is set

    - The current directory

    - The directory of the sbcl binary

    - The ../lib/sbcl/ directory relative to the sbcl binary

  Finding the contrib/ directory:

  Once the runtime loads the core file, the Lisp looks for contrib/ in
  the following directories until the first match.

  - The directory denoted by the SBCL_HOME environment variable if
    it is set

  - The directory of sbcl.core

  - The directory ../lib/sbcl relative to sbcl.core

  - The current directory

  - The directory of the sbcl binary

  - The directory ../lib/sbcl relative to the sbcl binary

  The list of directories is the same as for finding the core file
  except here we also try directories relative to sbcl.core.


2. SOURCE DISTRIBUTION

2.1. Quick start

  To build SBCL you need a working toolchain and a Common Lisp system
  (see section 2.5 "Supported platforms"). You also need approximately
  128 Mb of free RAM+swap.

  To build SBCL using an already installed SBCL:

    $ sh make.sh

  To configure SBCL to install to a non-standard location, you can use
  the --prefix option:

    $ sh make.sh --prefix=/opt/mysbcl

  To configure SBCL with a non-standard default dynamic-space size,
  use the --dynamic-space-size option:

    $ sh make.sh --dynamic-space-size=4Gb
    $ sh make.sh --dynamic-space-size=800Mb

  If mega- or gigabytes are not specified, the number is taken to be
  in megabytes. The standard default is 512Mb for 32-bit systems, and
  1Gb for 64-bit systems (with the exception of OpenBSD where 444Mb
  are used to fit under default ulimits.)

  If you don't already have an SBCL binary installed as "sbcl" on your
  system, you'll need to tell make.sh what Lisp to use as the
  cross-compilation host (cf. make.sh for detailed instructions on
  how to cross compile). For example, to use CMUCL (assuming it has
  been installed under its default name "lisp") as the
  cross-compilation host:

    $ sh make.sh --xc-host='lisp -batch -noinit'

  The build may take a long time, especially on older hardware. A
  successful build ends with a message beginning: "The build seems to
  have finished successfully...".

  To run the regression tests:

    $ cd ./tests && sh run-tests.sh

  To build documentation:

    $ cd ./doc/manual && make

  This builds the Info, HTML and PDF documentation from the SB-MANUAL
  contrib. The manual includes documentation strings from the built
  SBCL. If SBCL itself has not been built yet, but an installed one is
  found, documentation strings from the installed version are used.

  Now you should have the same src/runtime/sbcl and output/sbcl.core
  files that come with the binary distribution, and you can install
  them as described in the section 1. "BINARY DISTRIBUTION".

2.2. Customizing SBCL

  You can tweak the *FEATURES* set for the resulting Lisp system,
  enabling or disabling features like documentation strings, threads,
  or extra debugging code.

  The preferred way to do this is using commandline arguments to make.sh:

    --fancy                    Enables a curated set of features.
    --with-<feature>           Enables a specific feature.
    --without-<feature>        Disables a specific feature.

  Some features of interest:

    :SB-THREAD (--with-sb-thread, --without-sb-thread)

      Native threads. Enabled by default on x86[-64] Linux only, also
      available on x86[-64] Max OS X, x86[-64] FreeBSD, x86 Solaris,
      and PPC Linux.

      NOTE: --fancy enables threads on all platforms where they can be
      built, even if they aren't 100% stable on that platform.

    :SB-CORE-COMPRESSION (--with-sb-core-compression)

      Adds zstd as a build-dependency, and makes SBCL able to save
      compressed cores. Not enabled by default.

    :SB-XREF-FOR-INTERNALS (--with-sb-xref-for-internals)

      XREF data for SBCL internals. Not enabled by default, increases
      core size by 5-6mb.

    :SB-UNICODE (--without-sb-unicode)

      Unicode support. Enabled by default. Disabling this feature
      limits characters to the 8-bit ISO-8859-1 set.

  A catalog of available features and their meaning can be found in
  "src/cold/base-target-features.lisp-expr".

  Please do NOT edit base-target-features.lisp-expr in order to enable
  or disable build features.

2.3. Troubleshooting

  "GNU Make not found"

    If the GNU make command is not available under the names "make",
    "gmake", or "gnumake", then define the environment variable
    GNUMAKE to a name where it can be found.

  Segfaults on Linux with ASLR

    If SBCL segfaults immediately upon startup due to Address Space
    Layout Randomization (ASLR), you can bypass it by executing the
    host compiler binary via setarch:

    setarch x86_64 -R sbcl

    See also :ASLR in build option.

  Build crashes mysteriously, machine becomes unstable, etc

    You may be running out of memory. Try increasing swap, or
    building SBCL with fewer other programs running simultaneously.

  Other

    * Check that the host lisp you're building with is known to work as
      an SBCL build host, and that your operating system is supported.

    * Try to do a build without loading any initialization files
      for the cross-compilation host (for example
      "sh make.sh 'sbcl --userinit /dev/null --sysinit /dev/null'").

    * Some GCC versions are known to have bugs that affect SBCL
      compilation: if the error you're encountering seems related to
      files under "src/runtime", down- or upgrading GCC may help.

    * Ask for help on the mailing lists referenced from
      <https://www.sbcl.org/>.

2.4. Tracking SBCL sources

  If you want to be on the bleeding edge, you can update your sources
  to the latest development snapshot (or any previous development
  snapshot, for that matter) by using anonymous GIT to SourceForge.
  (This is not recommended if you're just using SBCL as a tool for
  other work, but if you're interested in working on SBCL itself, it's
  a good idea.) See
  <http://sourceforge.net/projects/sbcl/ci/master/tree> for
  instructions.

  Alternatively, use the official GitHub mirror at
  <https://github.com/sbcl/sbcl>.

2.5. Supported platforms

  All of the following platforms are supported in the sense of "should
  work", but some things like loading foreign object files may lag
  behind on less-used operating systems.

  Supported toolchains:

    GNU toolchain
    Sun toolchain with GCC

  SBCL can be compiled from source code using another ANSI-compliant
  Common Lisp implementation such as

    SBCL
    CMUCL
    CCL (formerly known as OpenMCL)
    CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
    ECL
    XCL
    ABCL (recent versions only, very slow)

    Note that not every release is tested with every possible host
    compiler. You're most likely to get a clean build with SBCL itself
    as host, otherwise CCL on a PPC and CMUCL elsewhere.

    See <https://sbcl.org/platform-table.html> for the list of
    supported operating systems and architectures.

    Some operating systems are more equal than others: most of the
    development and testing is done on x86-64 Linux and x86-64/arm64
    Mac OS X.

    If an underprivileged platform is important to you, you can help
    by e.g. testing during the monthly freeze periods, and most
    importantly by reporting any problems.

    For further support, see "Getting Support and Reporting Bugs"
    (SB-MANUAL:@SUPPORT-AND-BUGS) in the manual locally or at

      https://www.sbcl.org/manual/#Getting-Support-and-Reporting-Bugs
