.\" If you want to use this code or any part of CMU Common Lisp, please
.\" contact Scott Fahlman or slisp-group@cs.cmu.edu.
.\" **********************************************************************
+.\" Most of SBCL, including this man page, is in the public domain. See
+.\" COPYING in the distribution for more information.
.\"
.TH SBCL 1 "$Date$"
.AT 3
.SH NAME
-SBCL -- "Steel Bank Common Lisp"
+SBCL -- Steel Bank Common Lisp
.SH DESCRIPTION
acknowledge the connection: steel and banking are the industries where
Carnegie and Mellon made the big bucks.)
-.SH COMMAND LINE SYNTAX
+.SH LICENSING
-Command line syntax can be considered an advanced topic; for ordinary
-interactive use, no command line arguments should be necessary.
+It is free software, mostly in the public domain, but with some
+subsystems under BSD-style licenses which allow modification and
+reuse as long as credit is given. It is provided "as is", with no
+warranty of any kind.
-In order to understand the command line argument syntax for SBCL, it
-is helpful to understand that the SBCL system is implemented as two
-components, a low-level runtime environment written in C and a
-higher-level system written in Common Lisp itself. Some command line
-arguments are processed during the initialization of the low-level
-runtime environment, some command line arguments are processed during
-the initialization of the Common Lisp system, and any remaining
-command line arguments are passed on to user code.
+For more information about license issues, see the COPYING file in
+the distribution. For more information about history, see the
+CREDITS file in the distribution.
-The full, unambiguous syntax for invoking SBCL at the command line is
-.TP 3
-.B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]
-.PP
+.SH RUNNING SBCL
-For convenience, the --end-runtime-options and --end-toplevel-options
-elements can be omitted. Omitting these elements can be convenient
-when you are running the program interactively, and you can see that
-no ambiguities are possible with the option values you are using.
-Omitting these elements is probably a bad idea for any batch file
-where any of the options are under user control, since it makes it
-impossible for SBCL to detect erroneous command line input, so that
-erroneous command line arguments will be passed on to the user program
-even if they was intended for the runtime system or the Lisp system.
+To run SBCL, type "sbcl" at the command line with no arguments. (SBCL
+understands command line arguments, but you probably won't need to use
+them unless you're a fairly advanced user. If you are, you should read
+the COMMAND LINE SYNTAX section, below.) You should see some startup
+messages, then a prompt ("\f(CR*\fR"). Type a Lisp expression at the prompt,
+and SBCL will read it, execute it, print any values returned, give you
+another prompt, and wait for your next input. For example,
+\f(CR
+ * (+ 1 2 3)
-Supported runtime options are
-.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.
-.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 in
-Unix pipelines. See also the "--noinform" option.)
-.PP
+ 6
+ * (funcall (lambda (x y) (list x y y)) :toy :choo)
-In the future, runtime options may be added to control behavior such
-as lazy allocation of memory.
+ (:TOY :CHOO :CHOO)
+ * "Hello World"
-Runtime options, including any --end-runtime-options option,
-are stripped out of the command line before the
-Lisp toplevel logic gets a chance to see it.
+ "Hello World"
+ *
+\fR
-Supported toplevel options for the standard SBCL core are
+Many people like to run SBCL, like other Lisp systems, as a subprocess
+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 with
+respect to packages and readtables, in which case SBCL in the Emacs
+"shell" mode can be a useful substitute.
+
+.SH OVERVIEW
+
+SBCL compiles Common Lisp to native code. (Even today, some 30 years
+after the MacLisp compiler, people will tell you that Lisp is an
+interpreted language. Ignore them.)
+
+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, described more fully
+in the User Manual. Some of these are in the base system and others
+are "contrib" modules loaded on request using \f(CRREQUIRE\fR. For
+example, to load the \f(CRSB\-BSD\-SOCKETS\fR module that provides
+TCP/IP connectivity,
+\f(CR
+ * (require \(aqasdf)
+ * (require \(aqsb\-bsd\-sockets)
+\fR
+
+Many Lispy extensions have been retained from CMU CL:
.TP 3
-.B --sysinit <filename>
-Load filename instead of the default system-wide initialization file.
-(See the FILES section.) There is no special option to cause no
-system-wide initialization file to be read, but on a Unix system
-"--sysinit /dev/null" can be used to achieve the same effect.
+\--
+CMU-CL-style safe implementation of type declarations:
+"Declarations are assertions."
.TP 3
-.B --userinit <filename>
-Load filename instead of the default user initialization file. (See
-the FILES section.) There is no special option to cause no user
-initialization file to be read, but on a Unix system "--userinit
-/dev/null" can be used to achieve the same effect.
+\--
+the source level debugger (very similar to CMU CL's)
.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.
+\--
+the profiler (now somewhat different from CMU CL's)
.TP 3
-.B --noprint
-When ordinarily the toplevel "read-eval-print loop" would be executed,
-execute a "read-eval loop" instead, i.e. don't print a prompt and
-don't echo results. Combined with the --noinform runtime option, this
-makes it easier to write Lisp "scripts" which work in Unix pipelines.
+\--
+saving the state of the running SBCL process, producing a
+"core" file which can be restarted later
+.TP 3
+\--
+Gray streams (a de-facto standard system of overloadable CLOS classes
+whose instances can be used wherever ordinary ANSI streams can be used)
.TP 3
-.B --noprogrammer
-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. Thus 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.
+\--
+weak pointers and finalization (which have unfortunately
+suffered from at least some code rot, so that \fIe.g.\fR weak hash
+tables don't work)
.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.
-
-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
-options may be under the control of user code passed as arguments to
-SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options
-option itself can be considered a toplevel option, i.e. the user core,
-at its option, may not support it.
-
-In the standard SBCL startup sequence (i.e. with no user core
-involved) toplevel options and any --end-toplevel-options option are
-stripped out of the command line argument list before user code gets a
-chance to see it.
-
-.SH OVERVIEW
-
-SBCL aims for but has not reached ANSI compliance.
-
-SBCL compiles Lisp to native code, or optionally to more-compact but
-much slower byte code.
-
-SBCL's garbage collector is generational and conservative.
-
-SBCL includes a source level debugger, as well as the ANSI TRACE
-facility and a rudimentary profiler.
+Fundamental system interface extensions are also provided:
+.TP 3
+\--
+calling out to C code (a.k.a. FFI, foreign function interface,
+with very nearly the same interface as CMU CL)
+.TP 3
+\--
+some simple support for operations with a "scripting language" flavor,
+\fIe.g.\fR reading POSIX \f(CRargc\fR and \f(CRargv\fR, or executing a
+subprogram
+.PP
.SH DIFFERENCES FROM CMU CL
SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
system and a C compiler, and all of its properties are specified by
-the version of the source code that it was created from. (This clean
+the version of the source code that it was created from. This clean
bootstrappability was the immediate motivation for forking off of the
-CMU CL development tree.) A variety of internal implementation
-differences are motivated by this.
+CMU CL development tree. A variety of implementation differences are
+motivated by this design goal.
-Maintenance work in SBCL since the fork has diverged in various
-details from the maintenance work in CMU CL. E.g. as of 2001-04-12,
-SBCL was more ANSI-compliant than CMU CL in various details such as
-support for PRINT-OBJECT and DESCRIBE-OBJECT, and SBCL's compiler was
-substantially better than CMU CL's at optimizing operations on
-non-simple vectors.
+Maintenance work in SBCL since the fork has diverged somewhat from the
+maintenance work in CMU CL. Many but not all bug fixes and
+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 support,
-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 (\fIe.g.\fR \f(CRLETF\fR, \f(CRITERATE\fR, \f(CRMEMQ\fR,
+\f(CRREQUIRED\-ARGUMENT\fR), and many others.
-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 1.0.13 this is
+still 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:
.TP 3
\--
-things which might be in the new ANSI spec, e.g. weak pointers,
-finalization, foreign function interface to C, and Gray streams
+things which might be in the new ANSI spec, \fIe.g.\fR safe type
+declarations, weak pointers, finalization, foreign function
+interface to C, and Gray streams;
.TP 3
\--
things which are universally available in Unix scripting languages,
-e.g. RUN-PROGRAM and POSIX argv and getenv
+\fIe.g.\fR \f(CRRUN\-PROGRAM\fR and POSIX \f(CRargv\fR and \f(CRgetenv\fR;
.TP 3
\--
hooks into the low level workings of the system which can be useful
-for debugging, e.g. a list of functions to be run whenever GC occurs,
-or parameters to modify compiler diagnostic output
+for debugging, \fIe.g.\fR requesting that a particular function be executed
+whenever GC occurs, or tuning compiler diagnostic output;
.TP 3
\--
-unportable performance hacks, e.g. TRULY-THE, FREEZE-TYPE, and PURIFY
+unportable performance hacks, \fIe.g.\fR \f(CRFREEZE\-TYPE\fR and
+\f(CRPURIFY\fR. For more information about these, look at the online
+documentation for symbols in the \f(CRSB\-EXT\fR package, and look at the user
+manual.
.PP
-There are also a few retained extensions which don't fall into
-any particular category, e.g.
-.TP 3
-\--
-the ability to save running Lisp images as executable files
-.PP
+There are also a few retained extensions which don't fall into any
+particular category, \fIe.g.\fR the ability to save running Lisp images as
+executable files.
Some of the retained extensions have new names and/or different
options than their CMU CL counterparts. For example, the SBCL function
-which saves a Lisp image to disk and kills it is called
-SAVE-LISP-AND-DIE instead of SAVE-LISP, and it supports fewer keyword
-options than CMU CL's SAVE-LISP.
-
-(Why doesn't SBCL support more extensions? Why the hell did I (WHN)
-drop all those nice extensions from CMU CL when the code already
-exists? This is a frequently asked question on the mailing list. The
-answer is that they're hard to maintain, and I have enough on my hands
-already. Also, in the case of some big and unquestionably useful
-extensions, like sockets and Motif, I think that SBCL has done its job
-by supplying the FFI, and that people who need, and understand, and
-are motivated to maintain the functionality should supply it as a
-separate library, which I'd be happy to distribute or link to on the
-SBCL home page. Finally, in the case of multithreading, I do think it
-belongs in the new ANSI spec, and it'd be a good feature to have, but
-I didn't think the CMU CL implementation was sufficiently mature, and
-it's such a complicated and far-reaching extension that I thought that
-trying to fix it would interfere with the more urgent task of getting
-basic ANSI support up to speed.)
+which saves a Lisp image to disk and kills the running process is
+called \f(CRSAVE\-LISP\-AND\-DIE\fR instead of \f(CRSAVE\-LISP\fR, and
+SBCL's \f(CRSAVE\-LISP\-AND\-DIE\fR supports fewer keyword options
+than CMU CL's \f(CRSAVE\-LISP\fR does.
+
+(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 inherits from CMU CL the "Python" native code compiler. This
-compiler is very clever about understanding the type system of Common
-Lisp and using it to produce efficient 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
+SBCL inherits from CMU CL the "Python" native code compiler. (Though
+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", \fIi.e.\fR
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 machines 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, we find a
-typical performance decrease by a factor of perhaps 2 to 5 for small
-programs coded in SBCL instead of GCC.
+The compiled code uses garbage collection to automatically
+manage memory. The garbage collector implementation varies considerably
+from CPU to CPU. In particular, on some CPUs the GC is nearly exact,
+while on others it's more conservative, and on some CPUs the GC
+is generational, while on others simpler stop and copy strategies
+are used.
For more information about the compiler, see the user manual.
-.SH DOCUMENTATION
+.SH COMMAND LINE SYNTAX
-Currently, the documentation for the system is
-.TP 3
-\--
-the user manual
-.TP 3
-\--
-this man page
-.TP 3
-\--
-doc strings and online help built into the SBCL executable
-.PP
+Command line syntax can be considered an advanced topic; for ordinary
+interactive use, no command line arguments should be necessary.
-.SH SYSTEM REQUIREMENTS
+In order to understand the command line argument syntax for SBCL, it
+is helpful to understand that the SBCL system is implemented as two
+components, a low-level runtime environment written in C and a
+higher-level system written in Common Lisp itself. Some command line
+arguments are processed during the initialization of the low-level
+runtime environment, some command line arguments are processed during
+the initialization of the Common Lisp system, and any remaining
+command line arguments are passed on to user code.
-Unlike its distinguished ancestor CMU CL, SBCL is currently only
-supported on X86. Linux, FreeBSD, and OpenBSD ports are currently
-available. It would probably be straightforward to port the CMU CL
-support for SPARC or Alpha, or to port to NetBSD. Some work on a
-port to the Alpha has been reported on the mailing lists; check
-the archives (available from the home page at
-<http://sbcl.sourceforge.net/>) for information.
-
-As of version 0.6.11, SBCL requires on the order of 16Mb to run. In
-some future version, this number could shrink significantly, since
-large parts of the system are far from execution bottlenecks and could
-reasonably be stored in compact byte compiled form. (CMU CL does this
-routinely; the only reason SBCL doesn't currently do this is a
-combination of bootstrapping technicalities and inertia.)
+The full, unambiguous syntax for invoking SBCL at the command line is
+.TP 3
+.B sbcl [runtime options] \-\-end\-runtime\-options [toplevel options] \-\-end\-toplevel\-options [user options]
+.PP
-.SH ENVIRONMENT
+For convenience, the \-\-end\-runtime\-options and \-\-end\-toplevel\-options
+elements can be omitted. Omitting these elements can be convenient
+when you are running the program interactively, and you can see that
+no ambiguities are possible with the option values you are using.
+Omitting these elements is probably a bad idea for any batch file
+where any of the options are under user control, since it makes it
+impossible for SBCL to detect erroneous command line input, so that
+erroneous command line arguments will be passed on to the user program
+even if they was intended for the runtime system or the Lisp system.
-.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.
+Supported runtime options are
+.TP 3
+.B \-\-core <corefilename>
+Run the specified Lisp core file instead of the default. (See the FILES
+section for the standard core, or the system documentation for
+\f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR 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 \-\-dynamic-space-size <megabytes>
+Size of the dynamic space reserved on startup in megabytes. Default value
+is platform dependent.
+.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
-.SH FILES
+In the future, runtime options may be added to control behavior such
+as lazy allocation of memory.
-/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.
+Runtime options, including any \-\-end\-runtime\-options option,
+are stripped out of the command line before the
+Lisp toplevel logic gets a chance to see it.
-/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.
+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.
+(See the FILES section.)
+.TP 3
+.B \-\-no\-sysinit
+Do not load a system-wide initialization file. If this option is
+given, the \-\-sysinit option is ignored.
+.TP 3
+.B \-\-userinit <filename>
+Load filename instead of the default user initialization file. (See
+the FILES section.)
+.TP 3
+.B \-\-no\-userinit
+Do not load a user initialization file. If this option is
+given, the \-\-userinit option is ignored.
+.TP 3
+.B \-\-eval <command>
+After executing any initialization file, but before starting the
+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 \(aq(load "<filename>")\(aq. The special
+syntax is intended to reduce quoting headaches when invoking SBCL
+from shell scripts.
+.TP 3
+.B \-\-noprint
+When ordinarily the toplevel "read-eval-print loop" would be executed,
+execute a "read-eval loop" instead, \fIi.e.\fR don't print a prompt and
+don't echo results. Combined with the \-\-noinform runtime option, this
+makes it easier to write Lisp "scripts" which work cleanly in Unix
+pipelines.
+.TP 3
+.B \-\-disable\-debugger
+This is equivalent to \-\-eval \(aq(sb\-ext:disable\-debugger)\(aq. 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 \f(CR*DEBUG\-IO*\fR). 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 \f(CRINVOKE\-DEBUGGER\fR so that any call exits the process with a
+failure code after printing a backtrace. (Note that because it is
+implemented by modifying special variables and \f(CRFDEFINITION\fRs, its
+effects persist in .core files created by
+\f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR. If you want to undo its
+effects, \fIe.g.\fR if you build a system unattended and then want to
+operate a derived system interactively, see the
+\f(CRSB\-EXT:ENABLE\-DEBUGGER\fR 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 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 \f(CRSB\-EXT:QUIT\fR 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
+\f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR, the toplevel options may be
+under the control of user code passed as arguments to
+\f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR. For this purpose, the
+\-\-end\-toplevel\-options option itself can be considered a toplevel
+option, \fIi.e.\fR the user core, at its option, may not support it.
+
+In the standard SBCL startup sequence (\fIi.e.\fR with no user core
+involved) toplevel options and any \-\-end\-toplevel\-options option are
+stripped out of the command line argument list before user code gets a
+chance to see it.
-$HOME/.sbclrc is the standard location for a user's SBCL
-initialization file, unless overridden by the --userinit
-command line option.
+.SH SYSTEM REQUIREMENTS
-.SH BUGS
+SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD),
+X86-64 (Linux), 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.
-To report a bug, please send mail to sbcl-help@lists.sourceforge.net
-or sbcl-devel@lists.sourceforge.net. As with any software bug report,
-it's most helpful if you remember to describe the environment where
-the problem occurs (machine type, O/S name and version, etc.) and if
-you can provide enough information to reproduce the problem,
-preferably in compact form.
+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.
-This section attempts to list the most serious and long-standing bugs
-or surprising performance hits. For more detailed and current
-information on bugs, see the BUGS file in the distribution.
+.SH KNOWN BUGS
-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
-\--
-The system doesn't deal well with stack overflow.
-.TP 3
-\--
-The SBCL system overcommits memory at startup. On typical Unix-alikes
-like Linux and *BSD, this means that if the SBCL system turns out to
-use more virtual memory than the system has available for it, other
-processes to be killed randomly (!)
-.PP
+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.
-The compiler is overaggressive about static typing, assuming that a
-function's return type never changes. Thus compiling and loading a
-file containing
-(DEFUN FOO (X) NIL)
-(DEFUN BAR (X) (IF (FOO X) 1 2))
-(DEFUN FOO (X) (PLUSP X))
-then running (FOO 1) gives 2 (because the compiler "knew"
-that FOO's return type is NULL).
+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
-adheres to. Using PROCLAIM or DECLAIM to specify the return type of a
-function causes the compiler to believe you without checking. Thus
-compiling a file containing
-(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.
-
-The implementation of multidimensional arrays, especially
-multidimensional arrays of floating point numbers, is very
-inefficient.
-
-SYMBOL-FUNCTION is much slower than you might expect, being
-implemented not as a slot access but as a search through the
-compiler/kernel "globaldb" database.
-
-CLOS (based on the PCL reference implementation) is somewhat
-inefficient.
-
-There are many nagging pre-ANSIisms, e.g.
+adheres to. Using \f(CRPROCLAIM\fR or \f(CRDECLAIM\fR to specify the
+return type of a function causes the compiler to believe you without
+checking. Thus compiling a file containing
+\f(CR
+ (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
+ (DEFUN SOMETIMES (X) (ODDP X))
+ (DEFUN FOO (X) (IF (SOMETIMES X) \(aqTHIS\-TIME \(aqNOT\-THIS\-TIME))\fR
+.br
+then running \f(CR(FOO 1)\fR gives \f(CRNOT\-THIS\-TIME\fR, because
+the compiler relied on the truth of the \f(CRDECLAIM\fR without checking it.
+
+Some things are implemented very inefficiently.
.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. (This is less of a problem in
-practice than the speed, but it's still distasteful.)
-.TP 3
---
-The ANSI-recommended idiom for creating a function which is only
-sometimes expanded inline,
-(DECLAIM (INLINE F))
-(DEFUN F ...)
-(DECLAIM (NOTINLINE F)),
-doesn't do what you'd expect. (Instead, you have to declare the
-function as SB-EXT:MAYBE-INLINE to get the desired effect.)
+Multidimensional arrays are inefficient, especially
+multidimensional arrays of floating point numbers.
.TP 3
\--
-The DYNAMIC-EXTENT declaration is not implemented, and is simply
-ignored. (This is allowed by the ANSI spec, but can have a large
-efficiency cost in some kinds of code, e.g. code which uses a lot
-of upward closures or &REST lists.)
-.TP 3
---
-Compiling DEFSTRUCT in strange places (e.g. inside a DEFUN) doesn't
-do anything like what it should.
+CLOS isn't particularly efficient. (In part, CLOS is so dynamic
+that it's slow for fundamental reasons, but beyond that, the
+SBCL implementation of CLOS doesn't do some important known
+optimizations.)
.TP 3
\--
-The symbol * is the name of a type similar to T. (It's used as part of
-the implementation of compound types like (ARRAY * 1) and (CONS * *).
-In a strict ANSI implementation, * would not be the name of a type,
-but instead just a symbol which is recognized and handled specially by
-certain type expanders.)
+SBCL, like most (maybe all?) implementations of Common Lisp on stock
+hardware, has trouble passing floating point numbers around
+efficiently, because a floating point number, plus a few extra bits to
+identify its type, is larger than a machine word. (Thus, they get
+"boxed" in heap-allocated storage, causing GC overhead.) Within a
+single compilation unit, or when doing built-in operations like
+\f(CRSQRT\fR and \f(CRAREF\fR, or some special operations like
+structure slot accesses, this is avoidable: see the user manual for
+some efficiency hints. But for general function calls across the
+boundaries of compilation units, passing the result of a floating
+point calculation as a function argument (or returning a floating
+point result as a function value) is a fundamentally slow operation.
.PP
+.SH REPORTING BUGS
+
+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 at <\f(CRhttp://sbcl.sourceforge.net/\fR>; note that as a
+spam reduction measure you must subscribe to the lists before you can
+post. (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 it off.)
+
+As with any software bug report, it's most helpful if you can provide
+enough information to reproduce the symptoms reliably, and if you say
+clearly what the symptoms are. For example, "There seems to be
+something wrong with TAN of very small negative arguments. When I
+execute \f(CR(TAN LEAST\-NEGATIVE\-SINGLE\-FLOAT)\fR interactively on
+sbcl-1.2.3 on my Linux 4.5 X86 box, I get an \f(CRUNBOUND\-VARIABLE\fR
+error."
+
.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.
+<\f(CRhttp://www.sbcl.org/\fR>. The mailing lists there are the recommended
+place to look for support.
-.SH DISTRIBUTION
+.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 \fIe.g.\fR by a third-party
+packager.
-SBCL is a free implementation of Common Lisp derived from CMU CL. Both
-sources and executables are freely available; this software is "as
-is", and has no warranty of any kind. CMU and the authors assume no
-responsibility for the consequences of any use of this software. See
-the CREDITS file in the distribution for more information about
-history, contributors and permissions.
+.SH FILES
+.TP
+.I sbcl
+executable program containing some low-level runtime support and
+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. Looked for in $\f(CRSBCL_HOME\fR,
+unless overridden by the \f(CR\-\-core\fR option.
+.TP
+.I sbclrc
+optional system-wide startup script, looked for in $\f(CRSBCL_HOME\fR/sbclrc
+then /etc/sbclrc, unless overridden by the \f(CR\-\-sysinit\fR command line
+option.
+.TP
+.I .sbclrc
+optional per-user customizable startup script (in user's home
+directory, or as specified by \f(CR\-\-userinit\fR)
+
+.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 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 <\f(CRhttp://www.sbcl.org/\fR>
+.PP
+for more information, including directions on how to subscribe to the
+sbcl\-devel and sbcl\-help mailing-lists.
projects / sbcl.git / blobdiff