.\" 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
acknowledge the connection: steel and banking are the industries where
Carnegie and Mellon made the big bucks.)
+.SH LICENSING
+
+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" 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 ("*"). 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. E.g.
+
+ * (+ 1 2 3)
+
+ 6
+ * (funcall (lambda (x y) (list x y y)) :toy :choo)
+
+ (:TOY :CHOO :CHOO)
+ * "Hello World"
+
+ "Hello World"
+ *
+
+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.
+
+.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 yet reached compliance with the ANSI
+standard for Common Lisp. More information on this is available in the
+BUGS section below.
+
+SBCL also includes various non-ANSI extensions.
+
+Many Lispy extensions have been retained from CMU CL:
+.TP 3
+\--
+CMU-CL-style safe implementation of type declarations:
+"Declarations are assertions."
+.TP 3
+\--
+the source level debugger (very similar to CMU CL's)
+.TP 3
+\--
+the profiler (now somewhat different from CMU CL's)
+.TP 3
+\--
+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
+\--
+weak pointers and finalization (which have unfortunately
+suffered from at least some code rot, so that e.g. weak hash
+tables don't work)
+.PP
+
+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, e.g. reading POSIX argc and argv, 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
+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 are not supported in 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.
+
+SBCL has retained some extensions from 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. 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
+.TP 3
+\--
+hooks into the low level workings of the system which can be useful
+for debugging, e.g. requesting that a particular function be executed
+whenever GC occurs, or tuning compiler diagnostic output
+.TP 3
+\--
+unportable performance hacks, e.g. FREEZE-TYPE and PURIFY. For more
+information about these, look at the online documentation for symbols
+in the SB-EXT 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. 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 the running process is
+called SAVE-LISP-AND-DIE instead of SAVE-LISP, and SBCL's
+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 other 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.)
+
+.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
+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 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
+\--
+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
the initialization of the Common Lisp system, and any remaining
command line arguments are passed on to user code.
-The full, unambiguous syntax for SBCL is
+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
.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.
+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.)
+Unix pipelines. See also the "--noprogrammer" and "--noprint" options.)
.PP
In the future, runtime options may be added to control behavior such
Supported toplevel options for 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.
+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.
.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.
+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.
.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, 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.
+.TP 3
+.B --load <filename>
+This is equivalent to --eval '(load "<filename>")'. 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, 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.)
+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.
.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.)
+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.
.PP
Regardless of the order in which --sysinit, --userinit, and --eval
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.
+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.
-
-.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
-bootstrappability was the immediate motivation for forking off of the
-CMU CL development tree.)
-
-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.
-
-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
-
-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
-.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
-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.
-
-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.
+Unlike its distinguished ancestor CMU CL, SBCL currently runs only on
+X86 (Linux, FreeBSD, and OpenBSD), Alpha (Linux), and SPARC (Linux).
+For information on other ongoing and possible ports, see the
+sbcl-devel mailing list, and/or the web site.
-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 requires on the order of 16Mb RAM to run on X86 systems.
.SH ENVIRONMENT
/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_HOME variable or the --sysinit command line option.
$HOME/.sbclrc is the standard location for a user's SBCL
-initialization file.
+initialization file, unless overridden by the --userinit
+command line option.
-.SH BUGS
+.SH KNOWN BUGS
-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.
+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
yourself in the foot, but when you do, the entire universe explodes."
.TP 3
\--
-The system doesn't deal well with stack overflow.
+The system doesn't deal well with stack overflow. (It tends to cause
+a segmentation fault instead of being caught cleanly.)
.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.
+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
-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
then running (FOO 1) gives NOT-THIS-TIME, because the
never compiled code to check the declaration.
-The TRACE facility can't be used on some kinds of functions.
-
-The profiler is flaky, e.g. sometimes it fails by throwing a
-signal instead of giving you a result.
-
-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.
-
-CLOS (based on the PCL reference implementation) is quite slow.
+Some things are implemented very inefficiently.
+.TP 3
+\--
+Multidimensional arrays are inefficient, especially
+multidimensional arrays of floating point numbers
+.TP 3
+\--
+The DYNAMIC-EXTENT declaration isn't implemented at all, not even
+for &REST lists or upward closures, so such constructs always allocate
+their temporary storage from the heap, causing GC overhead.
+.TP 3
+\--
+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
+\--
+SBCL, like most implementations of Common Lisp, has trouble
+passing floating point numbers around efficiently, because
+they're 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 SQRT and AREF,
+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 a floating point
+number as a function argument (or returning a floating point
+number as a function value) is a fundamentally slow operation.
+.PP
-There are many nagging pre-ANSIisms, e.g.
+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. (This is less of a problem in
-practice than the speed, but it's still distasteful.)
+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
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).)
+There are several nonconforming bits of type syntax. E.g. (1) The type
+FOO is strictly equivalent to (FOO), so e.g. the type OR is treated as
+the type (OR), i.e. the empty type. This is the way that the ancestral
+code worked, and even though ANSI specifically forbids it, it hasn't
+been fixed yet. (2) 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.)
.PP
-.SH SUPPORT
+.SH REPORTING BUGS
+
+To report a bug, please send mail to sbcl-help@lists.sourceforge.net
+or sbcl-devel@lists.sourceforge.net.
-Please send bug reports or other information to
-<william.newman@airmail.net>.
+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. E.g. "There seems to be something wrong
+with TAN of very small negative arguments. When I execute
+(TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively on sbcl-1.2.3 on my Linux
+4.5 X86 box, I get an UNBOUND-VARIABLE error."
+
+.SH SUPPORT
-.SH DISTRIBUTION
+Various information about SBCL is available at
+<http://sbcl.sourceforge.net/>. The mailing lists there are the
+recommended place to look for support.
-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 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.
projects / sbcl.git / blobdiff