X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fintro.texinfo;h=4f3182ba4cc69aa6415eba55085417d05b0c8fea;hb=4783db4884a231e8d217ce85feaa2c32a53ef6b9;hp=26b130770bb40b6f6bedcd068faa0f95ad8d473a;hpb=a2e934ad4e9545f1c6bbd8a9e9d3dd4d1c4698d9;p=sbcl.git diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo index 26b1307..4f3182b 100644 --- a/doc/manual/intro.texinfo +++ b/doc/manual/intro.texinfo @@ -24,16 +24,8 @@ Lisp. @section ANSI Conformance 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. - -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}; note that as a spam-reduction measure you -must subscribe before you can post. - - +exceptions involve internal inconsistencies in the standard.) +@xref{Reporting Bugs}. @node Extensions @comment node-name, next, previous, up @@ -83,7 +75,8 @@ both TCP and UDP sockets. @xref{Networking}. @item Introspective Facilities @code{sb-introspect} module offers numerous introspective extensions, -including access to function lambda-lists. +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 @@ -104,8 +97,8 @@ streams} API proposed by Franz Inc. @xref{Simple Streams}. Profiler}. @code{sb-sprof} is a statistical profiler, capable of call-graph -generation and instruction level profiling. @xref{Statistical -Profiler}. +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 @@ -121,11 +114,7 @@ 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 presence of an SBCL runtime and core image -is still required to run it). - +@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 @@ -161,6 +150,7 @@ implementation. @menu * Declarations:: +* FASL Format:: * Compiler-only Implementation:: * Defining Constants:: * Style Warnings:: @@ -175,6 +165,35 @@ 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. + +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 @@ -190,7 +209,7 @@ leads to some oddities, e.g. collapsing @code{functionp} and @node Defining Constants @comment node-name, next, previous, up @subsection Defining Constants -@findex defconstant +@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 @@ -321,8 +340,8 @@ sb-ext:save-lisp-and-die}. @menu * SBCL Homepage:: -* Additional Distributed Documentation:: * Online Documentation:: +* Additional Documentation Files:: * Internals Documentation:: @end menu @@ -336,9 +355,23 @@ 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. -@node Additional Distributed Documentation +@node Online Documentation @comment node-name, next, previous, up -@subsection Additional Distributed Documentation +@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 +@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 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 @@ -347,9 +380,6 @@ installed along with this manual in on your system, eg. in @table @file -@item BUGS -Lists known bugs in the distribution. - @item COPYING Licence and copyright summary. @@ -364,25 +394,8 @@ 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 - -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 -@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 documentation strings are only readable in the source code. - @node Internals Documentation @comment node-name, next, previous, up @subsection Internals Documentation @@ -446,17 +459,15 @@ 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 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 ANSI Common Lisp, by Paul Graham -Introduces most of the language, though some parts (eg. CLOS) are -covered only lightly. +@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 @@ -465,20 +476,15 @@ 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. +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 to prime source of information on the Common Lisp Metaobject