+@node Introduction
+@comment node-name, next, previous, up
+@chapter Introduction
+
SBCL is a mostly-conforming implementation of the ANSI Common Lisp
standard. This manual focuses on behavior which is specific to SBCL,
not on behavior which is common to all implementations of ANSI Common
Lisp.
@menu
-* More Common Lisp Information::
+* ANSI Conformance::
+* Extensions::
+* Idiosyncrasies::
+* Development Tools::
* More SBCL Information::
-* Overview::
+* More Common Lisp Information::
+* History and Implementation of SBCL::
@end menu
-@node More Common Lisp Information
+
+
+@node ANSI Conformance
@comment node-name, next, previous, up
-@section Sources of information about Common Lisp
+@section ANSI Conformance
-Regardless of your ability level, two very useful resources for
-working with any implementation of Common Lisp are the SLIME
-package@footnote{Historically, the ILISP package at
-@uref{http://ilisp.cons.org/} provided similar functionality, but it
-does not support modern SBCL versions.} for Emacs at
-@uref{http://www.common-lisp.net/project/slime} and the Common Lisp
-HyperSpec at
-@uref{http://www.lispworks.com/reference/HyperSpec/index.html}.
+Essentially every type of non-conformance is considered a bug. (The
+exceptions involve internal inconsistencies in the standard.)
+@xref{Reporting Bugs}.
-If you're not a programmer and you're trying to learn, many
-introductory Lisp books are available. However, we don't have any
-standout favorites. If you can't decide, try checking the Usenet
-@uref{news://comp.lang.lisp} FAQ for recent recommendations.
+@node Extensions
+@comment node-name, next, previous, up
+@section Extensions
-If you are an experienced programmer in other languages but need to
-learn about Lisp, three books stand out.
+SBCL comes with numerous extensions, some in core and some in modules
+loadable with @code{require}. Unfortunately, not all of these
+extensions have proper documentation yet.
-@itemize
+@c FIXME: Once bits and pieces referred to here get real documentation
+@c add xrefs there.
+
+@table @strong
-@item
-@emph{ANSI Common Lisp}, by Paul Graham, will teach you
-about most of the language. (And later it might also be worth checking
-out @emph{On Lisp}, by the same author.)
+@item System Definition Tool
+@code{asdf} is a flexible and popular protocol-oriented system
+definition tool by Daniel Barlow. @inforef{Top,the asdf manual,asdf}, for
+more information.
-@item
-@emph{Paradigms Of Artificial Intelligence
-Programming}, by Peter Norvig, also has some good information on
-general Common Lisp programming, and many nontrivial examples.
-Whether or not your work is AI, it's a very good book to look at.
-
-@item
-Neither of the books above emphasizes CLOS, but @emph{Object-Oriented
-Programming In Common Lisp} by Sonya Keene does. Even if you're very
-knowledgeable about object oriented programming in the abstract, it's
-worth looking at this book if you want to do any OO in Common
-Lisp. Some abstractions in CLOS (especially multiple dispatch) go
-beyond anything you'll see in most OO systems, and there are a number
-of lesser differences as well. This book tends to help with the
-culture shock.
+@item Third-party Extension Installation Tool
+@code{asdf-install} is a tool that can be used to download and install
+third-party libraries and applications, automatically handling
+dependencies, etc.
-@end itemize
+@item Foreign Function Interface
+@code{sb-alien} package allows interfacing with C-code, loading shared
+object files, etc. @xref{Foreign Function Interface}.
+@code{sb-grovel} can be used to partially automate generation of
+foreign function interface definitions. @xref{sb-grovel}.
-@node More SBCL Information
+@item Recursive Event Loop
+SBCL provides a recursive event loop (@code{serve-event}) for doing
+non-blocking IO on multiple streams without using threads.
+
+@item Metaobject Protocol
+@code{sb-mop} package provides a metaobject protocol for the Common
+Lisp Object System as described in @cite{Art of Metaobject Protocol}.
+
+@item Extensible Sequences
+SBCL allows users to define subclasses of the @code{sequence}
+class. @xref{Extensible Sequences}.
+
+@item Native Threads
+SBCL has native threads on x86/Linux, capable of taking advantage
+of SMP on multiprocessor machines. @xref{Threading}.
+
+@item Network Interface
+@code{sb-bsd-sockets} is a low-level networking interface, providing
+both TCP and UDP sockets. @xref{Networking}.
+
+@item Introspective Facilities
+@code{sb-introspect} module offers numerous introspective extensions,
+including access to function lambda-lists and a cross referencing
+facility.
+
+@item Operating System Interface
+@code{sb-ext} contains a number of functions for running external
+processes, accessing environment variables, etc.
+
+@code{sb-posix} module provides a lispy interface to standard POSIX
+facilities.
+
+@item Extensible Streams
+@code{sb-gray} is an implementation of @emph{Gray Streams}. @xref{Gray
+Streams}.
+
+@code{sb-simple-streams} is an implementation of the @emph{simple
+streams} API proposed by Franz Inc. @xref{Simple Streams}.
+
+@item Profiling
+@code{sb-profile} is a exact per-function profiler. @xref{Deterministic
+Profiler}.
+
+@code{sb-sprof} is a statistical profiler, capable of call-graph
+generation and instruction level profiling, which also supports
+allocation profiling. @xref{Statistical Profiler}.
+
+@item Customization Hooks
+SBCL contains a number of extra-standard customization hooks that
+can be used to tweak the behaviour of the system. @xref{Customization
+Hooks for Users}.
+
+@code{sb-aclrepl} provides an Allegro CL -style toplevel for SBCL,
+as an alternative to the classic CMUCL-style one. @xref{sb-aclrepl}.
+
+@item CLTL2 Compatibility Layer
+@code{sb-cltl2} module provides @code{compiler-let} and environment
+access functionality described in @cite{Common Lisp The Language, 2nd
+Edition} which were removed from the language during the ANSI
+standardization process.
+
+@item Executable Delivery
+The @code{:executable} argument to @ref{Function
+sb-ext:save-lisp-and-die} can produce a `standalone' executable
+containing both an image of the current Lisp session and an SBCL
+runtime.
+
+@item Bitwise Rotation
+@code{sb-rotate-byte} provides an efficient primitive for bitwise
+rotation of integers, an operation required by e.g. numerous
+cryptographic algorithms, but not available as a primitive in ANSI
+Common Lisp. @xref{sb-rotate-byte}.
+
+@item Test Harness
+@code{sb-rt} module is a simple yet attractive regression and
+unit-test framework.
+
+@item MD5 Sums
+@code{sb-md5} is an implementation of the MD5 message digest algorithm
+for Common Lisp, using the modular arithmetic optimizations provided
+by SBCL. @xref{sb-md5}.
+
+@end table
+
+
+
+
+@node Idiosyncrasies
+@comment node-name, next, previous, up
+@section Idiosyncrasies
+
+The information in this section describes some of the ways that SBCL
+deals with choices that the ANSI standard leaves to the
+implementation.
+
+@menu
+* Declarations::
+* FASL Format::
+* Compiler-only Implementation::
+* Defining Constants::
+* Style Warnings::
+@end menu
+
+@node Declarations
@comment node-name, next, previous, up
-@section Sources of more information about SBCL
+@subsection Declarations
+
+Declarations are generally treated as assertions. This general
+principle, and its implications, and the bugs which still keep the
+compiler from quite satisfying this principle, are discussed in
+@ref{Declarations as Assertions}.
+
+
+@node FASL Format
+@comment node-name, next, previous, up
+@subsection FASL Format
+
+SBCL fasl-format is binary compatible only with the exact SBCL version
+it was generated with. While this is obviously suboptimal, it has
+proven more robust than trying to maintain fasl compatibility across
+versions: accidentally breaking things is far too easy, and can lead
+to hard to diagnose bugs.
-Before you read this user manual, you should probably read two other
-things.
+The following snippet handles fasl recompilation automatically for
+ASDF-based systems, and makes a good candidate for inclusion in
+the user or system initialization file (@pxref{Initialization Files}.)
+
+@lisp
+(require :asdf)
+
+;;; If a fasl was stale, try to recompile and load (once).
+(defmethod asdf:perform :around ((o asdf:load-op)
+ (c asdf:cl-source-file))
+ (handler-case (call-next-method o c)
+ ;; If a fasl was stale, try to recompile and load (once).
+ (sb-ext:invalid-fasl ()
+ (asdf:perform (make-instance 'asdf:compile-op) c)
+ (call-next-method))))
+@end lisp
+
+
+@node Compiler-only Implementation
+@comment node-name, next, previous, up
+@subsection Compiler-only Implementation
+
+SBCL is essentially a compiler-only implementation of Common Lisp.
+That is, for all but a few special cases, @code{eval} creates a lambda
+expression, calls @code{compile} on the lambda expression to create a
+compiled function, and then calls @code{funcall} on the resulting
+function object. A more traditional interpreter is also available on
+default builds; it is usually only called internally. This is
+explicitly allowed by the ANSI standard, but leads to some oddities;
+e.g. at default settings, @code{functionp} and
+@code{compiled-function-p} are equivalent, and they collapse into the
+same function when SBCL is built without the interpreter.
+
+@node Defining Constants
+@comment node-name, next, previous, up
+@subsection Defining Constants
+@findex @cl{defconstant}
+
+SBCL is quite strict about ANSI's definition of @code{defconstant}.
+ANSI says that doing @code{defconstant} of the same symbol more than
+once is undefined unless the new value is @code{eql} to the old value.
+Conforming to this specification is a nuisance when the ``constant''
+value is only constant under some weaker test like @code{string=} or
+@code{equal}.
+
+It's especially annoying because, in SBCL, @code{defconstant} takes
+effect not only at load time but also at compile time, so that just
+compiling and loading reasonable code like
+@lisp
+(defconstant +foobyte+ '(1 4))
+@end lisp
+runs into this undefined behavior. Many implementations of Common Lisp
+try to help the programmer around this annoyance by silently accepting
+the undefined code and trying to do what the programmer probably
+meant.
+
+SBCL instead treats the undefined behavior as an error. Often such
+code can be rewritten in portable ANSI Common Lisp which has the
+desired behavior. E.g., the code above can be given an exactly defined
+meaning by replacing @code{defconstant} either with
+@code{defparameter} or with a customized macro which does the right
+thing, e.g.
+@lisp
+(defmacro define-constant (name value &optional doc)
+ `(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
+ ,@@(when doc (list doc))))
+@end lisp
+or possibly along the lines of the @code{defconstant-eqx} macro used
+internally in the implementation of SBCL itself. In circumstances
+where this is not appropriate, the programmer can handle the condition
+type @code{sb-ext:defconstant-uneql}, and choose either the
+@command{continue} or @command{abort} restart as appropriate.
+
+@node Style Warnings
+@comment node-name, next, previous, up
+@subsection Style Warnings
+
+SBCL gives style warnings about various kinds of perfectly legal code,
+e.g.
@itemize
@item
-You should know how to program in Common Lisp. If you don't already
-know how, you should probably read a book on it. @xref{More Common
-Lisp Information}.
+@code{defmethod} without a preceding @code{defgeneric};
@item
-The Unix ``man page'' for SBCL will tell you
-how to start the SBCL environment, so you can get to the classic
-``hello, world'' level of knowledge. It's the file called
-@file{sbcl.1} in the SBCL distribution. If SBCL is installed on your
-system, you can read a formatted copy by executing the command
-@samp{man sbcl}.
+multiple @code{defun}s of the same symbol in different units;
+
+@item
+special variables not named in the conventional @code{*foo*} style,
+and lexical variables unconventionally named in the @code{*foo*} style
@end itemize
-
-Besides this user manual and the Unix man page, some other
-SBCL-specific information is available:
+This causes friction with people who point out that other ways of
+organizing code (especially avoiding the use of @code{defgeneric}) are
+just as aesthetically stylish. However, these warnings should be read
+not as ``warning, bad aesthetics detected, you have no style'' but
+``warning, this style keeps the compiler from understanding the code
+as well as you might like.'' That is, unless the compiler warns about
+such conditions, there's no way for the compiler to warn about some
+programming errors which would otherwise be easy to overlook. (Related
+bug: The warning about multiple @code{defun}s is pointlessly annoying
+when you compile and then load a function containing @code{defun}
+wrapped in @code{eval-when}, and ideally should be suppressed in that
+case, but still isn't as of SBCL 0.7.6.)
-@itemize
-@item
-The SBCL home page at @uref{http://www.sbcl.org/} has some
-general information, plus links to mailing lists devoted to SBCL, and
-to archives of these mailing lists.
-@item
-@findex help
+
+@node Development Tools
+@comment node-name, next, previous, up
+@section Development Tools
+
+@menu
+* Editor Integration::
+* Language Reference::
+* Generating Executables::
+@end menu
+
+@node Editor Integration
+@comment node-name, next, previous, up
+@subsection Editor Integration
+
+Though SBCL can be used running ``bare'', the recommended mode of
+development is with an editor connected to SBCL, supporting not
+only basic lisp editing (paren-matching, etc), but providing among
+other features an integrated debugger, interactive compilation, and
+automated documentation lookup.
+
+Currently @dfn{SLIME}@footnote{Historically, the ILISP package at
+@uref{http://ilisp.cons.org/} provided similar functionality, but it
+does not support modern SBCL versions.} (Superior Lisp Interaction
+Mode for Emacs) together with Emacs is recommended for use with
+SBCL, though other options exist as well.
+
+SLIME can be downloaded from
+@uref{http://www.common-lisp.net/project/slime/}.
+
+@node Language Reference
+@comment node-name, next, previous, up
+@subsection Language Reference
+
+@dfn{CLHS} (Common Lisp Hyperspec) is a hypertext version of the ANSI
+standard, made freely available by @emph{LispWorks} -- an invaluable
+reference.
+
+See: @uref{http://www.lispworks.com/reference/HyperSpec/index.html}
+
+@node Generating Executables
+@comment node-name, next, previous, up
+@subsection Generating Executables
+
+SBCL can generate stand-alone executables. The generated executables
+include the SBCL runtime itself, so no restrictions are placed on
+program functionality. For example, a deployed program can call
+@code{compile} and @code{load}, which requires the compiler to be present
+in the executable. For further information, @xref{Function
+sb-ext:save-lisp-and-die}.
+
+
+@node More SBCL Information
+@comment node-name, next, previous, up
+@section More SBCL Information
+
+@menu
+* SBCL Homepage::
+* Online Documentation::
+* Additional Documentation Files::
+* Internals Documentation::
+@end menu
+
+@node SBCL Homepage
+@comment node-name, next, previous, up
+@subsection SBCL Homepage
+
+The SBCL website at @uref{http://www.sbcl.org/} has some general
+information, plus links to mailing lists devoted to SBCL, and to
+archives of these mailing lists. Subscribing to the mailing lists
+@cite{sbcl-help} and @cite{sbcl-announce} is recommended: both are
+fairly low-volume, and help you keep abreast with SBCL development.
+
+@node Online Documentation
+@comment node-name, next, previous, up
+@subsection Online Documentation
+
Documentation for non-ANSI extensions for various commands is
-available online from the SBCL executable itself. The extensions for
-functions which have their own command prompts (e.g. the debugger, and
-@code{inspect}) are documented in text available by typing
+available online from the SBCL executable itself. The extensions
+for functions which have their own command prompts (e.g. the debugger,
+and @code{inspect}) are documented in text available by typing
@command{help} at their command prompts. The extensions for functions
which don't have their own command prompt (such as @code{trace}) are
described in their documentation strings, unless your SBCL was
compiled with an option not to include documentation strings, in which
-case the doc strings are only readable in the source code.
+case the documentation strings are only readable in the source code.
+
+@node Additional Documentation Files
+@comment node-name, next, previous, up
+@subsection Additional Documentation Files
+
+Besides this user manual both SBCL source and binary distributions
+include some other SBCL-specific documentation files, which should be
+installed along with this manual on your system, e.g. in
+@file{/usr/local/share/doc/sbcl/}.
+
+@table @file
+
+@item COPYING
+Licence and copyright summary.
+
+@item CREDITS
+Authorship information on various parts of SBCL.
+
+@item INSTALL
+Covers installing SBCL from both source and binary distributions on
+your system, and also has some installation related troubleshooting
+information.
+
+@item NEWS
+Summarizes changes between various SBCL versions.
+
+@end table
+
+@node Internals Documentation
+@comment node-name, next, previous, up
+@subsection Internals Documentation
+
+If you're interested in the development of the SBCL system itself,
+then subscribing to @cite{sbcl-devel} is a good idea.
+
+SBCL internals documentation -- besides comments in the source -- is
+currently maintained as a @emph{wiki-like} website:
+@uref{http://sbcl-internals.cliki.net/}.
-@item
Some low-level information describing the programming details of the
conversion from CMUCL to SBCL is available in the
-@file{doc/FOR-CMUCL-DEVELOPERS} file in the SBCL
-distribution.
+@file{doc/FOR-CMUCL-DEVELOPERS} file in the SBCL distribution, though
+it is not installed by default.
-@end itemize
-
+@node More Common Lisp Information
+@comment node-name, next, previous, up
+@section More Common Lisp Information
+
+@menu
+* Internet Community::
+* Third-party Libraries::
+* Common Lisp Books::
+@end menu
+
+@node Internet Community
+@comment node-name, next, previous, up
+@subsection Internet Community
+
+@c FIXME: Say something smart here
+
+The Common Lisp internet community is fairly diverse:
+@uref{news://comp.lang.lisp} is fairly high volume newsgroup, but has
+a rather poor signal/noise ratio. Various special interest mailing
+lists and IRC tend to provide more content and less flames.
+@uref{http://www.lisp.org} and @uref{http://www.cliki.net} contain
+numerous pointers places in the net where lispers talks shop.
+
+@node Third-party Libraries
+@comment node-name, next, previous, up
+@subsection Third-party Libraries
+
+For a wealth of information about free Common Lisp libraries and tools
+we recommend checking out @emph{CLiki}: @uref{http://www.cliki.net/}.
-@node Overview
+@node Common Lisp Books
@comment node-name, next, previous, up
-@section History and Implementation
+@subsection Common Lisp Books
-You can work productively with SBCL without knowing anything
+If you're not a programmer and you're trying to learn, many
+introductory Lisp books are available. However, we don't have any
+standout favorites. If you can't decide, try checking the Usenet
+@uref{news://comp.lang.lisp} FAQ for recent recommendations.
+
+@c FIXME: This non-stance is silly. Maybe we could recommend SICP,
+@c Touretzky, or something at least.
+
+If you are an experienced programmer in other languages but need to
+learn about Common Lisp, some books stand out:
+
+@table @cite
+
+@item Practical Common Lisp, by Peter Seibel
+An excellent introduction to the language, covering both the basics
+and ``advanced topics'' like macros, CLOS, and packages. Available
+both in print format and on the web: @uref{http://www.gigamonkeys.com/book/}.
+
+@item Paradigms Of Artificial Intelligence Programming, by Peter Norvig
+Good information on general Common Lisp programming, and many
+nontrivial examples. Whether or not your work is AI, it's a very good
+book to look at.
+
+@item On Lisp, by Paul Graham
+An in-depth treatment of macros, but not recommended as a first Common
+Lisp book, since it is slightly pre-ANSI so you need to be on your
+guard against non-standard usages, and since it doesn't really even
+try to cover the language as a whole, focusing solely on macros.
+Downloadable from @uref{http://www.paulgraham.com/onlisp.html}.
+
+@item Object-Oriented Programming In Common Lisp, by Sonya Keene
+With the exception of @cite{Practical Common Lisp} most introductory
+books don't emphasize CLOS. This one does. Even if you're very
+knowledgeable about object oriented programming in the abstract, it's
+worth looking at this book if you want to do any OO in Common Lisp.
+Some abstractions in CLOS (especially multiple dispatch) go beyond
+anything you'll see in most OO systems, and there are a number of
+lesser differences as well. This book tends to help with the culture
+shock.
+
+@item Art Of Metaobject Programming, by Gregor Kiczales et al.
+Currently the prime source of information on the Common Lisp Metaobject
+Protocol, which is supported by SBCL. Section 2 (Chapters 5 and 6) are
+freely available at @uref{http://www.lisp.org/mop/}.
+
+@end table
+
+
+
+
+@node History and Implementation of SBCL
+@comment node-name, next, previous, up
+@section History and Implementation of SBCL
+
+You can work productively with SBCL without knowing or
understanding anything about where it came from, how it is
implemented, or how it extends the ANSI Common Lisp standard. However,
a little knowledge can be helpful in order to understand error
to the casual user, since SBCL still can and does execute code
interactively by compiling it on the fly. (It is visible if you know how
to look, like using @code{compiled-function-p}; and it is visible in the
-way that that SBCL doesn't have many bugs which behave differently in
+way that SBCL doesn't have many bugs which behave differently in
interpreted code than in compiled code.) What it means is that in SBCL,
the @code{eval} function only truly ``interprets'' a few easy kinds of
forms, such as symbols which are @code{boundp}. More complicated forms
are evaluated by calling @code{compile} and then calling @code{funcall}
on the returned result.
-
+
The direct ancestor of SBCL is the x86 port of CMUCL. This port was in
some ways the most cobbled-together of all the CMUCL ports, since a
number of strange changes had to be made to support the register-poor
@itemize
@item
-SBCL has removed many CMUCL extensions, (e.g. IP networking, remote
-procedure call, Unix system interface, and X11 interface) from the
-core system. Most of these are available as contributed modules
-(distributed with sbcl) or third-party modules instead.
+SBCL has removed many CMUCL extensions, (e.g. IP networking,
+remote procedure call, Unix system interface, and X11 interface) from
+the core system. Most of these are available as contributed modules
+(distributed with SBCL) or third-party modules instead.
@item
SBCL has deleted or deprecated some nonstandard features and code
projects / sbcl.git / blobdiff