Fix make-array transforms.

[sbcl.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 796565e..378515b 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -4,7 +4,7 @@ INSTALLING SBCL
 
     1. BINARY DISTRIBUTION
     1.1. Quick start
 
     1. BINARY DISTRIBUTION
     1.1. Quick start

-    1.2. Finding ancilliary files
+    1.2. Finding ancillary files

     1.3. Anatomy of SBCL
 
     2. SOURCE DISTRIBUTION
     1.3. Anatomy of SBCL
 
     2. SOURCE DISTRIBUTION

@@ -19,9 +19,14 @@ INSTALLING SBCL
 
 1.1. Quick start:
 
 
 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 following command installs SBCL and related documentation under

-  the "/usr/local" directory:
-  
+  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=/usr/local sh install.sh
 
   You can also install SBCL as a user, under your home directory:

@@ -29,17 +34,21 @@ INSTALLING SBCL
     $ INSTALL_ROOT=/home/me sh install.sh
 
   In other words, "install.sh" installs SBCL under the directory named
     $ INSTALL_ROOT=/home/me sh install.sh
 
   In other words, "install.sh" installs SBCL under the directory named

-  by the environment variable "INSTALL_ROOT".
+  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 then
-  "/usr/local", see section 1.2, "Finding ancilliary files".
+  If you install SBCL from binary distribution in other location than
+  "/usr/local", see section 1.2, "Finding ancillary files".

 
 

-1.2. Finding ancilliary 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.
 
 
   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:
+  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".
 
     1. By default, in a location configured when the system was built.
        For binary distributions this is in "/usr/local/lib/sbcl".

@@ -57,15 +66,17 @@ INSTALLING SBCL
 
          $ sbcl --core /foo/bar/sbcl.core
 
 
          $ 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.
 
   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:
 1.3. Anatomy of SBCL
 
   The two files that SBCL needs to run, at minimum, are:

@@ -92,7 +103,7 @@ INSTALLING SBCL
   passed their tests. If you need to install by hand, see "install.sh"
   for details.
 
   passed their tests. If you need to install by hand, see "install.sh"
   for details.
 

-  Documentation concists of a man-page, the SBCL Manual (in info, pdf
+  Documentation consists of a man-page, the SBCL Manual (in info, pdf

   and html formats), and a few additional text files.
 
 2. SOURCE DISTRIBUTION
   and html formats), and a few additional text files.
 
 2. SOURCE DISTRIBUTION

@@ -107,13 +118,32 @@ INSTALLING SBCL
 
     $ sh make.sh
 
 
     $ 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
   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
+  cross-compilation host. For example, to use CMUCL (assuming has

   been installed under its default name "lisp") as the
   cross-compilation host:
 
   been installed under its default name "lisp") as the
   cross-compilation host:
 

-    $ sh make.sh 'lisp -batch'
+    $ 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
 
   The build may take a long time, especially on older hardware. A
   successful build ends with a message beginning: "The build seems to

@@ -142,27 +172,44 @@ INSTALLING SBCL
   enabling or disabling features like documentation strings, threads,
   or extra debugging code.
 
   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", containing a lambda expression
-  which is applied to the default *FEATURES* set and which returns the
-  new *FEATURES* set, e.g.
+  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.

 
 

-    (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)))
+  Some features of interest:

 
 

-  This is the preferred way because it lets local changes interact
-  cleanly with CVS changes to the main, global source tree.
+    :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".
 
 
   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"
 2.3. Troubleshooting
 
   "GNU Make not found"

@@ -174,7 +221,7 @@ INSTALLING SBCL
   Segfaults on Fedora
 
     Try disabling exec-shield. The easiest way is to use
   Segfaults on Fedora
 
     Try disabling exec-shield. The easiest way is to use

-    setarch: "setarch i386 sbcl".
+    setarch: "setarch i386 -R sbcl".

 
   Build crashes mysteriously, machine becomes unstable, etc
 
 
   Build crashes mysteriously, machine becomes unstable, etc
 

@@ -183,8 +230,12 @@ INSTALLING SBCL
 
   Other
 
 
   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.
+    * 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
 
     * Some GCC versions are known to have bugs that affect SBCL
       compilation: if the error you're encountering seems related to

@@ -203,13 +254,13 @@ INSTALLING SBCL
   itself, it's a good idea.) Follow the "CVS Repository" link on
   <http://sourceforge.net/projects/sbcl> for instructions.
 
   itself, it's a good idea.) Follow the "CVS Repository" link on
   <http://sourceforge.net/projects/sbcl> for instructions.
 

-2.5. Supported platforms 
+2.5. Supported platforms

 
 

-  Last updated for SBCL 0.8.10.61 (2004-05-28).
+  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
 
   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.
+  behind on less-used operating systems.

 
   Supported toolchains:
 
 
   Supported toolchains:
 

@@ -220,30 +271,38 @@ INSTALLING SBCL
 
     SBCL
     CMUCL
 
     SBCL
     CMUCL

-    OpenMCL
-    CLISP (recent versions only)
+    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
 
     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.
+    as host, otherwise CCL on a PPC and CMUCL elsewhere.

 
   Supported operating systems and architectures:
 
 
   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     X 
-    FreeBSD                 X
-    OpenBSD 3.4, 3.5            X
-    NetBSD                  X
-    Solaris                                X
-    Tru64                            X
-    Darwin (Mac OS X)           X
+                           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 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.
+    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
 
     If an underprivileged platform is important to you, you can help

-    by eg. testing during the monthly freeze periods, and most
+    by e.g. testing during the monthly freeze periods, and most

     importantly by reporting any problems.
 
     importantly by reporting any problems.
 

-    If you need support beyond what is available on the mailing lists,
-    see "Consultants" in the "SUPPORT" file.
+    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.