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 about 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
.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 "--noprogrammer" and "--noprint" options.)
+startup. (This makes it easier to write Lisp programs which work
+cleanly in Unix pipelines. See also the "--noprint" and
+"--disable-debugger" options.)
.PP
In the future, runtime options may be added to control behavior such
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.
+makes it easier to write Lisp "scripts" which work cleanly in Unix
+pipelines.
.TP 3
-.B --noprogrammer
+.B --disable-debugger
+This is equivalent to --eval '(sb-ext:disable-debugger)'.
By default, a Common Lisp system tries to ask the programmer for help
when it gets in trouble (by printing a debug prompt on *DEBUG-IO*).
However, this is not useful behavior for a system running with no
programmer available, and this option tries to set up more appropriate
-behavior for that situation. 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.
+behavior for that situation. This is implemented by modifying special
+variables: we set *DEBUG-IO* to send its output to *ERROR-OUTPUT*, and
+to raise an error if any input is requested from it, and we set
+*DEBUGGER-HOOK* to output a backtrace, then exit the process with a
+failure code. Because it is implemented by modifying special variables,
+its effects persist in .core files created by SB-EXT:SAVE-LISP-AND-DIE.
+(If you want to undo its effects, see the SB-EXT:ENABLE-DEBUGGER
+command.)
.PP
Regardless of the order in which --sysinit, --userinit, and --eval
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.) A variety of internal implementation
-differences are motivated by this.
-
-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.
-
-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 support,
-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. 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. a list of functions to be run whenever GC occurs,
-or parameters to modify compiler diagnostic output
-.TP 3
-\--
-unportable performance hacks, e.g. TRULY-THE, FREEZE-TYPE, and PURIFY
-.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
-
-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.)
-
-.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 on X86
-(Linux, FreeBSD, and OpenBSD) and Alpha (Linux). It would probably be
-straightforward to port the CMU CL support for SPARC, or to port to
-NetBSD.
+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.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.)
+SBCL requires on the order of 16Mb RAM to run on X86 systems.
.SH ENVIRONMENT
system-wide SBCL initialization files, unless overridden by the
SBCL_HOME variable or the --sysinit command line option.
-
$HOME/.sbclrc is the standard location for a user's SBCL
initialization file, unless overridden by the --userinit
command line option.
-.SH BUGS
+.SH KNOWN BUGS
-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.
+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.
-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.
-
-It is possible to get in deep trouble by exhausting
+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. (It tends to cause
-a segmentation fault instead of being caught cleanly.)
-.TP 3
-\--
Like CMU CL, the SBCL system overcommits memory at startup. On typical
Unix-alikes like Linux and FreeBSD, this means that if the SBCL system
turns out to use more virtual memory than the system has available for
it, other processes tend to be killed randomly (!).
.PP
-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 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.
+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 (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 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 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
-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, 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.
-.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.)
+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 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, <http://sbcl.sourceforge.net/>. (You may also find fancy
+SourceForge bug-tracking machinery there, but don't be fooled. As of
+2002-07-25 anyway, we don't actively monitor that machinery and just
+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. 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
Various information about SBCL is available at
<http://sbcl.sourceforge.net/>. The mailing lists there are the
recommended place to look for support.
-.SH DISTRIBUTION
-
-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
+.TP
+.I sbclrc
+optional system-wide startup script (in an etc-ish system
+configuration file directory)
+.TP
+.I .sbclrc
+optional per-user customizable startup script (in user's home directory)
+
+.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