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
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
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
-
-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.
+.SH KNOWN BUGS
-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.
+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
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 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, 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 sbcl-help@lists.sourceforge.net
+or sbcl-devel@lists.sourceforge.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
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 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