.TH SBCL 1 "$Date$"
.AT 3
.SH NAME
-SBCL -- "Steel Bank Common Lisp"
+SBCL -- Steel Bank Common Lisp
.SH DESCRIPTION
*
Many people like to run SBCL, like other Lisp systems, as a subprocess
-under Emacs. The Emacs "ilisp" mode provides many convenient features,
-like command line editing, tab completion, and various kinds of
-coupling between Common Lisp source files and the interactive SBCL
-subprocess, but can be somewhat fragile because it tries to be so
-clever and intimate in its interactions with the Lisp subprocess. In
-case of ilisp problems, running SBCL in the Emacs "shell" mode can a
-useful substitute.
+under Emacs. The Emacs "Slime" and "ilisp" modes provide many
+convenient features, like command line editing, tab completion, and
+various kinds of coupling between Common Lisp source files and the
+interactive SBCL subprocess, but they can be somewhat fragile wrt.
+packages and readtables, in which case SBCL in the Emacs "shell" mode
+can a useful substitute.
.SH OVERVIEW
after the MacLisp compiler, people will tell you that Lisp is an
interpreted language. Ignore them.)
-SBCL aims for but has not yet reached compliance with the ANSI
+SBCL aims for but has not completely achieved compliance with the ANSI
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
-SBCL is essentially a compiler-only implementation of Lisp. All
-nontrivial Lisp code is compiled to native machine code before being
-executed, even when the Lisp code is typed interactively at the
-"interpreter" prompt.
-
SBCL inherits from CMU CL the "Python" native code compiler. (Though
-we've essentially dropped that name in order to avoid confusion with
-the scripting language also called Python.) This compiler is very
-clever about understanding the type system of Common Lisp and using it
-to optimize code, and about producing notes to let the user know when
-the compiler doesn't have enough type information to produce efficient
+we often avoid that name in order to avoid confusion with the
+scripting language also called Python.) This compiler is very clever
+about understanding the type system of Common Lisp and using it to
+optimize code, and about producing notes to let the user know when the
+compiler doesn't have enough type information to produce efficient
code. It also tries (almost always successfully) to follow the unusual
but very useful principle that "declarations are assertions", i.e.
type declarations should be checked at runtime unless the user
explicitly tells the system that speed is more important than safety.
-The CMU CL version of this compiler reportedly produces pretty good
-code for modern CPU architectures which have lots of registers, but
-its code for the X86 is marred by a lot of extra loads and stores to
-stack-based temporary variables. Because of this, and because of the
-extra levels of indirection in Common Lisp relative to C, the
-performance of SBCL isn't going to impress people who are impressed by
-small constant factors. However, even on the X86 it tends to be faster
-than byte interpreted languages (and can be a lot faster).
+The compiler reportedly produces pretty good code for modern CPU
+architectures which have lots of registers, but its code for the X86
+is marred by many extra loads and stores to stack-based temporary
+variables. Because of this, and because of the extra levels of
+indirection in Common Lisp relative to C, the performance of SBCL
+isn't going to impress people who are impressed by small constant
+factors. However, even on the X86 it tends to be faster than byte
+interpreted languages (and can be a lot faster).
The compiled code uses garbage collection to automatically
manage memory. The garbage collector implementation varies considerably
For more information about the compiler, see the user manual.
-.SH DOCUMENTATION
-
-Currently, the documentation for the system is
-.TP 3
-\--
-this man page
-.TP 3
-\--
-the user manual
-.TP 3
-\--
-doc strings and online help built into the SBCL executable
-.PP
-
.SH COMMAND LINE SYNTAX
Command line syntax can be considered an advanced topic; for ordinary
.TP 3
.B --core <corefilename>
Run the specified Lisp core file instead of the default. (See the FILES
-section.) Note that if the Lisp core file is a user-created core file, it may
-run a nonstandard toplevel which does not recognize the standard toplevel
-options.
+section for the standard core, or the system documentation for
+SB-INT:SAVE-LISP-AND-DIE for information about how to create a
+custom core.) Note that if the Lisp core file is a user-created core
+file, it may run a nonstandard toplevel which does not recognize the
+standard toplevel options.
.TP 3
.B --noinform
Suppress the printing of any banner or other informational message at
startup. (This makes it easier to write Lisp programs which work
cleanly in Unix pipelines. See also the "--noprint" and
"--disable-debugger" options.)
+.TP 3
+.B --help
+Print some basic information about SBCL, then exit.
+.TP 3
+.B --version
+Print SBCL's version information, then exit.
.PP
In the future, runtime options may be added to control behavior such
are stripped out of the command line before the
Lisp toplevel logic gets a chance to see it.
-Supported toplevel options for the standard SBCL core are
+The toplevel options supported by the standard SBCL core are
.TP 3
.B --sysinit <filename>
Load filename instead of the default system-wide initialization file.
.TP 3
.B --eval <command>
After executing any initialization file, but before starting the
-read-eval-print loop on standard input, evaluate the command given.
-More than one --eval option can be used, and all will be executed, in
-the order they appear on the command line.
+read-eval-print loop on standard input, read and evaluate the command
+given. More than one --eval option can be used, and all will be read
+and executed, in the order they appear on the command line.
.TP 3
.B --load <filename>
This is equivalent to --eval '(load "<filename>")'. The special
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
Regardless of the order in which --sysinit, --userinit, and --eval
options appear on the command line, the sysinit file, if it exists, is
loaded first; then the userinit file, if it exists, is loaded; then
-any --eval commands are executed in sequence; then the read-eval-print
-loop is started on standard input. At any step, error conditions or
-commands such as SB-EXT:QUIT can cause execution to be terminated
-before proceeding to subsequent steps.
+any --eval commands are read and executed in sequence; then the
+read-eval-print loop is started on standard input. At any step, error
+conditions or commands such as SB-EXT:QUIT can cause execution to be
+terminated before proceeding to subsequent steps.
Note that when running SBCL with the --core option, using a core file
created by a user call to the SB-EXT:SAVE-LISP-AND-DIE, the toplevel
.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 requires on the order of 16Mb RAM to run on X86 systems,
-though for 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.core and /usr/local/lib/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.
+SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD), 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.
-$HOME/.sbclrc is the standard location for a user's SBCL
-initialization file, unless overridden by the --userinit
-command line option.
+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 KNOWN 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
(DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
(DEFUN SOMETIMES (X) (ODDP X))
(DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
-then running (FOO 1) gives NOT-THIS-TIME, because the
-never compiled code to check the declaration.
+then running (FOO 1) gives NOT-THIS-TIME, because the compiler
+relied on the truth of the DECLAIM without checking it.
Some things are implemented very inefficiently.
.TP 3
There are still some nagging pre-ANSIisms, notably
.TP 3
-\--
-CLOS (based on the PCL reference implementation) is incompletely
-integrated into the system, so that e.g. SB-PCL::FIND-CLASS is a
-different function than CL::FIND-CLASS. (In practice, you need to
-be a pretty advanced user before this is a serious problem, and
-by then you can usually work around it, but it's still distasteful.
-It's arguably the outstanding "This should be fixed by version 1.0"
-issue.)
-.TP 3
--
The ANSI-recommended idiom for creating a function which is only
sometimes expanded inline,
To report a bug, please send mail to the mailing lists sbcl-help or
sbcl-devel. You can find the complete mailing list addresses on the
-web pages, <http://sbcl.sourceforge.net/>. (You may also find fancy
+web pages at <http://sbcl.sourceforge.net/>. (You may also find fancy
SourceForge bug-tracking machinery there, but don't be fooled. As of
2002-07-25 anyway, we don't actively monitor that machinery, and it
exists only because we haven't been able to figure out how to turn
.SH SUPPORT
Various information about SBCL is available at
-<http://sbcl.sourceforge.net/>. The mailing lists there are the
-recommended place to look for support.
+<http://ww.sbcl.org/>. 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
a loader, used to read sbcl.core
.TP
.I sbcl.core
-dumped memory image containing most of SBCL, to be loaded by the
-'sbcl' executable
+dumped memory image containing most of SBCL, to be loaded by
+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
Dozens of people have made substantial contributions to SBCL and its
subsystems, and to the CMU CL system on which it was based, over the
-years. See the CREDITS file in the distribution.
+years. See the CREDITS file in the distribution for more information.
+
+.SH SEE ALSO
+
+Full SBCL documentation is maintained as a Texinfo manual. If is has
+been installed, the command
+.IP
+.B info sbcl
+.PP
+should give you access to the complete manual. Depending on your
+installation it may also be available in HTML and PDF formats in eg.
+.IP
+.B /usr/local/share/doc/sbcl/
+.PP
+See the SBCL homepage
+.IP
+.B http://www.sbcl.org/
+.PP
+for more information, including directions on how to subscribe to the
+sbcl-devel and sbcl-help mailing-lists.
projects / sbcl.git / blobdiff