From: Nikodemus S. <tsi...@cc...> - 2004-05-29 12:28:59
|
Going once... The following version of INSTALL incorporates the suggestions, and a few more changes, esp. to the way supported platforms are enumerated. Cheers, -- Nikodemus "Not as clumsy or random as a C++ or Java. An elegant weapon for a more civilized time." INSTALLING SBCL CONTENTS 1. BINARY DISTRIBUTION 1.1. Quick start 1.2. Finding ancilliary 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: The following command installs SBCL under the "/usr/local" directory: # 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 you install SBCL from binary distribution in other location then "/usr/local", see section 1.2, "Finding ancilliary files". 1.2. Finding ancilliary files The SBCL runtime needs to be able to find the ancillary files associated with it: the "sbcl.core" file, and the contrib modules. This 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 When using this option contrib modules are looked for in the directory where the designated core resides, and in "SBCL_HOME". 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. 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 contrib-modules that have passed their tests. If you need to install by hand, see "install.sh" for details. 2. SOURCE DISTRIBUTION 2.1. Quick start IMPORTANT: If you are going to build SBCL on a mission critical machine, review the "Troubleshooting" section before building. 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 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 CMU CL (assuming has been installed under its default name "lisp") as the cross-compilation host: $ sh make.sh 'lisp -batch' 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 by creating a file "customize-target-features.lisp-expr", containing a lambda expression which is applied to the default *FEATURES* set and which returns the new *FEATURES* set, e.g. (lambda (features) (flet ((enable (x) (pushnew x features)) (disable (x) (setf features (remove x features)))) ;; Threading support, available on x86 Linux only. (enable :sb-thread) ;; Slightly smaller core (disable :sb-doc))) This is the preferred way because it lets local changes interact cleanly with CVS changes to the main, global source tree. A catalog of available features and their meaning can be found in "base-target-features.lisp-expr". 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 sbcl". Build crashes mysteriously, machine becomes unstable, etc 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 was 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. Other * Check that the host lisp you're building with is known to work as an SBCL build host, and the your OS is supported. * 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 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 OS's. Supported toolchains: GNU toolchain Sun toolchain with GCC Supported build hosts are: SBCL CMUCL OpenMCL CLISP (recent versions only) 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 OpenMCL on a PPC and CMUCL elsewhere. Supported operating systems and architectures: x86 PPC Alpha Sparc HPPA MIPS MIPSel Linux 2.2, 2.4, 2.6 X X X X ? X X FreeBSD X OpenBSD 3.4 X NetBSD X Solaris X Tru64 X Darwin (Mac OS X) X Some OS's are more equal then others: most of the development and testing is done on x86 Linux and *BSD, PPC Linux and Mac OS X. If an underprivileged platform is important to you, you can help by eg. testing during the monthly freeze periods. If you need support beyond what is available on the mailing lists, see "Consultants" in the "SUPPORT" file. |