0.8.9.7:

[sbcl.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 728f6db..28da68d 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,10 +1,13 @@
 IF YOU HAVE A BINARY DISTRIBUTION:
 
 IF YOU HAVE A BINARY DISTRIBUTION:
 

-The two files that SBCL needs to run are sbcl and sbcl.core.
+The two files that SBCL needs to run, at minimum, are sbcl and sbcl.core.

 They are in 
        src/runtime/sbcl
 and
        output/sbcl.core
 They are in 
        src/runtime/sbcl
 and
        output/sbcl.core

+In addition, there are a number of modules that extend the basic sbcl
+functionality, in
+        contrib/

 
 sbcl is a standard executable, built by compiling and linking an
 ordinary C program. It provides the runtime environment for the
 
 sbcl is a standard executable, built by compiling and linking an
 ordinary C program. It provides the runtime environment for the

@@ -17,24 +20,38 @@ 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:
 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
+
+  1. by default, in /usr/lib/sbcl/sbcl.core or /usr/local/lib/sbcl/sbcl.core
+     (depending on the SBCL_HOME C preproccessor #define at compile-time)

   2. by environment variable: 
   2. by environment variable: 

-     $ export SBCL_HOME=/foo/bar/
+     $ export SBCL_HOME=/foo/bar/lib/sbcl

      $ sbcl
   3. by command line option:
      $ sbcl --core /foo/bar/sbcl.core"
      $ 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.
+
+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.

 
 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.
 
 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.
+  3. Copy the contrib modules that you're using (if any) to the same place
+      as sbcl.core
+  4. Optionally copy sbcl.1 to /usr/man/man1 or /usr/local/man/man1.
+
+The script install.sh does all of this for you, including compilation
+of all contrib modules it can find, and installation of all those that
+pass their tests.  You should set the INSTALL_ROOT environment
+variable to /usr or /usr/local as appropriate before starting
+install.sh: e.g.

 
 

+   # INSTALL_ROOT=/usr/local sh install.sh
+or
+   $ INSTALL_ROOT=/home/me/sbcl sh install.sh
+(if your INSTALL_ROOT is XYZ, SBCL_HOME should be set to
+XYZ/lib/sbcl).

 
 IF YOU HAVE A SOURCE DISTRIBUTION:
 
 
 IF YOU HAVE A SOURCE DISTRIBUTION:
 

@@ -43,16 +60,38 @@ This software has been built successfully on these systems:
                os = Debian GNU/Linux 2.1 with libc >= 2.1
                        host lisp = CMU CL 2.4.17
                        host lisp = SBCL itself
                os = Debian GNU/Linux 2.1 with libc >= 2.1
                        host lisp = CMU CL 2.4.17
                        host lisp = SBCL itself

+                       host lisp = CLISP CVS as of end of April

                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 = 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
+               os = OpenBSD 2.6, 2.7, 2.8, 2.9, and 3.0
+                       host lisp = SBCL itself
+       cpu = alpha
+               os = Debian GNU/Linux 2.2 with libc >= 2.1
+                       host lisp = SBCL itself
+               os = Tru64 5.1
+                       host lisp = SBCL itself
+       cpu = sparc
+               os = Debian GNU/Linux 2.2 with libc >= 2.2

                        host lisp = SBCL itself
                        host lisp = SBCL itself

-It is known not to build under CLISP, because CLISP doesn't support
-MAKE-LOAD-FORM. Reports of other systems that it works on, or help in
-making it run on more systems, would be appreciated.
+               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
+               os = MacOS X.2
+                       host lisp = OpenMCL 0.13.6
+                       host lisp = SBCL itself
+       cpu = mips and mipsel
+               os = Debian GNU/Linux 3.0
+                       host lisp = SBCL itself
+
+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
 
                CAUTION CAUTION CAUTION CAUTION CAUTION
            SBCL, like CMU CL, overcommits memory. That is, it

@@ -93,17 +132,24 @@ To build the system binaries:
   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
   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.
-     This will probably be reduced somewhat in some later version
-     by allowing cold load of byte-compiled files, so that the cold
-     image can be smaller.)
-  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 edit the base-target-features.lisp-expr file
-     to customize the resulting Lisp system. By enabling or disabling
-     features in this file, you can create a smaller system, or one
-     with extra code for debugging output or error-checking or other things.
+     GENESIS, which makes the Lisp image grow to around 128 Mb RAM+swap.
+  2. If the GNU make command is not available under the names "gmake"
+     or "make", 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, threads, or extra debugging code (see
+     "base-target-features.lisp-expr" for a list of recognized
+     *FEATURES*).  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
   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

@@ -117,9 +163,7 @@ To build the system binaries:
        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
        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.
+     spent about 2/3 of its wall clock time swapping. 

 
 Now you should have the same src/runtime/sbcl and output/sbcl.core
 files that come with the binary distribution, and you can install
 
 Now you should have the same src/runtime/sbcl and output/sbcl.core
 files that come with the binary distribution, and you can install