0.8.14.13: Step SBCL, step!

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

diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo
index 3713a9a..3e639d4 100644 (file)
--- a/doc/manual/debugger.texinfo
+++ b/doc/manual/debugger.texinfo
@@ -1,6 +1,6 @@
-@node  The Debugger, Efficiency, The Compiler, Top
+@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,9 +35,10 @@ indistinguishable from interpreted code debugging.
 * Exiting Commands::            
 * Information Commands::        
 * Function Tracing::            
 * Exiting Commands::            
 * Information Commands::        
 * Function Tracing::            

+* Single Stepping::             

 @end menu
 
 @end menu
 

-@node  Starting the Debugger, The Debugger Command Loop, The Debugger, The Debugger
+@node  Starting the Debugger

 @comment  node-name,  next,  previous,  up
 @section Starting the Debugger
 
 @comment  node-name,  next,  previous,  up
 @section 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,8 +79,22 @@ 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.

 
 

-@node  The Debugger Command Loop, Controlling Printing in the Debugger, Starting the Debugger, The Debugger
+@include var-sb-ext-star-invoke-debugger-hook-star.texinfo
+
+
+@node  The Debugger Command Loop

 @comment  node-name,  next,  previous,  up
 @section The Debugger Command Loop
 @cindex Evaluation, in the debugger
 @comment  node-name,  next,  previous,  up
 @section The Debugger Command Loop
 @cindex Evaluation, in the debugger

@@ -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

@@ -117,14 +133,14 @@ current frame.  For more information on debugger variable access, see
 @ref{Variable Access}.
 
 
 @ref{Variable Access}.
 
 

-@node Controlling Printing in the Debugger, Stack Frames, The Debugger Command Loop, The Debugger
+@node Controlling Printing in the Debugger

 @comment  node-name,  next,  previous,  up
 @section Controlling Printing in the Debugger
 
 In the debugger, it is possible to override the printing behaviour of
 the REPL.
 
 @comment  node-name,  next,  previous,  up
 @section Controlling Printing in the Debugger
 
 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.

@@ -140,7 +156,7 @@ initially.
 
 @end defvr
 
 
 @end defvr
 

-@node  Stack Frames, Variable Access, Controlling Printing in the Debugger, The Debugger
+@node  Stack Frames

 @comment  node-name,  next,  previous,  up
 @section Stack Frames
 @cindex Stack frames
 @comment  node-name,  next,  previous,  up
 @section Stack Frames
 @cindex Stack frames

@@ -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.
 

@@ -176,7 +192,7 @@ another function, or because of an interrupt or error.
 * Unknown Locations and Interrupts::  
 @end menu
 
 * Unknown Locations and Interrupts::  
 @end menu
 

-@node  Stack Motion, How Arguments are Printed, Stack Frames, Stack Frames
+@node  Stack Motion

 @comment  node-name,  next,  previous,  up
 @subsection Stack Motion
 
 @comment  node-name,  next,  previous,  up
 @subsection Stack Motion
 

@@ -209,7 +225,7 @@ was entered.
 @end deffn
 
 
 @end deffn
 
 

-@node  How Arguments are Printed, Function Names, Stack Motion, Stack Frames
+@node  How Arguments are Printed

 @comment  node-name,  next,  previous,  up
 @subsection How Arguments are Printed
 
 @comment  node-name,  next,  previous,  up
 @subsection How Arguments are Printed
 

@@ -288,12 +304,13 @@ 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}.
 
 

-@node  Function Names, Funny Frames, How Arguments are Printed, Stack Frames
+@node  Function Names

 @comment  node-name,  next,  previous,  up
 @subsection Function Names
 
 @comment  node-name,  next,  previous,  up
 @subsection Function Names
 

@@ -320,7 +337,7 @@ that encloses or expanded into the lambda, or the outermost enclosing
 form if there is no @code{def@var{mumble}}.
 
 
 form if there is no @code{def@var{mumble}}.
 
 

-@node  Funny Frames, Debug Tail Recursion, Function Names, Stack Frames
+@node  Funny Frames

 @comment  node-name,  next,  previous,  up
 @subsection Funny Frames
 @cindex External entry points
 @comment  node-name,  next,  previous,  up
 @subsection Funny Frames
 @cindex External entry points

@@ -385,7 +402,7 @@ are present in the debugger, see @ref{Debugger Policy Control}.
 @c @ref{open-coding}
 
 
 @c @ref{open-coding}
 
 

-@node  Debug Tail Recursion, Unknown Locations and Interrupts, Funny Frames, Stack Frames
+@node  Debug Tail Recursion

 @comment  node-name,  next,  previous,  up
 @subsection Debug Tail Recursion
 @cindex Tail recursion
 @comment  node-name,  next,  previous,  up
 @subsection Debug Tail Recursion
 @cindex Tail recursion

@@ -435,7 +452,7 @@ optimization quality is greater than @code{2}.
 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
 
 
 @c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
 
 

-@node Unknown Locations and Interrupts,  , Debug Tail Recursion, Stack Frames
+@node Unknown Locations and Interrupts

 @comment  node-name,  next,  previous,  up
 @subsection Unknown Locations and Interrupts
 @cindex Unknown code locations
 @comment  node-name,  next,  previous,  up
 @subsection Unknown Locations and Interrupts
 @cindex Unknown code locations

@@ -483,7 +500,7 @@ when the real problem is that the current stack frame can't be
 located.  If this happens, return from the interrupt and try again.
 
 
 located.  If this happens, return from the interrupt and try again.
 
 

-@node Variable Access, Source Location Printing, Stack Frames, The Debugger
+@node Variable Access

 @comment  node-name,  next,  previous,  up
 @section Variable Access
 @cindex Debug variables
 @comment  node-name,  next,  previous,  up
 @section Variable Access
 @cindex Debug variables

@@ -545,7 +562,7 @@ that must unambiguously complete to the name of a valid variable.
 * Note On Lexical Variable Access::  
 @end menu
 
 * Note On Lexical Variable Access::  
 @end menu
 

-@node Variable Value Availability, Note On Lexical Variable Access, Variable Access, Variable Access
+@node Variable Value Availability

 @comment  node-name,  next,  previous,  up
 @subsection Variable Value Availability
 @cindex Availability of debug variables
 @comment  node-name,  next,  previous,  up
 @subsection Variable Value Availability
 @cindex Availability of debug variables

@@ -628,7 +645,7 @@ values to be available, and even then, values are only available at
 known locations.
 
 
 known locations.
 
 

-@node  Note On Lexical Variable Access,  , Variable Value Availability, Variable Access
+@node  Note On Lexical Variable Access

 @comment  node-name,  next,  previous,  up
 @subsection Note On Lexical Variable Access
 
 @comment  node-name,  next,  previous,  up
 @subsection Note On Lexical Variable Access
 

@@ -647,7 +664,7 @@ proved the variable could never take on.  This may result in bad
 things happening.
 
 
 things happening.
 
 

-@node Source Location Printing, Debugger Policy Control, Variable Access, The Debugger
+@node Source Location Printing

 @comment  node-name,  next,  previous,  up
 @section Source Location Printing
 @cindex Source location printing, debugger
 @comment  node-name,  next,  previous,  up
 @section Source Location Printing
 @cindex Source location printing, debugger

@@ -726,7 +743,7 @@ print:
 * Source Location Availability::  
 @end menu
 
 * Source Location Availability::  
 @end menu
 

-@node  How the Source is Found, Source Location Availability, Source Location Printing, Source Location Printing
+@node  How the Source is Found

 @comment  node-name,  next,  previous,  up
 @subsection How the Source is Found
 
 @comment  node-name,  next,  previous,  up
 @subsection How the Source is Found
 

@@ -783,7 +800,7 @@ into something different, or if a read-macro ever returns the same
 @code{##} in perverted ways, you don't need to worry about this.
 
 
 @code{##} in perverted ways, you don't need to worry about this.
 
 

-@node  Source Location Availability,  , How the Source is Found, Source Location Printing
+@node  Source Location Availability

 @comment  node-name,  next,  previous,  up
 @subsection Source Location Availability
 @cindex Debug optimization quality
 @comment  node-name,  next,  previous,  up
 @subsection Source Location Availability
 @cindex Debug optimization quality

@@ -835,7 +852,7 @@ next conditional (but watch out because the compiler may have changed the
 program on you.)
 
 
 program on you.)
 
 

-@node Debugger Policy Control, Exiting Commands, Source Location Printing, The Debugger
+@node Debugger Policy Control

 @comment  node-name,  next,  previous,  up
 @section Debugger Policy Control
 @cindex Policy, debugger
 @comment  node-name,  next,  previous,  up
 @section Debugger Policy Control
 @cindex Policy, debugger

@@ -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

@@ -923,7 +944,7 @@ but the call is to an optimized local version of the function, not to
 the original function.
 
 
 the original function.
 
 

-@node  Exiting Commands, Information Commands, Debugger Policy Control, The Debugger
+@node  Exiting Commands

 @comment  node-name,  next,  previous,  up
 @section Exiting Commands
 
 @comment  node-name,  next,  previous,  up
 @section Exiting Commands
 

@@ -958,7 +979,7 @@ is of the same type as SBCL expects the stack frame to return.
 @end deffn
 
 
 @end deffn
 
 

-@node  Information Commands, Function Tracing, Exiting Commands, The Debugger
+@node  Information Commands

 @comment  node-name,  next,  previous,  up
 @section Information Commands
 
 @comment  node-name,  next,  previous,  up
 @section Information Commands
 

@@ -990,16 +1011,15 @@ 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

@@ -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

@@ -1137,7 +1151,7 @@ Displays all the frames from the current to the bottom.  Only shows
 @c @end example
 
 
 @c @end example
 
 

-@node  Function Tracing,  , Information Commands, The Debugger
+@node  Function Tracing

 @comment  node-name,  next,  previous,  up
 @section Function Tracing
 @cindex Tracing
 @comment  node-name,  next,  previous,  up
 @section Function Tracing
 @cindex Tracing

@@ -1148,20 +1162,50 @@ their results whenever they are called.  Options allow conditional
 printing of the trace information and conditional breakpoints on
 function entry or exit.
 
 printing of the trace information and conditional breakpoints on
 function entry or exit.
 

-@comment rudi 2004-03-26: The docstring for `trace' is quite comprehensive,
-@comment so refer to it (see also ``OAOO'')
-The docstrings for @code{trace} and @code{untrace} explain SBCL's
-tracing facility.
+@include macro-common-lisp-trace.texinfo
+
+@include macro-common-lisp-untrace.texinfo

 
 

-@comment FIXME rudi 2004-03-26: revive the documentation of variables
-@comment describing trace behaviour: *trace-encapsulate-default*,
-@comment *max-trace-indentation* and friends.  Some of these are
-@comment mentioned (perhaps under different names) in the cmucl
-@comment manual.
+@include var-sb-debug-star-trace-indentation-step-star.texinfo
+
+@include var-sb-debug-star-max-trace-indentation-star.texinfo
+
+@include var-sb-debug-star-trace-encapsulate-default-star.texinfo
+
+@include var-sb-debug-star-trace-values-star.texinfo

 
 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
 @comment 0.8.9) in a state of flux.  When it's sorted out, revive the
 @comment cmucl documentation.
 
 
 @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
 @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