.TH SBCL 1 "$Date$"
.AT 3
.SH NAME
-SBCL -- "Steel Bank Common Lisp"
+SBCL -- Steel Bank Common Lisp
.SH DESCRIPTION
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:
.TP 3
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
+others.
+
+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 parent CMU CL. Many of the
+SBCL has retained some extensions from its parent CMU CL. Many of the
retained extensions are in these categories:
.TP 3
\--
SAVE-LISP-AND-DIE supports fewer keyword options than CMU CL's
SAVE-LISP does.
-(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
pipelines.
.TP 3
.B --disable-debugger
-This is equivalent to --eval '(sb-ext:disable-debugger)'.
-By default, a Common Lisp system tries to ask the programmer for help
-when it gets in trouble (by printing a debug prompt on *DEBUG-IO*).
-However, this is not useful behavior for a system running with no
-programmer available, and this option tries to set up more appropriate
-behavior for that situation. This is implemented by modifying special
-variables: we set *DEBUG-IO* to send its output to *ERROR-OUTPUT*, and
-to raise an error if any input is requested from it, and we set
-*DEBUGGER-HOOK* to output a backtrace, then exit the process with a
-failure code. Because it is implemented by modifying special variables,
-its effects persist in .core files created by SB-EXT:SAVE-LISP-AND-DIE.
-(If you want to undo its effects, see the SB-EXT:ENABLE-DEBUGGER
+This is equivalent to --eval '(sb-ext:disable-debugger)'. By default,
+a Common Lisp system tries to ask the programmer for help when it gets
+in trouble (by printing a debug prompt, then listening, on
+*DEBUG-IO*). However, this is not useful behavior for a system running
+with no programmer available, and this option tries to set up more
+appropriate behavior for that situation. This is implemented by
+redefining INVOKE-DEBUGGER so that any call exits the process with a
+failure code after printing a backtrace, and by redefining *DEBUG-IO*
+to send its output to *ERROR-OUTPUT* and to raise an error if any
+input is requested from it. (Note that because it is implemented by
+modifying special variables and FDEFINITIONs, its effects persist in
+.core files created by SB-EXT:SAVE-LISP-AND-DIE. If you want to undo
+its effects, e.g. if you build a system unattended and then want to
+operate a derived system interactively, see the SB-EXT:ENABLE-DEBUGGER
command.)
.PP
.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.
-.SH ENVIRONMENT
-
-.TP 10n
-.BR SBCL_HOME
-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
-default.
-.PP
-
-.SH FILES
-
-/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."
-.TP 3
-\--
-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 (!).
-.PP
+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
<http://sbcl.sourceforge.net/>. The mailing lists there are the
recommended place to look for support.
+.SH ENVIRONMENT
+
+.TP 10n
+.BR SBCL_HOME
+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
+packager.
+
.SH FILES
.TP
.TP
.I sbcl.core
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.
.TP
.I sbclrc
-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
+option.
.TP
.I .sbclrc
-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)
.SH AUTHORS