.\" 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.
.\"
-.\" $Header$
-.\" FIXME: The date below should be $Date$.
.TH SBCL 1 "$Date$"
.AT 3
.SH NAME
-SBCL -- "Steel Bank Common Lisp"
+SBCL -- Steel Bank Common Lisp
.SH DESCRIPTION
-SBCL is a free Common Lisp programming environment. It is derived from
-the free CMU CL programming environment. (The name is intended to
-acknowledge the connection: steel and banking are the industries where
-Carnegie and Mellon made the big bucks.)
+SBCL is an implementation of ANSI Common Lisp, featuring a
+high-performance native compiler, native threads on several platforms,
+a socket interface, a source-level debugger, a statistical profiler,
+and much more.
+
+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.
+
+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.
+
+.SH RUNNING SBCL
+
+To run SBCL, type "sbcl". After startup messages a prompt
+("\f(CR*\fR") appears. Enter a Lisp expression, and SBCL will read and
+execute it, print any values returned, give you another prompt, and
+wait for your next input.
+
+\f(CR
+ $ sbcl
+ ...[startup messages elided]...
+ * (+ 1 2 3)
+
+ 6
+ * (exit)
+\fR
+
+Most people like to run SBCL as a subprocess under Emacs. The Emacs
+"Slime" 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.
+
+For information on creating "standalone executables" using SBCL, see
+\f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR in the User Manual.
.SH COMMAND LINE SYNTAX
-Command line syntax can be considered an advanced topic; for ordinary
-interactive use, no command line arguments should be necessary.
+For ordinary interactive use, no command line arguments should be
+necessary.
-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
+In order to understand the SBCL command line syntax, it is helpful to
+understand that the system is composed of two parts: a runtime
+environment, and the Common Lisp system it supports. Some command line
+arguments are processed during the initialization of the runtime, and
+some during the initialization of the Lisp system -- any remaining
command line arguments are passed on to user code.
-The full, unambiguous syntax for SBCL is
+The overall command line syntax is:
.TP 3
-.B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]
+.B sbcl [runtime options] \-\-end\-runtime\-options [toplevel options] \-\-end\-toplevel\-options [user options]
.PP
-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.
+Both \-\-end\-runtime\-options and \-\-end\-toplevel\-options are
+optional, and may be omitted. They are intended for use in situations
+where any command line options are under user control (e.g. in batch
+files): by using them you can prevent options intended for your
+program being accidentally processed by SBCL.
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 accept the standard toplevel options.
+.B \-\-core <corefilename>
+Use 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
+.B \-\-control-stack-size <megabytes>
+Size of control stack reserved for each thread in megabytes. Default value
+is 2.
+.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.)
+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 \-\-disable\-ldb
+Disable the low-level debugger. Only effective if SBCL is compiled with LDB.
+.TP 3
+.B \-\-lose\-on\-corruption
+There are some dangerous low level errors (for instance, control stack
+exhausted, memory fault) that (or whose handlers) can corrupt the
+image. By default SBCL prints a warning, then tries to continue and
+handle the error in Lisp, but this will not always work and SBCL may
+malfunction or even hang. With this option, upon encountering such an
+error SBCL will invoke ldb (if present and enabled) or else exit.
+.TP 3
+.B \-\-script <filename>
+As a runtime option equivalent to \-\-noinform \-\-disable\-ldb
+\-\-lose\-on\-corruption \-\-end\-runtime\-options \-\-script
+<filename>. See the description of \-\-script as a toplevel option
+below.
+.TP 3
+.B \-\-merge\-core\-pages
+When platform support is present, provide hints to the operating
+system that identical pages may be shared between processes until they
+are written to. This can be useful to reduce the memory usage on
+systems with multiple SBCL processes started from similar but
+differently\-named core files, or from compressed cores. Without
+platform support, do nothing.
+.TP 3
+.B \-\-no-merge\-core\-pages
+Ensures that no sharing hint is provided to the operating system.
+.TP 3
+.B \-\-default\-merge\-core\-pages
+Reverts the sharing hint policy to the default: only compressed cores
+trigger hinting. Uncompressed cores are mapped directly from the core
+file, which is usually enough to ensure sharing.
+.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
as lazy allocation of memory.
-Runtime options, including any --end-runtime-options option,
+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.
-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. (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.
+.B \-\-sysinit <filename>
+Load filename instead of the default system-wide initialization file.
+(See the FILES section.)
.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.
+.B \-\-no\-sysinit
+Do not load a system-wide initialization file. If this option is
+given, the \-\-sysinit option is ignored.
.TP 3
-.B --eval <command>
+.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,
-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 --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.)
+.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 --noprogrammer
-Ordinarily the system initializes *DEBUG-IO* to *TERMINAL-IO*.
-When the --notty option is set, however, *DEBUG-IO* is instead
-set to a stream which sends its output to *ERROR-OUTPUT* and
-which raises an error on input. As a result, any attempt by the
-program to get programmer feedback through the debugger
-causes an error which abnormally terminates the entire
-Lisp environment. (This can be useful behavior for programs
-which are to run without programmer supervision.)
-.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 from 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.
+.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
+By default when SBCL encounters an error, it enters the builtin
+debugger, allowing interactive diagnosis and possible intercession.
+This option disables the debugger, causing errors to print a backtrace
+and exit with status 1 instead -- which is a mode of operation better suited
+for batch processing. See the User Manual on \f(CRSB\-EXT:DISABLE\-DEBUGGER\fR for details.
+.TP 3
+.B \-\-quit
+At the end of toplevel option processing, exit SBCL with a successful
+code of zero. Note that the effect of this option is delayed until after
+toplevel options following this one.
+.TP 3
+.B \-\-non-interactive
+This option disables the read-eval-print loop for both exceptional and
+non-exceptional reasons. It is short for --disable-debugger and --quit in
+combination and is useful for batch uses where the special option processing
+implied by --script is not desired.
+.TP 3
+.B \-\-script <filename>
+Implies \-\-no-sysinit \-\-no-userinit \-\-disable-debugger
+\-\-end\-toplevel\-options.
-SBCL compiles Lisp to native code, or optionally to more-compact but
-much slower byte code.
+Causes the system to load the specified file and exit immediately
+afterwards, instead of entering the read-eval-print loop. If the file
+begins with a shebang line, it is ignored.
+.PP
-SBCL's garbage collector is generational and conservative.
+Regardless of the order in which toplevel options appear on the command
+line, the order of actions is:
+
+.nr step 1 1
+.IP \n[step]. 3
+Debugger is disabled, if requested.
+.IP \n+[step].
+Any system initialization file is loaded, unless prohibited.
+.IP \n+[step].
+Any user initialization file is loaded, unless prohibited.
+.IP \n+[step].
+\-\-eval and \-\-load options are processed in the order given.
+.PP
-SBCL includes a source level debugger, as well as the ANSI TRACE
-facility and a rudimentary profiler.
+Finally, either the read-eval-print loop is entered or the file
+specified with \-\-script option is loaded.
-.SH DIFFERENCES FROM CMU CL
+When running in the read-eval-print loop the system exits on end of
+file. Similarly, the system exits immediately after processing the
+file specified with \-\-script.
-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
-bootstrappability was the immediate motivation for forking off of the
-CMU CL development tree.)
+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.
-Many extensions supported by CMU CL, like Motif support,
-the Hemlock editor, search paths, the WIRE protocol, various
-user-level macros and functions (e.g. LETF, ITERATE, MEMQ,
-REQUIRED-ARGUMENT), and many others.
+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.
-SBCL has retained some extensions of its parent CMU CL. Many
-of them are in three categories:
-.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 an operator to cause a particular string to be compiled into a fasl
-file)
-.TP 3
-\--
-non-portable performance hacks (e.g. PURIFY, which causes
-everything currently in existence to become immune to GC)
-.TP 3
-\--
-things which might be in the new ANSI spec (e.g. weak pointers,
-finalization, foreign function interface to C, and Gray streams)
-.PP
+.SH OVERVIEW
-There are also various retained extensions which don't fall into
-any particular category, e.g.
-.TP 3
-\--
-the ability to save running Lisp images as executable files
+SBCL is derived from the CMU CL. (The name is intended to acknowledge
+the connection: steel and banking are the industries where Carnegie
+and Mellon made the big bucks.)
+
+SBCL compiles by default: even functions entered in the
+read-eval-print loop are compiled to native code, unless the evaluator
+has been explicitly turned on. (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
+
+For more information, see the User Manual.
.PP
-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.
-
.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
-
-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
-
.SH SYSTEM REQUIREMENTS
-Unlike its distinguished ancestor CMU CL, SBCL is currently only
-supported on X86. Linux and FreeBSD are currently available. It would
-probably be straightforward to port the CMU CL support for Alpha or
-SPARC as well, or to OpenBSD or NetBSD, but at the time of this
-writing no such efforts are underway.
-
-As of version 0.6.3, 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.)
+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.
-.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.
+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.
-$HOME/.sbclrc is the standard location for a user's SBCL
-initialization file.
+.SH KNOWN BUGS
-.SH 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.
-Too numerous to list, alas. This section attempts to list the most
-serious known bugs, and a reasonably representative sampling of
-others. For more information on bugs, see the BUGS file in the
-distribution.
+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 (!).
-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."
+The compiler's handling of function return values unnecessarily
+violates the "declarations are assertions" principle that it otherwise
+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
\--
-The system doesn't deal well with stack overflow.
+Multidimensional arrays are inefficient, especially
+multidimensional arrays of floating point numbers.
.TP 3
\--
-The SBCL system overcommits memory at startup. On typical Unix-alikes
-like Linux and *BSD, this can cause other processes to be killed
-randomly (!) if the SBCL system turns out to use more virtual memory
-than the system has available for it.
+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
-The facility for dumping a running Lisp image to disk gets confused
-when run without the PURIFY option, and creates an unnecessarily large
-core file (apparently representing memory usage up to the previous
-high-water mark). Moreover, when the file is loaded, it confuses the
-GC, so that thereafter memory usage can never be reduced below that
-level.
-
-By default, 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).
-
-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.
+.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."
-The TRACE facility can't be used on some kinds of functions.
+.SH DIFFERENCES FROM CMU CL
-The profiler is flaky, e.g. sometimes it fails by throwing a
-signal instead of giving you a result.
+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
+bootstrappability was the immediate motivation for forking off of the
+CMU CL development tree. A variety of implementation differences are
+motivated by this design goal.
+
+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 have been unbundled from SBCL,
+including Motif support, the Hemlock editor, search paths, 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.
+
+(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.)
-SYMBOL-FUNCTION is much slower than you'd expect, being implemented
-not as a slot access but as a search through the compiler/kernel
-"globaldb" database.
+.SH SUPPORT
-CLOS (based on the PCL reference implementation) is quite slow.
+Various information about SBCL is available at
+<\f(CRhttp://www.sbcl.org/\fR>. The mailing lists there are the recommended
+place to look for support.
-There are many nagging pre-ANSIisms, e.g.
-.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.)
-.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.)
-.TP 3
---
-Compiling DEFSTRUCT in strange places (e.g. inside a DEFUN) doesn't
-do anything like what it should.
-.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).)
-.PP
+.SH AUTHORS
-.SH SUPPORT
+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.
-Please send bug reports or other information to
-<william.newman@airmail.net>.
+.SH ENVIRONMENT
-.SH DISTRIBUTION
+.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 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 e.g.
+.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