-IF YOU HAVE A BINARY DISTRIBUTION:
-
-The two files that SBCL needs to run are sbcl and sbcl.core.
-They are in
- src/runtime/sbcl
-and
- output/sbcl.core
-
-sbcl 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. sbcl.core is a dump file written in a special SBCL format
-which only sbcl understands, and it contains all the high-level Lisp
-stuff.
-
-In order to get a usable system, you need to run sbcl in a way that
-it can find sbcl.core. There are three ways for it to find
-sbcl.core:
- 1. by default, in /usr/lib/sbcl.core or /usr/local/lib/sbcl.core
- 2. by environment variable:
- $ export SBCL_HOME=/foo/bar/
- $ sbcl
- 3. by command line option:
- $ sbcl --core /foo/bar/sbcl.core"
-The usual, recommended approach is method #1. Method #2 is useful if
-you're installing SBCL on a system in your user account, instead of
-installing SBCL on an entire system. Method #3 is mostly useful for
-testing or other special cases.
-
-So: the standard installation procedure is
- 1. Copy sbcl.core to /usr/lib or /usr/local/lib.
- 2. Copy sbcl to /usr/bin or /usr/local/bin.
- 3. Optionally copy sbcl.1 to /usr/man/man1 or /usr/local/man/man1.
-The script install.sh does these for you (choosing the /usr/local
-subdirectory) in each case.
-
-
-IF YOU HAVE A SOURCE DISTRIBUTION:
-
-This software has been built successfully on these systems:
- cpu = x86 (Intel 386 or higher, or compatibles like the AMD K6)
- os = Debian GNU/Linux 2.1 with libc >= 2.1
- host lisp = CMU CL 2.4.17
- host lisp = SBCL itself
- os = RedHat Linux 6.2
- host lisp = SBCL itself
- os = FreeBSD 3.4 or 4.0
- host lisp = CMU CL
- host lisp = SBCL itself
- os = OpenBSD 2.6, 2.7, 2.8, 2.9, and 3.0
- host lisp = SBCL itself
- cpu = sparc
- os = Debian GNU/Linux 2.2 with libc >= 2.2
- host lisp = SBCL itself
- os = Solaris 8
- host lisp = SBCL itself
- cpu = powerpc
- os = Debian GNU/Linux 2.2 with libc >= 2.1
- host lisp = OpenMCL 0.12
- host lisp = SBCL itself
-
-It is known not to build under CLISP because of (as of early June 2002)
-bugs in the CLISP garbage collector.
-
-Reports of other systems that it works on (or doesn't work on, for
-that matter), or help in making it run on more systems, would be
-appreciated.
-
- CAUTION CAUTION CAUTION CAUTION CAUTION
- SBCL, like CMU CL, overcommits memory. That is, it
- asks the OS for more virtual memory address space than
- it actually intends to use, and the OS is expected to
- optimistically give it this address space even if the OS
- doesn't have enough RAM+swap to back it up. This works
- fine as long as SBCL's memory usage pattern is sparse
- enough that the OS can actually implement the requested
- VM usage. Unfortunately, if the OS runs out of RAM+swap to
- implement the requested VM usage, things get bad. On many
- systems, including the Linux 2.2.13 kernel that I used for
- development of SBCL up to version 0.6.0, the kernel kills
- processes more-or-less randomly when it runs out of
- resources. You may think your Linux box is very stable, but
- it is unlikely to be stable if this happens.:-| So be sure
- to have enough memory available when you build the system.
- (This can be considered a bug in SBCL, or a bug in the
- Unix overcommitment-of-memory architecture, or both. It's
- not clear what the best fix is. On the SBCL side, Peter Van
- Eynde has a lazy-allocation patch for CMU CL that lets
- it run without overcommitting memory, and that could be
- ported to SBCL, but unfortunately that might introduce
- new issues, e.g. alien programs allocating memory in the
- address space that SBCL thinks of as its own, and later
- getting trashed when SBCL lazily allocates the memory.
- On the OS side, there might be some way to address the
- problem with quotas, I don't know.)
-
-To build the system binaries:
- 0. 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 CVS
- 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.) Follow the "CVS Repository" link on
- <http://sourceforge.net/projects/sbcl> for instructions.
- 1. Make sure that you have enough RAM+swap to build SBCL, as
- per the CAUTION note above. (As of version 0.6.0, the most
- memory-intensive operation in make.sh is the second call to
- GENESIS, which makes the Lisp image grow to nearly 128 Mb RAM+swap.
- 2. If the GNU make command is not available under the name "gmake",
- then define the environment variable GNUMAKE to a name where it can
- be found.
- 3. If you like, you can tweak the *FEATURES* set for the resulting
- Lisp system, enabling or disabling features like documentation
- strings or extra debugging code. The preferred way to do this is
- by creating a file "customize-target-features.lisp", containing
- a lambda expression which is applied to the default *FEATURES*
- set and which returns the new *FEATURES* set, e.g.
- (LAMBDA (LIST)
- (ADJOIN :SB-SHOW
- (REMOVE :SB-DOC
- LIST)))
- (This is the preferred way because it lets local changes interact
- cleanly with CVS changes to the main, global source tree.)
- 4. Run "sh make.sh" in the same directory where you unpacked the
- tarball. If you don't already have a SBCL binary installed
- as "sbcl" in your path, you'll need to tell make.sh what Lisp
- system to use as the cross-compilation host. (To use CMU CL
- as the cross-compilation host, run "sh make.sh 'lisp -batch'",
- assuming CMU CL has been installed under its default name "lisp".)
- 5. Wait. This can be a slow process. On my test machines, the
- wall clock time for a build of sbcl-0.6.7 was approximately
- 1.5 hours on a 450MHz K6/3 with 248Mb RAM, running RH Linux 6.2;
- 4 hours on a 200MHz Pentium (P54C) with 64Mb RAM, running FreeBSD 4.0;
- 13 hours on a 133MHz Pentium (P54C) with 48Mb RAM, running OpenBSD 2.6.
- Around the 48Mb mark, the build process is starved for RAM:
- on my 48Mb OpenBSD machine with nothing else running, it
- spent about 2/3 of its wall clock time swapping. Anything which
- substantially increases memory use, like running X11, Emacs, or,
- God forbid, Netscape, can increase the build time substantially.
-
-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 in the "IF YOU HAVE A BINARY DISTRIBUTION" instructions (above).
-
-To convert the DocBook version of the system documentation (files
-ending in .sgml) to more-readable form (HTML or text):
- DocBook is an abstract markup system based on SGML. It's intended
- to be automatically translated to other formats. Tools to do this
- exist on the web, and are becoming increasingly easy to find as
- more free software projects move their documentation to DocBook.
- Any one of these systems should work with the SBCL documentation.
- If you'd like to have the documentation produced in the same
- format as appears in the binary distribution, and you have
- the jade binary and Norman Walsh's modular DSSSL stylesheets
- installed, you can try the doc/make-doc.sh script. Otherwise,
- your formatted copy of the SBCL documentation should have the
- same content as in the binary distribution, but details of
- presentation will probably vary.
+INSTALLING SBCL
+
+ CONTENTS
+
+ 1. BINARY DISTRIBUTION
+ 1.1. Quick start
+ 1.2. Finding ancillary files
+ 1.3. Anatomy of SBCL
+
+ 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
+
+ In other words, "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.
+
+ If you install SBCL from binary distribution in other location than
+ "/usr/local", see section 1.2, "Finding ancillary files".
+
+1.2. 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 core can happen in three ways:
+
+ 1. By default, in a location configured when the system was built.
+ For binary distributions this is in "/usr/local/lib/sbcl".
+
+ 2. By environment variable, in the directory named by the
+ environment variable "SBCL_HOME". Example:
+
+ $ export SBCL_HOME=/foo/bar/lib/sbcl
+ $ sbcl
+
+ If your "INSTALL_ROOT" was FOO, then your "SBCL_HOME" is
+ "FOO/lib/sbcl".
+
+ 3. By command line option:
+
+ $ sbcl --core /foo/bar/sbcl.core
+
+ The usual, recommended approach is method #1. Method #2 is useful if
+ you're installing SBCL on a system in a non-standard location
+ (e.g. in your user account), instead of installing SBCL on an entire
+ system. Method #3 is mostly useful for testing or other special
+ cases.
+
+ Contributed modules are primarily looked for in "SBCL_HOME", or the
+ directory the core resides in if "SBCL_HOME" is not set.
+ ASDF:*CENTRAL-REGISTRY* serves as an additional fallback for
+ ASDF-based modules.
+
+1.3. 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" 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" is a dump
+ file written in a special SBCL format which 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 the "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.
+
+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
+
+ This also sets the default SBCL_HOME to prefix/lib/sbcl/ for the
+ built binaries.
+
+ 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. For example, to use CMUCL (assuming 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 Texinfo
+ sources. The manual includes documentation string from the build
+ SBCL, but if SBCL itself has not been yet built, but one if found
+ installed 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 all supported feature enhancements.
+ --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 zlib 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
+ "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 Fedora
+
+ Try disabling exec-shield. The easiest way is to use
+ setarch: "setarch i386 -R sbcl".
+
+ 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
+ <http://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 CVS 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.) Follow the "CVS Repository" link on
+ <http://sourceforge.net/projects/sbcl> for instructions.
+
+2.5. Supported platforms
+
+ Last updated for SBCL 0.9.3.74 (2005-08-20).
+
+ 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
+
+ Supported build hosts are:
+
+ SBCL
+ CMUCL
+ CCL (formerly known as OpenMCL)
+ ABCL (recent versions only)
+ CLISP (only some versions: 2.44.1 is OK, 2.47 is not)
+ XCL
+
+
+ Note that every release isn't 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.
+
+ Supported operating systems and architectures:
+
+ x86 x86-64 PPC Sparc Alpha MIPS MIPSel
+ Linux 2.6 X X X X X X X
+ Darwin (Mac OS X) X X X
+ Solaris X X
+ FreeBSD X X
+ NetBSD X X
+ OpenBSD 3.4, 3.5 X
+ Windows X
+
+ Some operating systems are more equal than others: most of the
+ development and testing is done on x86/x86-64 Linux and x86/PPC
+ 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
+ in the manual, or
+
+ http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
+
+ if you do not have the manual for some reason.
projects / sbcl.git / blobdiff