0.8.16.43: Fixes for various CLOS/MOP bugs

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

diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo
index 493471c..0d018f9 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

@@ -139,21 +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} 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.
-@lisp
-((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
-@end lisp
-The variables in the @code{car} position are bound to the values in
-the @code{cdr} during the execution of some debug commands.  When
-evaluating arbitrary expressions in the debugger, the normal values of
-the printer control variables are in effect. @c FIXME: is this correct?
-@code{*debug-print-variable-alist*} does not contain any bindings
-initially.
-
-@end defvr
+@include var-sb-ext-star-debug-print-variable-alist-star.texinfo

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

@@ -789,7 +776,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

@@ -829,7 +816,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},

@@ -900,7 +887,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

@@ -918,6 +905,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

@@ -1002,24 +993,24 @@ proceed cases.
 @end deffn
 
 @deffn {Debugger Command} backtrace [@var{n}]
 @end deffn
 
 @deffn {Debugger Command} backtrace [@var{n}]

-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*}.
+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
 
 @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

@@ -1064,12 +1055,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

@@ -1180,5 +1165,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