Update of /cvsroot/sbcl/sbcl/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv17354/doc
"brown paper bag" bug fix: initialise the thread->state slot
when it's created, to fix the most obvious threading problem
Search order for sbcl.core and sbclrc simplified.
Manual page edits: updates for contrib/, threading, platforms,
new sbcl.core search order, etc
Make "debugger invoked" message print thread id
asdf-install contrib: new UNINSTALL function deletes a
New installation variable $(BUILD_ROOT) for use by package
installers that want to install into a fake root directory
RCS file: /cvsroot/sbcl/sbcl/doc/sbcl.1,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -d -r1.31 -r1.32
--- sbcl.1 13 Sep 2003 01:19:37 -0000 1.31
+++ sbcl.1 7 Oct 2003 21:41:27 -0000 1.32
@@ -16,7 +16,7 @@
.TH SBCL 1 "$Date$"
-SBCL -- "Steel Bank Common Lisp"
+SBCL -- Steel Bank Common Lisp
@@ -76,7 +76,13 @@
standard for Common Lisp. More information about this is available in
the BUGS section below.
-SBCL also includes various non-ANSI extensions.
+SBCL also includes various non-ANSI extensions, described more fully
+in the User Manual. Some of these are in the base system and others
+are "contrib" modules loaded on request using REQUIRE. For example,
+to load the SB-BSD-SOCKETS module that providces TCP/IP connectivity,
+ * (require 'asdf)
+ * (require 'sb-bsd-sockets)
Many Lispy extensions have been retained from CMU CL:
@@ -130,13 +136,17 @@
improvements have been shared between the two projects, and sometimes
the two projects disagree about what would be an improvement.
-Most extensions supported by CMU CL are not supported in SBCL,
+Most extensions supported by CMU CL have been unbundled from SBCL,
including Motif support, the Hemlock editor, search paths, the
-low-level Unix interface, the WIRE protocol, multithreading, various
-user-level macros and functions (e.g. LETF, ITERATE, MEMQ,
-REQUIRED-ARGUMENT), and many others.
+low-level Unix interface, the WIRE protocol, various user-level macros
+and functions (e.g. LETF, ITERATE, MEMQ, REQUIRED-ARGUMENT), and many
-SBCL has retained some extensions from parent CMU CL. Many of the
+SBCL inplements multithreading, but in a completely different fashion
+from CMU CL: see the User Manual for details. As of 0.8.5 this is
+considered beta-quality and must be explicitly enabled at build time.
+SBCL has retained some extensions from its parent CMU CL. Many of the
retained extensions are in these categories:
@@ -170,19 +180,17 @@
SAVE-LISP-AND-DIE supports fewer keyword options than CMU CL's
-(Why doesn't SBCL support more extensions? Why drop all those nice
-extensions from CMU CL when the code already exists? This is a
-frequently asked question on the mailing list. In some cases, it's a
-design philosophy issue: arguably SBCL has done its job by supplying a
-stable FFI, and the right design decision is to move functionality
-derived from that, like socket support, into separate libraries,
-distributed as separate software packages by separate maintainers. In
-other cases it's a practical decision, hoping that focusing on a
-smaller number of things will let us do a better job on them. This is
-very much the case for multithreading: it's an important, valuable
-extension, but it's not easy to get right, and especially while SBCL
-is still working on basic ANSI compliance, difficult extensions aren't
-likely to be a priority.)
+(Why doesn't SBCL support more extensions natively? Why drop all
+those nice extensions from CMU CL when the code already exists? This
+is a frequently asked question on the mailing list. There are two
+principal reasons. First, it's a design philosophy issue: arguably
+SBCL has done its job by supplying a stable FFI, and the right design
+decision is to move functionality derived from that, like socket
+support, into separate libraries. Some of these are distributed with
+SBCL as "contrib" modules, others are distributed as separate software
+packages by separate maintainers. Second, it's a practical decision -
+focusing on a smaller number of things will, we hope, let us do a
+better job on them.)
.SH THE COMPILER
@@ -365,60 +373,25 @@
.SH SYSTEM REQUIREMENTS
-SBCL currently runs on
-X86 (Linux, FreeBSD, and OpenBSD), Alpha (Linux, Tru64), PPC
-(Linux) and SPARC (Linux and Solaris 2.x).
-For information on other ongoing and possible ports, see the
-sbcl-devel mailing list, and/or the web site.
+SBCL currently runs on X86 (Linux, FreeBSD, and OpenBSD), Alpha
+(Linux, Tru64), PPC (Linux, Darwin/MacOS X), SPARC (Linux and Solaris
+2.x), and MIPS (Linux). For information on other ongoing and possible
+ports, see the sbcl-devel mailing list, and/or the web site.
SBCL requires on the order of 16Mb RAM to run on X86 systems, though
all but the smallest programs would be happier with 32Mb or more.
-If this variable is set, it overrides the default directories for
-files like "sbclrc" and "sbcl.core", so that instead of being searched
-for in e.g. /etc/, /usr/local/etc/, /usr/lib/, and /usr/local/lib/, they
-are searched for only in the directory named by SBCL_HOME. This is
-intended to support users who wish to use their own version of SBCL
-instead of the version which is currently installed as the system
-/usr/lib/sbcl/sbcl.core and /usr/local/lib/sbcl/sbcl.core are the
-standard locations for the standard SBCL core, unless overridden by
-the SBCL_HOME variable.
-/etc/sbclrc and /usr/local/etc/sbclrc are the standard locations for
-system-wide SBCL initialization files, unless overridden by the
-SBCL_HOME variable or the --sysinit command line option.
-$HOME/.sbclrc is the standard location for a user's SBCL
-initialization file, unless overridden by the --userinit
-command line option.
.SH KNOWN BUGS
This section attempts to list the most serious and long-standing bugs.
For more detailed and current information on bugs, see the BUGS file
in the distribution.
-It is possible to get in deep trouble by exhausting
-memory. To plagiarize a sadly apt description of a language not
-renowned for the production of bulletproof software, "[The current
-SBCL implementation of] Common Lisp makes it harder for you to shoot
-yourself in the foot, but when you do, the entire universe explodes."
-Like CMU CL, the SBCL system overcommits memory at startup. On typical
-Unix-alikes like Linux and FreeBSD, this means that if the SBCL system
-turns out to use more virtual memory than the system has available for
-it, other processes tend to be killed randomly (!).
+It is possible to get in deep trouble by exhausting heap memory. The
+SBCL system overcommits memory at startup, so, on typical Unix-alikes
+like Linux and FreeBSD, this means that if the SBCL system turns out
+to use more virtual memory than the system has available for it, other
+processes tend to be killed randomly (!).
The compiler's handling of function return values unnecessarily
violates the "declarations are assertions" principle that it otherwise
@@ -512,6 +485,16 @@
<http://sbcl.sourceforge.net/>. The mailing lists there are the
recommended place to look for support.
+This variable controls where files like "sbclrc", "sbcl.core", and the
+add-on "contrib" systems are searched for. If it is not set, then
+sbcl sets it from a compile-time default location which is usually
+/usr/local/lib/sbcl/ but may have been changed e.g. by a third-party
@@ -521,14 +504,17 @@
dumped memory image containing most of SBCL, to be loaded by
-the 'sbcl' executable
+the 'sbcl' executable. Looked for in $SBCL_HOME,
+unless overridden by the --core option.
-optional system-wide startup script (in an etc-ish system
-configuration file directory)
+optional system-wide startup script, looked for in $SBCL_HOME/sbclrc
+then /etc/sbclrc, unless overridden by the --sysinit command line
-optional per-user customizable startup script (in user's home directory)
+optional per-user customizable startup script (in user's home
+directory, or as specified by --userinit)