From: Nikodemus S. <de...@us...> - 2004-08-17 22:56:12
|
Update of /cvsroot/sbcl/sbcl/doc/manual In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv29874/doc/manual Modified Files: beyond-ansi.texinfo intro.texinfo sbcl.texinfo Added Files: start-stop.texinfo Log Message: 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. --- NEW FILE: start-stop.texinfo --- @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 Index: beyond-ansi.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/beyond-ansi.texinfo,v retrieving revision 1.13 retrieving revision 1.14 diff -u -d -r1.13 -r1.14 --- beyond-ansi.texinfo 17 Aug 2004 18:53:05 -0000 1.13 +++ beyond-ansi.texinfo 17 Aug 2004 22:55:57 -0000 1.14 @@ -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 @@ @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 @@ @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 @@ @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 @@ @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 @@ @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 @@ @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 @@ @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 Index: intro.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/intro.texinfo,v retrieving revision 1.8 retrieving revision 1.9 diff -u -d -r1.8 -r1.9 --- intro.texinfo 17 Aug 2004 18:34:29 -0000 1.8 +++ intro.texinfo 17 Aug 2004 22:55:57 -0000 1.9 @@ -8,117 +8,475 @@ 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.) -@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. +@node Extensions +@comment node-name, next, previous, up +@section Extensions -@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. +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. -@end itemize +@c FIXME: Once bits and pieces referred to here get real documentation +@c add xrefs there. +@table @strong -@node More SBCL Information +@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 Sources of more information about SBCL +@section Idiosyncrasies -Before you read this user manual, you should probably read two other -things. +The information in this section describes some of the ways that SBCL +deals with choices that the ANSI standard leaves to the +implementation. -@itemize +@menu +* Declarations:: +* Compiler-only Implementation:: +* Defining Constants:: +* Style Warnings:: +@end menu -@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}. +@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 -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}. +@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 - -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:: +@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 More SBCL Information + +@menu +* SBCL Homepage:: +* Additional Distributed Documentation:: +* Online Documentation:: +* 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 abrest with SBCL development. + +@node Additional Distributed Documentation +@comment node-name, next, previous, up +@subsection Additional Distributed Documentation + +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/}. + +@table @file + +@item BUGS +Lists known bugs in the distribution. + +@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 + 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. -@end itemize - +@node More Common Lisp Information +@comment node-name, next, previous, up +@section More Common Lisp Information -@node Overview +@menu +* Internet Community:: +* Third-party Libraries:: +* Common Lisp Books:: +@end menu + +@node Internet Community @comment node-name, next, previous, up -@section History and Implementation +@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 + + + + +@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 anything understanding anything about where it came from, how it is @@ -215,9 +573,9 @@ @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 Index: sbcl.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/sbcl.texinfo,v retrieving revision 1.13 retrieving revision 1.14 diff -u -d -r1.13 -r1.14 --- sbcl.texinfo 17 Aug 2004 18:53:05 -0000 1.13 +++ sbcl.texinfo 17 Aug 2004 22:55:57 -0000 1.14 @@ -57,6 +57,7 @@ @menu * Introduction:: +* Starting and Stopping:: * Compiler:: * Debugger:: * Efficiency:: @@ -78,6 +79,7 @@ @end ifnottex @include intro.texinfo +@include start-stop.texinfo @include compiler.texinfo @include debugger.texinfo @include efficiency.texinfo |