From ef8fd235fa2ca39e444710d1bc275acbc8d3279c Mon Sep 17 00:00:00 2001 From: Christophe Rhodes Date: Fri, 16 Apr 2004 14:17:39 +0000 Subject: [PATCH] 0.8.9.48: Just documentation ... make the compiler messages in the Compiler chapter match reality slightly more; ... Slightly Less Capitalization All Over The Place When It's Not Really Necessary (I realise this may be controversial :-) ... more index entries, etc; ... annotate various bits with FIXMEs --- contrib/sb-aclrepl/sb-aclrepl.texinfo | 12 +- contrib/sb-md5/sb-md5.texinfo | 2 +- contrib/sb-rotate-byte/sb-rotate-byte.texinfo | 4 +- doc/manual/beyond-ansi.texinfo | 21 ++- doc/manual/compiler.texinfo | 181 ++++++++++++++----------- doc/manual/debugger.texinfo | 10 +- doc/manual/efficiency.texinfo | 7 +- doc/manual/intro.texinfo | 50 ++++--- doc/manual/sbcl.texinfo | 8 +- version.lisp-expr | 2 +- 10 files changed, 161 insertions(+), 136 deletions(-) diff --git a/contrib/sb-aclrepl/sb-aclrepl.texinfo b/contrib/sb-aclrepl/sb-aclrepl.texinfo index 07eb17b..c8a2fc1 100644 --- a/contrib/sb-aclrepl/sb-aclrepl.texinfo +++ b/contrib/sb-aclrepl/sb-aclrepl.texinfo @@ -3,9 +3,11 @@ @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 @@ -43,3 +45,7 @@ some of the features of @code{sb-aclrepl}: 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. diff --git a/contrib/sb-md5/sb-md5.texinfo b/contrib/sb-md5/sb-md5.texinfo index 5de3f57..d43db06 100644 --- a/contrib/sb-md5/sb-md5.texinfo +++ b/contrib/sb-md5/sb-md5.texinfo @@ -3,7 +3,7 @@ @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 diff --git a/contrib/sb-rotate-byte/sb-rotate-byte.texinfo b/contrib/sb-rotate-byte/sb-rotate-byte.texinfo index ff908d1..54736e2 100644 --- a/contrib/sb-rotate-byte/sb-rotate-byte.texinfo +++ b/contrib/sb-rotate-byte/sb-rotate-byte.texinfo @@ -9,10 +9,10 @@ rotation, with an efficient implementation for operations which can be 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 diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index 82d824f..5de13f9 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -23,8 +23,8 @@ 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 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 @@ -37,8 +37,8 @@ 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 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 @@ -48,6 +48,7 @@ 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 @@ -57,11 +58,9 @@ 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 @@ -82,10 +81,10 @@ e.g. @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, @@ -393,9 +392,9 @@ generational garbage collectors. @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 diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo index 835a4d5..d404ef9 100644 --- a/doc/manual/compiler.texinfo +++ b/doc/manual/compiler.texinfo @@ -57,15 +57,15 @@ The main problem with this program is that it is trying to add 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 @@ -74,7 +74,8 @@ error message: @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 @@ -91,6 +92,7 @@ forms, then they are all printed from the outside in, separated by @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 @@ -99,19 +101,21 @@ this example, the expansion of the @code{zoq} macro was responsible 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 @@ -119,10 +123,13 @@ last form of the processing path.) In this example, the problem is 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 @@ -143,7 +150,7 @@ Each line of the processing path is prefixed with @samp{-->} @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 @@ -159,21 +166,23 @@ compiler omits as much of the second message as in common with the 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 @@ -192,6 +201,8 @@ processing path will also be omitted. @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 @@ -221,10 +232,15 @@ form. For example, compiling this function 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 @@ -249,13 +265,14 @@ don't write macros, you can probably ignore it. Consider this example: 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 @@ -305,7 +322,7 @@ these classes. The fourth level of compiler error severity, @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 @@ -327,12 +344,15 @@ example, this definition: 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 @@ -341,9 +361,9 @@ DO step variable is not a symbol: (ATOM CURRENT) @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 +@c Also see my paper on improving Baker, when I get round to it. @menu * Type Errors at Compile Time:: @@ -462,13 +483,15 @@ this code fragment: 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 @@ -484,7 +507,6 @@ compiler can't always prove this code is dead (could never be 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 @@ -566,12 +588,11 @@ nonexistent runtime checking. @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 @@ -806,7 +827,7 @@ The value of @code{space} mostly influences the compiler's decision 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