@cindex Read-Eval-Print Loop
@cindex REPL
-The @code{sb-aclrepl} module offers an AllegroCL style Read-Eval-Print
-Loop for SBCL. An AllegroCL style inspector is integrated. Adding an
-AllegroCL style debugger is planned.
+@c FIXME: I wanted to use @registeredsymbol{}, but that's
+@c only available in Texinfo 4.7. sigh.
+The @code{sb-aclrepl} module offers an Allegro CL-style
+Read-Eval-Print Loop for SBCL, with integrated inspector. Adding an
+debugger interface is planned.
@subsection Usage
Questions, comments, or bug reports should be sent to Kevin Rosenberg
(@email{kevin@@rosenberg.net}).
+
+@subsection Credits
+
+Allegro CL is a registered trademark of Franz Inc.
@cindex Hashing, cryptographic
The @code{sb-md5} module implements the RFC1321 MD5 Message Digest
-Algorithm.
+Algorithm. [FIXME cite]
@include fun-sb-md5-md5sum-file.texinfo
performed directly using the platform's arithmetic routines. It
implements the specification at
@uref{http://www.cliki.net/ROTATE-BYTE}.
-@comment except when someone scribbles all over it. Hmm.
+@comment FIXME: except when someone scribbles all over it. Hmm.
Bitwise rotation is a component of various cryptographic or hashing
algorithms: MD5, SHA-1, etc.; often these algorithms are specified on
-32-bit rings. [cite cite cite].
+32-bit rings. [FIXME cite cite cite].
@include fun-sb-rotate-byte-rotate-byte.texinfo
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 mailings lists. For mailing list
-addresses, @ref{More SBCL Information}.
+through the sbcl-help or sbcl-devel mailing lists. For mailing list
+addresses, @xref{More SBCL Information}.
@node Idiosyncrasies
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 the
-chapter on the compiler, @ref{The Compiler}.
+compiler from quite satisfying this principle, are discussed in
+@ref{The Compiler}.
SBCL is essentially a compiler-only implementation of Common
Lisp. That is, for all but a few special cases, @code{eval} creates a
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
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
@itemize
@item
-@code{defmethod} without @code{defgeneric}
+@code{defmethod} without a preceding @code{defgeneric};
@item
-multiple @code{defun}s of the same symbol
+multiple @code{defun}s of the same symbol in different units;
@item
special variables not named in the conventional @code{*foo*} style,
@include fun-sb-ext-purify.texinfo
-@code{sb-ext:truly-the} special form declares the type of the result
-of the operations, producing its argument; the declaration is not
-checked. In short: don't use it.
+The @code{sb-ext:truly-the} special form declares the type of the
+result of the operations, producing its argument; the declaration is
+not checked. In short: don't use it.
@include special-operator-sb-ext-truly-the.texinfo
When processing this program, the compiler will produce this warning:
@example
-file: /tmp/foo.lisp
-
-in: DEFUN FOO
-(ZOQ Y)
---> ROQ PLOQ +
-==>
-Y
-caught WARNING:
-Result is a SYMBOL, not a NUMBER.
+; file: /tmp/foo.lisp
+; in: DEFUN FOO
+; (ZOQ Y)
+; --> ROQ PLOQ
+; ==>
+; (+ Y 3)
+;
+; caught WARNING:
+; Asserted type NUMBER conflicts with derived type (VALUES SYMBOL &OPTIONAL).
@end example
In this example we see each of the six possible parts of a compiler
@enumerate
@item
-@samp{File: /tmp/foo.lisp} This is the name of the file that the
+@findex with-compilation-unit
+@samp{file: /tmp/foo.lisp} This is the name of the file that the
compiler read the relevant code from. The file name is displayed
because it may not be immediately obvious when there is an error
during compilation of a large system, especially when
@code{foo}.
@item
+@cindex Original Source
@samp{(ZOQ Y)} This is the @dfn{original source} form responsible for
the error. Original source means that the form directly appeared in
the original input to the compiler, i.e. in the lambda passed to
for the error.
@item
-@samp{--> ROQ PLOQ +} This is the @dfn{processing path} that the
+@cindex Processing Path
+@samp{--> ROQ PLOQ} This is the @dfn{processing path} that the
compiler used to produce the errorful code. The processing path is a
representation of the evaluated forms enclosing the actual source that
the compiler encountered when processing the original source. The
path is the first element of each form, or the form itself if the form
is not a list. These forms result from the expansion of macros or
source-to-source transformation done by the compiler. In this
-example, the enclosing evaluated forms are the calls to @code{roq},
-@code{ploq} and @code{+}. These calls resulted from the expansion of
-the @code{zoq} macro.
+example, the enclosing evaluated forms are the calls to @code{roq} and
+@code{ploq}. These calls resulted from the expansion of the
+@code{zoq} macro.
@item
-@samp{==> Y} This is the @dfn{actual source} responsible for the
+@cindex Actual Source
+@samp{==> (+ Y 3)} This is the @dfn{actual source} responsible for the
error. If the actual source appears in the explanation, then we print
the next enclosing evaluated form, instead of printing the actual
source twice. (This is the form that would otherwise have been the
with the evaluation of the reference to the variable @code{y}.
@item
-@samp{caught WARNING: Result is a SYMBOL, not a NUMBER.} This is the
-@dfn{explanation} of the problem. In this example, the problem is that
-@code{y} evaluates to a symbol, but is in a context where a number is
-required (the argument to @code{+}).
+@samp{caught WARNING: Asserted type NUMBER conflicts with derived type
+(VALUES SYMBOL &OPTIONAL).} This is the @dfn{explanation} of the
+problem. In this example, the problem is that, while the call to
+@code{+} requires that its arguments are all of type @code{number},
+the compiler has derived that @code{y} will evaluate to a
+@code{symbol}. Note that @samp{(VALUES SYMBOL &OPTIONAL)} expresses
+that @code{y} evaluates to precisely one value.
@end enumerate
@item
The actual source form is indented like the original source, but is
marked by a preceding @samp{==>} line.
-
+@comment no it isn't.
@item
The explanation is prefixed with the error severity, which can be
first. For example:
@example
-file: /tmp/foo.lisp
-
-in: DEFUN FOO
-(ZOQ Y)
---> ROQ
-==>
-(PLOQ (+ Y 3))
-caught STYLE-WARNING:
-undefined function: PLOQ
-
-==>
-(ROQ (PLOQ (+ Y 3)))
-caught STYLE-WARNING:
-undefined function: ROQ
+; file: /tmp/foo.lisp
+; in: DEFUN FOO
+; (ZOQ Y)
+; --> ROQ
+; ==>
+; (PLOQ (+ Y 3))
+;
+; caught STYLE-WARNING:
+; undefined function: PLOQ
+
+; ==>
+; (ROQ (PLOQ (+ Y 3)))
+;
+; caught STYLE-WARNING:
+; undefined function: ROQ
@end example
+@comment fixing that weird blank line might be good
In this example, the file, definition and original source are
identical for the two messages, so the compiler omits them in the
@node The Original and Actual Source
@comment node-name, next, previous, up
@subsection The Original and Actual Source
+@cindex Original Source
+@cindex Actual Source
The @emph{original source} displayed will almost always be a list. If
the actual source for an error message is a symbol, the original
gives this error message
@example
-in: DEFUN BAR
-(LET (A) (DECLARE (FIXNUM A)) (SETQ A (FOO X)) A)
-caught WARNING: The binding of A is not a FIXNUM:
-NIL
+; file: /tmp/foo.lisp
+; in: DEFUN BAR
+; (LET (A)
+; (DECLARE (FIXNUM A))
+; (SETQ A (FOO X))
+; A)
+;
+; caught WARNING:
+; Asserted type FIXNUM conflicts with derived type (VALUES NULL &OPTIONAL).
@end example
This error message is not saying ``there is a problem somewhere in
Compiling results in this error message:
@example
-in: DEFUN FOO
-(DOTIMES (I N *UNDEFINED*))
---> DO BLOCK LET TAGBODY RETURN-FROM
-==>
-(PROGN *UNDEFINED*)
-caught STYLE-WARNING:
-undefined variable: *UNDEFINED*
+; in: DEFUN FOO
+; (DOTIMES (I N *UNDEFINED*))
+; --> DO BLOCK LET TAGBODY RETURN-FROM
+; ==>
+; (PROGN *UNDEFINED*)
+;
+; caught WARNING:
+; undefined variable: *UNDEFINED*
@end example
Note that @code{do} appears in the processing path. This is because
@emph{note}, is used for problems which are too mild for the standard
condition classes, typically hints about how efficiency might be
improved.
-
+@comment mention sb-ext:compiler-note
@node Errors During Macroexpansion
@comment node-name, next, previous, up
gives this error:
@example
-in: DEFUN FOO
-(DO ((CURRENT L #) (# NIL)) (WHEN (EQ # E) (RETURN CURRENT)) )
-caught ERROR:
-(in macroexpansion of (DO # #))
-(hint: For more precise location, try *BREAK-ON-SIGNALS*.)
-DO step variable is not a symbol: (ATOM CURRENT)
+; in: DEFUN FOO
+; (DO ((CURRENT L (CDR CURRENT))
+; ((ATOM CURRENT) NIL))
+; (WHEN (EQ (CAR CURRENT) E) (RETURN CURRENT)))
+;
+; caught ERROR:
+; (in macroexpansion of (DO # #))
+; (hint: For more precise location, try *BREAK-ON-SIGNALS*.)
+; DO step variable is not a symbol: (ATOM CURRENT)
@end example
@subsection Read Errors
@cindex Read errors, compiler
-SBCL's compiler (unlike CMUCL's) does not attempt to recover from read
-errors when reading a source file, but instead just reports the
-offending character position and gives up on the entire source file.
+SBCL's compiler does not attempt to recover from read errors when
+reading a source file, but instead just reports the offending
+character position and gives up on the entire source file.
@c <!-- FIXME: How much control over error messages is in SBCL?
(@pxref{Efficiency}), the use of appropriate type declarations can be
very important for performance as well.
-The SBCL compiler, like the related compiler in CMUCL, treats type
-declarations much differently than other Lisp compilers. By default
-(@emph{i.e.}, at ordinary levels of the @code{safety} compiler
-optimization parameter), the compiler doesn't blindly believe most
-type declarations; it considers them assertions about the program that
-should be checked.
+@findex safety
+The SBCL compiler treats type declarations differently from most other
+Lisp compilers. By default (@emph{i.e.}, at ordinary levels of the
+@code{safety} compiler optimization parameter), the compiler doesn't
+blindly believe most type declarations; it considers them assertions
+about the program that should be checked.
+@findex satisfies
The SBCL compiler also has a greater knowledge of the
Common Lisp type system than other compilers. Support is incomplete
-only for the @code{not}, @code{and} and @code{satisfies}
-types.
+only for types involving the @code{satisfies} type specifier.
@c <!-- FIXME: See also sections \ref{advanced-type-stuff}
@c and \ref{type-inference}, once we snarf them from the
@c CMU CL manual. -->
+@c Also see my paper on improving Baker, when I get round to it.
@menu
* Type Errors at Compile Time::
Compilation produces this warning:
@example
-in: DEFUN RAZ
-(CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
---> LET COND IF COND IF COND IF
-==>
-(COND)
-caught WARNING: This is not a FIXNUM:
-NIL
+; in: DEFUN RAZ
+; (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
+; --> LET COND IF COND IF COND IF
+; ==>
+; (COND)
+;
+; caught WARNING:
+; This is not a FIXNUM:
+; NIL
@end example
In this case, the warning means that if @code{foo} isn't any of
executed), so it compiles the erroneous code (which will always signal
an error if it is executed) and gives a warning.
-
Type warnings are inhibited when the @code{sb-ext:inhibit-warnings}
optimization quality is @code{3}. @xref{Compiler Policy}. This
can be used in a local declaration to inhibit type warnings in a code
@cindex Compatibility with other Lisps
@c (should also have an entry in the non-ANSI-isms section)-->
-Since SBCL's compiler, like CMUCL's compiler, does much more
-comprehensive type checking than most Lisp compilers, SBCL may detect
-type errors in programs that have been debugged using other
-compilers. These errors are mostly incorrect declarations, although
-compile-time type errors can find actual bugs if parts of the program
-have never been tested.
+Since SBCL's compiler does much more comprehensive type checking than
+most Lisp compilers, SBCL may detect type errors in programs that have
+been debugged using other compilers. These errors are mostly incorrect
+declarations, although compile-time type errors can find actual bugs
+if parts of the program have never been tested.
Some incorrect declarations can only be detected by run-time type
checking. It is very important to initially compile a program with
whether to inline operations, which tend to increase the size of
programs. Use the value @code{0} with caution, since it can cause the
compiler to inline operations so indiscriminately that the net effect
-is to slow the program by causing cache misses or swapping.
+is to slow the program by causing cache misses or even swapping.
@c <!-- FIXME: old CMU CL compiler policy, should perhaps be adapted
@c _ for SBCL. (Unfortunately, the CMU CL docs are out of sync with the
redefine standard functions, users sometimes want to implicitly
redefine these functions when they are debugging using the
@code{trace} macro. Special-casing of standard functions can be
-inhibited using the @code{notinline} declaration.
+inhibited using the @code{notinline} declaration, but even then some
+phases of analysis such as type inferencing are applied by the
+compiler.
@item
The compiler can have multiple alternate implementations of standard
abbreviated by any unambiguous prefix: @command{help} can be typed as
@samp{h}, @samp{he}, etc. For convenience, some commands have
ambiguous one-letter abbreviations: @samp{f} for @command{frame}.
+@comment FIXME: what does that last bit mean?
The package is not significant in debugger commands; any symbol with the
name of a debugger command will work. If you want to show the value of
@itemize
@item
-@dfn{Variables} (@pxref{Variable Access}), which are the values being operated
-on, and
+@dfn{variables} (@pxref{Variable Access}), which are the values being operated
+on;
@item
-@dfn{Arguments} to the call (which are really just particularly
+@dfn{arguments} to the call (which are really just particularly
interesting variables), and
@item
-A current location (@pxref{Source Location Printing}), which is the place in
+a current location (@pxref{Source Location Printing}), which is the place in
the program where the function was running when it stopped to call
another function, or because of an interrupt or error.
then @samp{#<unavailable-arg>} will be printed instead of the argument
value.
+@vindex *debug-print-variable-alist*
Printing of argument values is controlled by
@code{*debug-print-variable-alist*}. @xref{Controlling Printing in
the Debugger}.
(here---expressions @code{x} and @code{y}) are also of type
@code{(unsigned-byte 32)}, 32-bit machine arithmetic can be used.
-
As of SBCL 0.8.5 ``good'' functions are @code{+}, @code{-};
@code{logand}, @code{logior}, @code{logxor}, @code{lognot} and their
combinations; and @code{ash} with the positive second
-argument. ``Good'' widths are 32 on HPPA, MIPS, PPC, Sparc and X86 and
-64 on Alpha. While it is possible to support smaller widths as well,
-currently it is not implemented.
+argument. ``Good'' widths are 32 on HPPA, MIPS, PPC, Sparc and x86 and
+64 on Alpha. While it is possible to support smaller widths as well,
+currently this is not implemented.
Lisp.
@menu
-* More Common Lisp Information::
-* More SBCL Information::
-* Overview::
+* More Common Lisp Information::
+* More SBCL Information::
+* Overview::
@end menu
@node More Common Lisp Information
@comment node-name, next, previous, up
-@section Where To Go For More Information about Common Lisp in General
+@section Sources of information about Common Lisp
Regardless of your ability level, two very useful resources for
-working with any implementation of Common Lisp are the ILISP package
-for Emacs at @uref{http://ilisp.cons.org} and the Common Lisp HyperSpec
-at @uref{http://www.lispworks.com/reference/HyperSpec/index.html}.
+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}.
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
-comp.lang.lisp FAQ for recent recommendations.
+@uref{news://comp.lang.lisp} FAQ for recent recommendations.
If you are an experienced programmer in other languages but need to
learn about Lisp, three books stand out.
@node More SBCL Information
@comment node-name, next, previous, up
-@section Where To Go For More Information About SBCL
+@section Sources of more information about SBCL
Before you read this user manual, you should probably read two other
things.
@itemize
@item
-The SBCL home page at @uref{http://sbcl.sourceforge.net/} has some
+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
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 (like @code{trace} does) are
+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.
@node Overview
@comment node-name, next, previous, up
-@section Overview Of SBCL, How It Works And Where It Came From
+@section History and Implementation
You can work productively with SBCL without knowing anything
understanding anything about where it came from, how it is
storage.
@item
-A word is a 32-bit quantity. The system has been ported to many
-processor architectures without altering this basic principle. Some
-hacks allow the system to run on the Alpha chip (a 64-bit
-architecture) but even there 32-bit words are used. The assumption
-that a word is 32 bits wide is implicit in hundreds of places in the
-system.
-
-@item
The system is implemented as a C program which is responsible for
supplying low-level services and loading a Lisp @file{.core}
file.
@end itemize
-
+
+@cindex Garbage Collection, generational
SBCL also inherited some newer architectural features from CMUCL. The
most important is that on some architectures it has a generational
garbage collector (``GC''), which has various implications (mostly
-good) for performance. These are discussed another chapter,
+good) for performance. These are discussed in another chapter,
@ref{Efficiency}.
SBCL has diverged from CMUCL in that SBCL is now essentially a
evaluated by calling @code{compile} and then calling @code{funcall} on
the returned result.
-
-The direct ancestor of SBCL is the X86 port of CMUCL. This port was in
+The direct ancestor of SBCL is the x86 port of CMUCL. This port was in
some ways the most cobbled-together of all the CMUCL ports, since a
number of strange changes had to be made to support the register-poor
-X86 architecture. Some things (like tracing and debugging) do not work
+x86 architecture. Some things (like tracing and debugging) do not work
particularly well there. SBCL should be able to improve in these areas
(and has already improved in some other areas), but it takes a while.
-On the x86, SBCL like the X86 port of CMUCL, uses a
+@cindex Garbage Collection, conservative
+On the x86 SBCL -- like the x86 port of CMUCL -- uses a
@emph{conservative} GC. This means that it doesn't maintain a strict
separation between tagged and untagged data, instead treating some
untagged data (e.g. raw floating point numbers) as possibly-tagged
* sbcl: (sbcl). The Steel Bank Common Lisp compiler
@end direntry
-
-
@copying
@quotation
-This manual is part of the SBCL software system. See the @file{README} file
-for more information.
+This manual is part of the SBCL software system. See the
+@file{README} file for more information.
This manual is largely derived from the manual for the CMUCL system,
which was produced at Carnegie Mellon University and later released
@titlepage
@title SBCL User Manual
-@subtitle SBCL Version @value{VERSION}
+@subtitle SBCL version @value{VERSION}
@subtitle @value{UPDATE-MONTH}
@c @author The CMUCL and SBCL teams
;;; 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.9.47"
+"0.8.9.48"
projects / sbcl.git / commitdiff