0.8.16.2: TYPE-ERROR for ERROR

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

diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo
index 040c49c..6a9e137 100644 (file)
--- a/doc/manual/debugger.texinfo
+++ b/doc/manual/debugger.texinfo
@@ -1,6 +1,6 @@
-@node  The Debugger
+@node Debugger

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@chapter The Debugger
+@chapter Debugger

 @cindex Debugger
 
 The SBCL debugger (as the CMUCL debugger it was derived from) has very
 @cindex Debugger
 
 The SBCL debugger (as the CMUCL debugger it was derived from) has very

@@ -35,6 +35,7 @@ indistinguishable from interpreted code debugging.
 * Exiting Commands::            
 * Information Commands::        
 * Function Tracing::            
 * Exiting Commands::            
 * Information Commands::        
 * Function Tracing::            

+* Single Stepping::             

 @end menu
 
 @node  Starting the Debugger
 @end menu
 
 @node  Starting the Debugger

@@ -55,7 +56,7 @@ or
 
 @item
 the debugger is explicitly entered with the Lisp @code{break} or
 
 @item
 the debugger is explicitly entered with the Lisp @code{break} or

-@code{debug} functions.
+@code{invoke-debugger} functions.

 
 @end itemize
 
 
 @end itemize
 

@@ -78,6 +79,20 @@ execution after this error.  In this case, both options return to
 top-level.  After printing its banner, the debugger prints the current
 frame and the debugger prompt.
 
 top-level.  After printing its banner, the debugger prints the current
 frame and the debugger prompt.
 

+When the debugger is invoked by a condition, ANSI mandates that the
+value of @code{*debugger-hook*}, if any, be called with two arguments:
+the condition that caused the debugger to be invoked and the previous
+value of @code{*debugger-hook*}. When this happens,
+@code{*debugger-hook*} is bound to NIL to prevent recursive
+errors. However, ANSI also mandates that @code{*debugger-hook*} not be
+invoked when the debugger is to be entered by the @code{break}
+function. For users who wish to provide an alternate debugger
+interface (and thus catch @code{break} entries into the debugger),
+SBCL provides @code{sb-ext:*invoke-debugger-hook*}, which is invoked
+during any entry into the debugger.
+
+@include var-sb-ext-star-invoke-debugger-hook-star.texinfo
+

 
 @node  The Debugger Command Loop
 @comment  node-name,  next,  previous,  up
 
 @node  The Debugger Command Loop
 @comment  node-name,  next,  previous,  up

@@ -92,6 +107,7 @@ commands prompt for additional input.  Debugger commands can be
 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}.
 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
 
 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

@@ -124,7 +140,7 @@ current frame.  For more information on debugger variable access, see
 In the debugger, it is possible to override the printing behaviour of
 the REPL.
 
 In the debugger, it is possible to override the printing behaviour of
 the REPL.
 

-@defvr {Variable} *debug-print-variable-alist*
+@defvr {Variable} sb-debug:*debug-print-variable-alist*

 
 An association list describing new bindings for special variables
 (typically *PRINT-FOO* variables) to be used within the debugger, e.g.
 
 An association list describing new bindings for special variables
 (typically *PRINT-FOO* variables) to be used within the debugger, e.g.

@@ -152,15 +168,15 @@ what it is doing.  Frames have:
 @itemize
 
 @item
 @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
 
 @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
 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.
 
 the program where the function was running when it stopped to call
 another function, or because of an interrupt or error.
 

@@ -288,6 +304,7 @@ unavailable or not known to be available (@pxref{Variable Access}),
 then @samp{#<unavailable-arg>} will be printed instead of the argument
 value.
 
 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}.
 Printing of argument values is controlled by
 @code{*debug-print-variable-alist*}.  @xref{Controlling Printing in
 the Debugger}.

@@ -773,7 +790,7 @@ form have been added or deleted.)
 If the heuristic doesn't work, the displayed source will be wrong, but will
 probably be near the actual source.  If the ``shape'' of the top-level form in
 the source file is too different from the original form, then an error will be
 If the heuristic doesn't work, the displayed source will be wrong, but will
 probably be near the actual source.  If the ``shape'' of the top-level form in
 the source file is too different from the original form, then an error will be

-signaled.  When the heuristic is used, the the source location commands are
+signaled.  When the heuristic is used, the source location commands are

 noticeably slowed.
 
 Source location printing can also be confused if (after the source was
 noticeably slowed.
 
 Source location printing can also be confused if (after the source was

@@ -813,7 +830,7 @@ some properties of the block start location:
 
 @item The block start location may be the same as the true location.
 
 
 @item The block start location may be the same as the true location.
 

-@item The block start location will never be later in the the
+@item The block start location will never be later in the 

 program's flow of control than the true location.
 
 @item No conditional control structures (such as @code{if},
 program's flow of control than the true location.
 
 @item No conditional control structures (such as @code{if},

@@ -884,7 +901,7 @@ Level @code{1} plus all interned local variables, source location
 information, and lifetime information that tells the debugger when
 arguments are available (even when @code{speed} is @code{3} or the
 argument is set).
 information, and lifetime information that tells the debugger when
 arguments are available (even when @code{speed} is @code{3} or the
 argument is set).

-
+ 

 @item > 2
 Any level greater than @code{2} gives level @code{2} and in addition
 disables tail-call optimization, so that the backtrace will contain
 @item > 2
 Any level greater than @code{2} gives level @code{2} and in addition
 disables tail-call optimization, so that the backtrace will contain

@@ -902,6 +919,10 @@ If @code{debug} is greater than both @code{speed} and @code{space},
 the command @command{return} can be used to continue execution by
 returning a value from the current stack frame.
 
 the command @command{return} can be used to continue execution by
 returning a value from the current stack frame.
 

+If @code{debug} is also at least 2, then  the code is @emph{partially
+steppable}. If @code{debug} is 3, the code is @emph{fully steppable}.
+@xref{Single Stepping}, for details.
+

 @end table
 
 As you can see, if the @code{speed} quality is @code{3}, debugger performance is
 @end table
 
 As you can see, if the @code{speed} quality is @code{3}, debugger performance is

@@ -990,20 +1011,19 @@ Displays all the frames from the current to the bottom.  Only shows
 @var{n} frames if specified.  The printing is controlled by @code{*debug-print-variable-alist*}.
 @end deffn
 
 @var{n} frames if specified.  The printing is controlled by @code{*debug-print-variable-alist*}.
 @end deffn
 

-@comment  FIXME (rudi 2004-03-31): sbcl doesn't support breakpoints
-@comment  and stepping as of version 0.8.9.  The `list-locations'
-@comment  command works, but executing a function leads to an error
-@comment  when a breakpoint is hit.  When stepping works, the
-@comment  commented-out section below should be reinstated and the
-@comment  example output updated to correspont to sbcl's behaviour.
+@deffn {Debugger Command} step
+Selects the @code{continue} restart if one exists and starts single stepping.
+@xref{Single Stepping}.
+@end deffn
+
+@c The new instrumentation based single stepper doesn't support
+@c the following commands, but BREAKPOINT at least should be
+@c resurrectable via (TRACE FOO :BREAK T).

 
 

-@c @node  Breakpoint Commands, , Information Commands, The Debugger
-@c @comment  node-name,  next,  previous,  up
-@c @section Breakpoint Commands

 @c @cindex Breakpoints
 
 @c SBCL supports setting of breakpoints inside compiled functions and
 @c @cindex Breakpoints
 
 @c SBCL supports setting of breakpoints inside compiled functions and

-@c stepping of compiled code.  Breakpoints can only be set at at known
+@c stepping of compiled code.  Breakpoints can only be set at known

 @c locations (@pxref{Unknown Locations and Interrupts}), so these
 @c commands are largely useless unless the @code{debug} optimize quality
 @c is at least @code{2} (@pxref{Debugger Policy Control}).  These
 @c locations (@pxref{Unknown Locations and Interrupts}), so these
 @c commands are largely useless unless the @code{debug} optimize quality
 @c is at least @code{2} (@pxref{Debugger Policy Control}).  These

@@ -1048,12 +1068,6 @@ Displays all the frames from the current to the bottom.  Only shows
 @c is specified, delete all breakpoints.
 @c @end deffn
 
 @c is specified, delete all breakpoints.
 @c @end deffn
 

-@c @deffn {Debugger Command} step
-@c Step to the next possible breakpoint location in the current function.
-@c This always steps over function calls, instead of stepping into them.
-@c @end deffn
-
-

 @c @menu
 @c * Breakpoint Example::          
 @c @end menu
 @c @menu
 @c * Breakpoint Example::          
 @c @end menu

@@ -1164,5 +1178,34 @@ function entry or exit.
 @comment 0.8.9) in a state of flux.  When it's sorted out, revive the
 @comment cmucl documentation.
 
 @comment 0.8.9) in a state of flux.  When it's sorted out, revive the
 @comment cmucl documentation.
 

+@node Single Stepping
+@comment  node-name,  next,  previous,  up
+@section Single Stepping
+@cindex Stepper
+@cindex Single Stepping
+
+SBCL includes an instrumentation based single-stepper for compiled
+code, that can be invoked via the @code{step} macro, or from within
+the debugger. @xref{Debugger Policy Control}, for details on enabling
+stepping for compiled code.
+
+Compiled code can be unsteppable, partially steppable, or fully steppable.
+
+@table @strong

 
 

+@item Unsteppable
+Single stepping is not possible.
+
+@item Partially steppable
+Single stepping is possible at sequential function call granularity:
+nested function calls cannot be stepped into, and no intermediate
+values are available.
+
+@item Fully steppable
+Single stepping is possible at individual function call argument
+granularity, nested calls can be stepped into, and intermediate values
+are available.
+
+@end table

 
 

+@include macro-common-lisp-step.texinfo