From 3c0ee1b87c4191298a8842cf7682c3f308680e66 Mon Sep 17 00:00:00 2001 From: Nikodemus Siivola Date: Tue, 17 Aug 2004 22:55:56 +0000 Subject: [PATCH] 0.8.13.73: Documentation frenzy continues * Restructure "Introduction", moving bits of "Beyond ANSI" there. * Add a new chapter "Starting and Stopping". * Clean up a few minor @xref problems. --- contrib/sb-grovel/sb-grovel.texinfo | 2 +- doc/manual/beyond-ansi.texinfo | 130 +-------- doc/manual/intro.texinfo | 514 +++++++++++++++++++++++++++++------ doc/manual/sbcl.texinfo | 2 + doc/manual/start-stop.texinfo | 369 +++++++++++++++++++++++++ version.lisp-expr | 2 +- 6 files changed, 816 insertions(+), 203 deletions(-) create mode 100644 doc/manual/start-stop.texinfo diff --git a/contrib/sb-grovel/sb-grovel.texinfo b/contrib/sb-grovel/sb-grovel.texinfo index 4313153..ccb6fd2 100644 --- a/contrib/sb-grovel/sb-grovel.texinfo +++ b/contrib/sb-grovel/sb-grovel.texinfo @@ -171,7 +171,7 @@ structure member. @item @code{:function} - alien function definitions are similar to @code{define-alien-routine} definitions, because they expand to such -forms when the lisp program is loaded. @xref{Foreign Function Calls} +forms when the lisp program is loaded. @xref{Foreign Function Calls}. @lisp (:function lisp-function-name ("alien_function_name" alien-return-type diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index 0f1b27a..97231fe 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -2,119 +2,10 @@ @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:: @@ -127,7 +18,7 @@ it still has quite a few. @xref{Contributed Modules}. @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}. @@ -171,7 +62,7 @@ requested order from a user-supplied primary method. @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 @@ -179,17 +70,10 @@ the @code{sb-ext:posix-getenv} function. @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. @@ -211,7 +95,7 @@ mechanisms as follows: @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}. @@ -224,7 +108,7 @@ the @code{inspect} prompt. @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 @@ -242,7 +126,7 @@ ffi.texinfo?} @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 @@ -264,7 +148,7 @@ list. @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 diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo index 6ad18eb..4a6528a 100644 --- a/doc/manual/intro.texinfo +++ b/doc/manual/intro.texinfo @@ -8,117 +8,475 @@ not on behavior which is common to all implementations of ANSI Common 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 @@ -215,9 +573,9 @@ Other major changes since the fork from CMUCL include @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 diff --git a/doc/manual/sbcl.texinfo b/doc/manual/sbcl.texinfo index ec05fda..28cd36a 100644 --- a/doc/manual/sbcl.texinfo +++ b/doc/manual/sbcl.texinfo @@ -57,6 +57,7 @@ provided with absolutely no warranty. See the @file{COPYING} and @menu * Introduction:: +* Starting and Stopping:: * Compiler:: * Debugger:: * Efficiency:: @@ -78,6 +79,7 @@ provided with absolutely no warranty. See the @file{COPYING} and @end ifnottex @include intro.texinfo +@include start-stop.texinfo @include compiler.texinfo @include debugger.texinfo @include efficiency.texinfo diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo new file mode 100644 index 0000000..320a8b6 --- /dev/null +++ b/doc/manual/start-stop.texinfo @@ -0,0 +1,369 @@ +@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 . + +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 . + +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 diff --git a/version.lisp-expr b/version.lisp-expr index c4de0fc..24fb926 100644 --- a/version.lisp-expr +++ b/version.lisp-expr @@ -17,4 +17,4 @@ ;;; checkins which aren't released. (And occasionally for internal ;;; versions, especially for internal versions off the main CVS ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".) -"0.8.13.72" +"0.8.13.73" -- 1.7.10.4