1.0.19.19: manual updates

[sbcl.git] / doc / manual / compiler.texinfo

diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo
index a8aab4f..9a3533d 100644 (file)
--- a/doc/manual/compiler.texinfo
+++ b/doc/manual/compiler.texinfo
@@ -11,11 +11,12 @@ naive translation. Efficiency issues are sufficiently varied and
 separate that they have their own chapter, @ref{Efficiency}.
 
 @menu
 separate that they have their own chapter, @ref{Efficiency}.
 
 @menu

-* Diagnostic Messages::         
+* Diagnostic Messages::

 * Handling of Types::           
 * Compiler Policy::             
 * Compiler Errors::             
 * Open Coding and Inline Expansion::  
 * Handling of Types::           
 * Compiler Policy::             
 * Compiler Errors::             
 * Open Coding and Inline Expansion::  

+* Interpreter::

 @end menu
 
 @node  Diagnostic Messages
 @end menu
 
 @node  Diagnostic Messages

@@ -77,6 +78,15 @@ Cancels the effect of a previous @code{sb-ext:muffle-condition}
 declaration.
 @end deffn
 
 declaration.
 @end deffn
 

+Various details of @emph{how} the compiler messages are printed can be
+controlled via the alist
+@code{sb-ext:*compiler-print-variable-alist*}.
+
+@include var-sb-ext-star-compiler-print-variable-alist-star.texinfo
+
+For information about muffling warnings signaled outside of the
+compiler, see @ref{Customization Hooks for Users}.
+

 @c <!-- FIXME: How much control over error messages is in SBCL?
 @c      _     How much should be? How much of this documentation should
 @c      _     we save or adapt? 
 @c <!-- FIXME: How much control over error messages is in SBCL?
 @c      _     How much should be? How much of this documentation should
 @c      _     we save or adapt? 

@@ -99,15 +109,6 @@ declaration.
 @c      _   which is useful when debugging macros.
 @c      _ \end{defvar}
 @c      _ 
 @c      _   which is useful when debugging macros.
 @c      _ \end{defvar}
 @c      _ 

-@c      _ \begin{defvar}{}{error-print-length}
-@c      _   \defvarx{error-print-level}
-@c      _ 
-@c      _   These variables are the print level and print length used in
-@c      _   printing error messages.  The default values are \code{5} and
-@c      _   \code{3}.  If null, the global values of \code{*print-level*} and
-@c      _   \code{*print-length*} are used.
-@c      _ \end{defvar}
-@c      _ 

 @c      _ \begin{defmac}{extensions:}{define-source-context}{%
 @c      _     \args{\var{name} \var{lambda-list} \mstar{form}}}
 @c      _ 
 @c      _ \begin{defmac}{extensions:}{define-source-context}{%
 @c      _     \args{\var{name} \var{lambda-list} \mstar{form}}}
 @c      _ 

@@ -124,12 +125,11 @@ declaration.
 @c      _ 
 @c      _ -->
 
 @c      _ 
 @c      _ -->
 

-

 @node  Diagnostic Severity
 @comment  node-name,  next,  previous,  up
 @subsection Diagnostic Severity
 @cindex Severity of compiler messages
 @node  Diagnostic Severity
 @comment  node-name,  next,  previous,  up
 @subsection Diagnostic Severity
 @cindex Severity of compiler messages

-@cindex compiler diagnostic severity
+@cindex Compiler Diagnostic Severity

 @tindex error
 @tindex warning
 @tindex style-warning
 @tindex error
 @tindex warning
 @tindex style-warning

@@ -393,7 +393,7 @@ This message is not saying ``there is a problem somewhere in this
 @node The Processing Path
 @comment  node-name,  next,  previous,  up
 @subsubsection The Processing Path
 @node The Processing Path
 @comment  node-name,  next,  previous,  up
 @subsubsection The Processing Path

-@cindex Processing path
+@cindex Processing Path

 @cindex Macroexpansion
 @cindex Source-to-source transformation
 
 @cindex Macroexpansion
 @cindex Source-to-source transformation
 

@@ -516,21 +516,27 @@ selectable via @code{optimize} declarations.
 
 @item Full Type Checks
 All declarations are considered assertions to be checked at runtime,
 
 @item Full Type Checks
 All declarations are considered assertions to be checked at runtime,

-and all type checks are precise.
+and all type checks are precise. The default compilation policy
+provides full type checks.

 
 

-Used when @code{(>= safety (max speed space compilation-speed)}. The
-default compilation policy provides full type checks.
+Used when @code{(or (>= safety 2) (>= safety speed 1))}.

 
 @item Weak Type Checks
 
 @item Weak Type Checks

-Any or all type declarations may be believed without runtime
-assertions, and assertions that are done may be imprecise.
+Declared types may be simplified into faster to check supertypes: for example,
+@code{(and unsigned-byte fixnum)} is simplified into @code{fixnum}.
+
+@strong{Note}: it is relatively easy to corrupt the heap when weak
+type checks are used if the program contains type-errors.

 
 

-Used when @code{(< 0 safety (max speed space compilation-speed)}.
+Used when @code{(and (< safety 2) (< safety speed))}

 
 @item No Type Checks
 All declarations are believed without assertions. Also disables
 argument count and array bounds checking.
 
 
 @item No Type Checks
 All declarations are believed without assertions. Also disables
 argument count and array bounds checking.
 

+@strong{Note}: any type errors in code where type checks are not
+performed are liable to corrupt the heap.
+

 Used when @code{(= safety 0)}.
 
 @end table
 Used when @code{(= safety 0)}.
 
 @end table

@@ -862,6 +868,7 @@ is to slow the program by causing cache misses or even swapping.
 @c      _  In addition to suppressing type checks, \code{0} also suppresses
 @c      _  argument count checking, unbound-symbol checking and array bounds
 @c      _  checks.
 @c      _  In addition to suppressing type checks, \code{0} also suppresses
 @c      _  argument count checking, unbound-symbol checking and array bounds
 @c      _  checks.

+@c      _  ... and checking of tag existence in RETURN-FROM and GO.

 @c      _
 @c      _\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings
 @c      _    optimization quality}This is a CMU extension that determines how
 @c      _
 @c      _\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings
 @c      _    optimization quality}This is a CMU extension that determines how

@@ -1019,8 +1026,8 @@ character position and gives up on the entire source file.
 @comment  node-name,  next,  previous,  up
 @section Open Coding and Inline Expansion
 @cindex Open-coding
 @comment  node-name,  next,  previous,  up
 @section Open Coding and Inline Expansion
 @cindex Open-coding

-@cindex inline expansion
-@cindex static functions
+@cindex Inline expansion
+@cindex Static functions

 
 Since Common Lisp forbids the redefinition of standard functions, the
 compiler can have special knowledge of these standard functions
 
 Since Common Lisp forbids the redefinition of standard functions, the
 compiler can have special knowledge of these standard functions

@@ -1091,3 +1098,20 @@ open-coded. Even when not open-coded, a call to a standard function
 may be transformed into a different function call (as in the last
 example) or compiled as @emph{static call}. Static function call uses
 a more efficient calling convention that forbids redefinition.
 may be transformed into a different function call (as in the last
 example) or compiled as @emph{static call}. Static function call uses
 a more efficient calling convention that forbids redefinition.

+
+@node  Interpreter
+@comment  node-name,  next,  previous,  up
+@section Interpreter
+@cindex Interpreter
+@vindex sb-ext:*evaluator-mode*
+
+By default SBCL implements @code{eval} by calling the native code
+compiler. SBCL also includes an interpreter for use in special cases
+where using the compiler is undesirable, for example due to compilation
+overhead. Unlike in some other Lisp implementations, in SBCL interpreted
+code is not safer or more debuggable than compiled code.
+
+Switching between the compiler and the interpreter is done using the
+special variable @code{sb-ext:*evaluator-mode*}. As of 0.9.17, valid
+values for @code{sb-ext:*evaluator-mode*} are @code{:compile} and
+@code{:interpret}.