@comment node-name, next, previous, up
@chapter Beyond the ANSI Standard
-SBCL is mostly an implementation of the ANSI standard for
-Common Lisp. However, there's some important behavior which extends
-or clarifies the standard, and various behavior which outright
-violates the standard.
-
-
-@menu
-* Non-Conformance With The ANSI Standard::
-* Idiosyncrasies::
-* Extensions::
-@end menu
-
-@node Non-Conformance With The ANSI Standard
-@comment node-name, next, previous, up
-@section Non-Conformance With The ANSI Standard
-
-Essentially every type of non-conformance is considered a bug. (The
-exceptions involve internal inconsistencies in the standard.) In SBCL
-0.7.6, the master record of known bugs is in the @file{BUGS} file in
-the distribution. Some highlight information about bugs may also be
-found in the manual page. The recommended way to report bugs is
-through the sbcl-help or sbcl-devel mailing lists. For mailing list
-addresses, @xref{More SBCL Information}.
-
-
-@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.
-
-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{Compiler}.
-
-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. This is explicitly allowed by the ANSI
-standard, but leads to some oddities, e.g. collapsing @code{functionp}
-and @code{compiled-function-p} into the same predicate.
-
-@findex 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, 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.
-
-SBCL gives style warnings about various kinds of perfectly legal code,
-e.g.
-
-@itemize
-
-@item
-@code{defmethod} without a preceding @code{defgeneric};
-
-@item
-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
-
-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.)
-
-
-@node Extensions
-@comment node-name, next, previous, up
-@section Extensions
-
SBCL is derived from CMUCL, which implements many extensions to the
ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
it still has quite a few. @xref{Contributed Modules}.
-
@menu
* Things Which Might Be In The Next ANSI Standard::
* Support For Unix::
@node Things Which Might Be In The Next ANSI Standard
@comment node-name, next, previous, up
-@subsection Things Which Might Be In The Next ANSI Standard
+@section Things Which Might Be In The Next ANSI Standard
SBCL provides extensive support for calling external C code,
@ref{Foreign Function Interface}.
@node Support For Unix
@comment node-name, next, previous, up
-@subsection Support For Unix
+@section Support For Unix
The UNIX command line can be read from the variable
@code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
@include fun-sb-ext-posix-getenv.texinfo
-The SBCL system can be terminated with @code{sb-ext:quit}, (but see
-notes in @ref{Threading} about the interaction between this feature and
-sessions) optionally returning a specified numeric value to the
-calling Unix process. The normal Unix idiom of terminating on end of
-file on input is also supported.
-
-@include fun-sb-ext-quit.texinfo
@node Customization Hooks for Users
@comment node-name, next, previous, up
-@subsection Customization Hooks for Users
+@section Customization Hooks for Users
The toplevel repl prompt may be customized, and the function
that reads user input may be replaced completely.
@node Tools To Help Developers
@comment node-name, next, previous, up
-@subsection Tools To Help Developers
+@section Tools To Help Developers
SBCL provides a profiler and other extensions to the ANSI @code{trace}
facility. For more information, see @ref{macro-common-lisp-trace}.
@node Interface To Low-Level SBCL Implementation
@comment node-name, next, previous, up
-@subsection Interface To Low-Level SBCL Implementation
+@section Interface To Low-Level SBCL Implementation
SBCL has the ability to save its state as a file for later
execution. This functionality is important for its bootstrapping
@node Stale Extensions
@comment node-name, next, previous, up
-@subsection Stale Extensions
+@section Stale Extensions
SBCL has inherited from CMUCL various hooks to allow the user to
tweak and monitor the garbage collection process. These are somewhat
@node Efficiency Hacks
@comment node-name, next, previous, up
-@subsection Efficiency Hacks
+@section Efficiency Hacks
The @code{sb-ext:purify} function causes SBCL first to collect all
garbage, then to mark all uncollected objects as permanent, never
Lisp.
@menu
-* More Common Lisp Information::
-* More SBCL Information::
-* Overview::
+* ANSI Conformance::
+* Extensions::
+* Idiosyncrasies::
+* Development Tools::
+* More SBCL Information::
+* 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.) In SBCL
+the master record of known bugs is in the @file{BUGS} file in the
+distribution.
-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.
+The recommended way to report bugs is through the @cite{sbcl-help} or
+@cite{sbcl-devel} mailing lists. For mailing list addresses,
+see @ref{SBCL Homepage}.
-If you are an experienced programmer in other languages but need to
-learn about Lisp, three books stand out.
-@itemize
-@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.)
+@node Extensions
+@comment node-name, next, previous, up
+@section Extensions
+
+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.
+
+@c FIXME: Once bits and pieces referred to here get real documentation
+@c add xrefs there.
+
+@table @strong
+
+@item System Definition Tool
+@code{asdf} is a flexible and popular protocol-oriented system
+definition tool by Daniel Barlow.
+
+@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.
+
+@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}.
+
+@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 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. x@ref{Networking}.
+
+@item Introspective Facilities
+@code{sb-introspect} module offers numerous introspective extensions,
+including access to function lambda-lists.
+
+@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 implentation 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{Accurate
+Profiler}.
+
+@code{sb-sprof} is a statistical profiler, capable of call-graph
+generation and instruction level 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 Compatility 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 Fasl Packaging
+@code{sb-executable} can be used to concatenate multiple fasls into a
+single executable (though the presense of an SBCL runtime and core
+image is still required to run it).
+
+@item Bitwise Rotation
+@code{sb-rotate-byte} provides an efficient primitive for bitwise
+rotation of integers, an operation required by eg. numerous
+cryptographic algorightms, 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::
+* Compiler-only Implementation::
+* Defining Constants::
+* Style Warnings::
+@end menu
+
+@node Declarations
+@comment node-name, next, previous, up
+@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 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. This is explicitly allowed by the ANSI standard, but
+leads to some oddities, e.g. collapsing @code{functionp} and
+@code{compiled-function-p} into the same predicate.
+
+@node Defining Constants
+@comment node-name, next, previous, up
+@subsection Defining Constants
+@findex 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, eg.
+@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
-@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.
+@code{defmethod} without a preceding @code{defgeneric};
+
+@item
+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
+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.)
+
+
+
+
+@node Development Tools
+@comment node-name, next, previous, up
+@section Development Tools
+
+@menu
+* Editor Integration::
+* Language Reference::
+@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) togather 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{Xanalyst} -- an invaluable
+reference.
+
+See: @uref{http://www.lispworks.com/reference/HyperSpec/index.html}
+
+
+
@node More SBCL Information
@comment node-name, next, previous, up
-@section Sources of more information about SBCL
+@section More SBCL Information
-Before you read this user manual, you should probably read two other
-things.
+@menu
+* SBCL Homepage::
+* Additional Distributed Documentation::
+* Online Documentation::
+* Internals Documentation::
+@end menu
-@itemize
+@node SBCL Homepage
+@comment node-name, next, previous, up
+@subsection SBCL Homepage
-@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}.
+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 abrest with SBCL development.
-@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}.
+@node Additional Distributed Documentation
+@comment node-name, next, previous, up
+@subsection Additional Distributed Documentation
-@end itemize
-
+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 in on your system, eg. in
+@file{/usr/local/share/doc/sbcl/}.
-Besides this user manual and the Unix man page, some other
-SBCL-specific information is available:
+@table @file
-@itemize
+@item BUGS
+Lists known bugs in the distribution.
-@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 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.
+
+@item SUPPORT
+Lists SBCL developers available for-pay development of SBCL.
+
+@end table
+
+@node Online Documentation
+@comment node-name, next, previous, up
+@subsection Online Documentation
-@item
-@findex help
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 Internals Documentation
+@comment node-name, next, previous, up
+@subsection Internals Documentation
+
+If you're interested in the development of the SBCL system itself,
+then subcribing to @cite{sbcl-devel} is a good idea.
+
+SBCL internals documentation -- besides comments in the source -- is
+currenly maitained 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.
+
+@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 Common Lisp Books
+@comment node-name, next, previous, up
+@subsection Common Lisp Books
+
+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
+
+@c FIXME: Ask Seibel if he minds us referring to the preview
+@c
+@c @item Practical Common Lisp, by Peter Seibel
+@c A forthcoming book from APress with a web free preview at
+@c @uref{http://www.gigamonkeys.com/book/}. An excellent introduction to
+@c the language, covering both the basics and ``advanced topics'' like
+@c macros, CLOS, and packages.
+
+@item ANSI Common Lisp, by Paul Graham
+Introduces most of the language, though some parts (eg. CLOS) are
+covered only lightly.
+
+@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 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 Object-Oriented Programming In Common Lisp, by Sonya Keene
+@c With the exception of @cite{Practical Common Lisp}
+None the books above emphasize CLOS, but 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 to prime source of information on the Common Lisp Metaobject
+Protocol, which is supported by SBCL. Section 2 (Chapers 5 and 6) are
+freely available at @uref{http://www.lisp.org/mop/}.
+
+@end table
+
+
-@end itemize
-
-@node Overview
+@node History and Implementation of SBCL
@comment node-name, next, previous, up
-@section History and Implementation
+@section History and Implementation of SBCL
You can work productively with SBCL without knowing anything
understanding anything about where it came from, how it is
@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
+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
--- /dev/null
+@node Starting and Stopping
+@comment node-name, next, previous, up
+@chapter Starting and Stoppping
+
+@menu
+* Starting SBCL::
+* Stopping SBCL::
+* Command Line Options::
+* Initialization Files::
+@end menu
+
+@node Starting SBCL
+@comment node-name, next, previous, up
+@section Starting SBCL
+
+@menu
+* Running from Shell::
+* Running from Emacs::
+* Shebang Scripts::
+@end menu
+
+@node Running from Shell
+@comment node-name, next, previous, up
+@subsection From Shell to Lisp
+
+To run SBCL type @command{sbcl} at the command line.
+
+You should end up in the toplevel @dfn{REPL} (read, eval, print
+-loop), where you can interact with SBCL by typing expressions.
+
+@smallexample
+@cartouche
+$ sbcl
+This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
+More information about SBCL is available at <http://www.sbcl.org/>.
+
+SBCL is free software, provided as is, with absolutely no warranty.
+It is mostly in the public domain; some portions are provided under
+BSD-style licenses. See the CREDITS and COPYING files in the
+distribution for more information.
+* (+ 2 2)
+
+4
+* (quit)
+$
+@end cartouche
+@end smallexample
+
+See also @ref{Command Line Options} and @ref{Stopping SBCL}.
+
+@node Running from Emacs
+@comment node-name, next, previous, up
+@subsection Running from Emacs
+
+To run SBCL as an inferior-lisp from Emacs in your @file{.emacs} do
+something like:
+
+@lisp
+;;; The SBCL binary and command-line arguments
+(setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
+@end lisp
+
+For more information on using SBCL with Emacs, see @ref{Editor
+Integration}.
+
+
+@node Shebang Scripts
+@comment node-name, next, previous, up
+@subsection Shebang Scripts
+
+SBCL doesn't come with built-in support for shebang-line execution,
+but this can be provided with a shell trampoline, or by dispatching
+from initialization files (@pxref{Unix-style Command Line Protocol} for
+an example.)
+
+
+@node Stopping SBCL
+@comment node-name, next, previous, up
+@section Stopping SBCL
+
+@menu
+* Quit::
+* End of File::
+* Exit on Errors::
+@end menu
+
+@node Quit
+@comment node-name, next, previous, up
+@subsection Quit
+
+SBCL can be stopped at any time by calling @code{sb-ext:quit},
+optionally returning a specified numeric value to the calling process.
+See notes in @ref{Threading} about the interaction between this
+feature and sessions.
+
+@include fun-sb-ext-quit.texinfo
+
+@node End of File
+@comment node-name, next, previous, up
+@subsection End of File
+
+By default SBCL also exits on end of input, caused either by user
+pressing @kbd{Control-D} on an attached terminal, or end of input when
+using SBCL as part of a shell pipeline.
+
+
+@node Exit on Errors
+@comment node-name, next, previous, up
+@subsection Exit on Errors
+
+SBCL can also be configured to exit if an unhandled error occurs,
+which is mainly useful for acting as part of a shell pipeline; doing
+so under most other circumstances would mean giving up large parts of
+the flexibility and robustness of Common Lisp. See @ref{Customization
+Hooks for Users}.
+
+
+@node Command Line Options
+@comment node-name, next, previous, up
+@section Command Line Options
+
+@c FIXME: This is essentially cut-and-paste from the manpage
+@c What should probably be done is generate both this and the
+@c man-page from ``sbcl --help'' output.
+
+Command line options can be considered an advanced topic; for ordinary
+interactive use, no command line arguments should be necessary.
+
+In order to understand the command line argument syntax for SBCL, it
+is helpful to understand that the SBCL system is implemented as two
+components, a low-level runtime environment written in C and a
+higher-level system written in Common Lisp itself. Some command line
+arguments are processed during the initialization of the low-level
+runtime environment, some command line arguments are processed during
+the initialization of the Common Lisp system, and any remaining
+command line arguments are passed on to user code.
+
+The full, unambiguous syntax for invoking SBCL at the command line is:
+
+@command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
+
+For convenience, the @code{--end-runtime-options} and
+@code{--end-toplevel-options} elements can be omitted. Omitting these
+elements can be convenient when you are running the program
+interactively, and you can see that no ambiguities are possible with
+the option values you are using. Omitting these elements is probably a
+bad idea for any batch file where any of the options are under user
+control, since it makes it impossible for SBCL to detect erroneous
+command line input, so that erroneous command line arguments will be
+passed on to the user program even if they was intended for the
+runtime system or the Lisp system.
+
+@menu
+* Runtime Options::
+* Toplevel Options::
+@end menu
+
+@node Runtime Options
+@comment node-name, next, previous, up
+@subsection Runtime Options
+
+@table @code
+
+@item --core @var{corefilename}
+Run the specified Lisp core file instead of the default. Note that if
+the Lisp core file is a user-created core file, it may run a
+nonstandard toplevel which does not recognize the standard toplevel
+options.
+
+@item --noinform
+Suppress the printing of any banner or other informational message at
+startup. This makes it easier to write Lisp programs which work
+cleanly in Unix pipelines. See also the @code{--noprint} and
+@code{--disable-debugger} options.
+
+@item --help
+Print some basic information about SBCL, then exit.
+
+@item --version
+Print SBCL's version information, then exit.
+
+@end table
+
+In the future, runtime options may be added to control behavior such
+as lazy allocation of memory.
+
+Runtime options, including any --end-runtime-options option, are
+stripped out of the command line before the Lisp toplevel logic gets a
+chance to see it.
+
+@node Toplevel Options
+@comment node-name, next, previous, up
+@subsection Toplevel Options
+
+@table @code
+
+@item --sysinit @var{filename}
+Load filename instead of the default system initialization file
+(@pxref{System Initialization File}.) There is no special option to
+cause no system initialization file to be read, but on a Unix
+system ``@code{"--sysinit /dev/null}'' can be used to achieve the same
+effect.
+
+@item --userinit @var{filename}
+Load filename instead of the default user initialization file
+(@pxref{User Initialization File}.) There is no special option to
+cause no user initialization file to be read, but ``@code{--userinit
+/dev/null}'' can be used to achieve the same effect.
+
+@item --eval @var{command}
+After executing any initialization file, but before starting the
+read-eval-print loop on standard input, read and evaluate the com-
+mand given. More than one @code{--eval} option can be used, and all
+will be read and executed, in the order they appear on the command
+line.
+
+@item --load @var{filename}
+This is equivalent to @code{--eval '(load "@var{filename}")'}. The
+special syntax is intended to reduce quoting headaches when invoking
+SBCL from shell scripts.
+
+@item --noprint
+When ordinarily the toplevel "read-eval-print loop" would be exe-
+cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
+and don't echo results. Combined with the @code{--noinform} runtime
+option, this makes it easier to write Lisp "scripts" which work
+cleanly in Unix pipelines.
+
+@item --disable-debugger
+This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
+@xref{Customization Hooks for Users}.
+
+@end table
+
+
+@node Initialization Files
+@comment node-name, next, previous, up
+@section Initialization Files
+
+This section covers initialization files loaded at startup, which can
+be used to customize the lisp environment.
+
+@menu
+* System Initialization File::
+* User Initialization File::
+* Initialization File Semantics::
+* Initialization Examples::
+@end menu
+
+@node System Initialization File
+@comment node-name, next, previous, up
+@subsection System Initialization File
+
+Site-wide startup script. Unless overridden with the command line
+option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
+if that doesn't exist to @file{/etc/sbclrc}.
+
+No system initialization file is required.
+
+@node User Initialization File
+@comment node-name, next, previous, up
+@subsection User Initialization File
+
+Per-user startup script. Unless overridden with the command line
+option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
+
+No user initialization file is required.
+
+@node Initialization File Semantics
+@comment node-name, next, previous, up
+@subsection Initialization File Semantics
+
+SBCL uses @code{load} to process its initialization files, which
+has the unfortunate effect of preventing users from changing the
+default startup @code{*package*}, and setting a default optimization
+policy.
+
+This is considered a bug and liable to change in the future.
+
+@node Initialization Examples
+@comment node-name, next, previous, up
+@subsection Initialization Examples
+
+Some examples of what you may consider doing in the initialization
+files follow.
+
+@menu
+* Unix-style Command Line Protocol::
+* Automatic Recompilation of Stale Fasls::
+@end menu
+
+@node Unix-style Command Line Protocol
+@comment node-name, next, previous, up
+@subsubsection Unix-style Command Line Protocol
+
+Standard Unix tools that are interpeters follow a common command line
+protocol that is necessary to work with ``shebang scripts''. SBCL
+doesn't do this by default, but adding the following snippet to an
+initialization file does the trick:
+
+@lisp
+;;; If the first user-processable command-line argument is a filename,
+;;; disable the debugger, load the file handling shebang-line and quit.
+(let ((script (probe-file (second sb-ext:*posix-argv*))))
+ (when script
+ ;; Handle the possible shebang-line
+ (set-dispatch-macro-character #\# #\!
+ (lambda (stream char arg)
+ (declare (ignore char arg))
+ (read-line stream)))
+ ;; Disable debugger
+ (setf sb-ext:*invoke-debugger-hook*
+ (lambda (condition hook)
+ (declare (ignore hook))
+ (format *error-output* "Error: ~A~%" condition)
+ (quit :unix-status 1)))
+ (load script)
+ (quit)))
+@end lisp
+
+Example file (@file{hello.lisp}):
+
+@lisp
+#!/usr/local/bin/sbcl --noinform
+(write-line "Hello, World!")
+@end lisp
+
+Usage examples:
+
+@smallexample
+@cartouche
+$ ./hello.lisp
+Hello, World!
+@end cartouche
+@end smallexample
+
+@smallexample
+@cartouche
+$ sbcl hello.lisp
+This is SBCL 0.8.13.70, an implementation of ANSI Common Lisp.
+More information about SBCL is available at <http://www.sbcl.org/>.
+
+SBCL is free software, provided as is, with absolutely no warranty.
+It is mostly in the public domain; some portions are provided under
+BSD-style licenses. See the CREDITS and COPYING files in the
+distribution for more information.
+Hello, World!
+@end cartouche
+@end smallexample
+
+
+@node Automatic Recompilation of Stale Fasls
+@comment node-name, next, previous, up
+@subsubsection Automatic Recompilation of Stale Fasls
+
+SBCL fasl-format is at current stage of development undergoing
+non-backwards compatible changes fairly often. The following snippet
+handles recompilation automatically for ASDF-based systems.
+
+@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)
+ (sb-ext:invalid-fasl error ()
+ (asdf:perform (make-instance 'asdf:compile-op) c)
+ (call-next-method))))
+@end lisp
projects / sbcl.git / commitdiff