X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fdebugger.texinfo;h=0d018f9c464d908d45f9560281baa553a1eafebc;hb=f4e8bca5eaa6e6db42299fe2f3852fb2e07508c7;hp=86f6ad295b327af646cf29e0330cf2241f9e6ec6;hpb=01b53542be411ba6ede003da5e7292e16602ab6e;p=sbcl.git diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 86f6ad2..0d018f9 100644 --- a/doc/manual/debugger.texinfo +++ b/doc/manual/debugger.texinfo @@ -1,3 +1,6 @@ +@node Debugger +@comment node-name, next, previous, up +@chapter Debugger @cindex Debugger The SBCL debugger (as the CMUCL debugger it was derived from) has very @@ -32,6 +35,7 @@ indistinguishable from interpreted code debugging. * Exiting Commands:: * Information Commands:: * Function Tracing:: +* Single Stepping:: @end menu @node Starting the Debugger @@ -136,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. -@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 @@ -786,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 -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 @@ -826,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 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}, @@ -897,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). - + @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 @@ -915,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. +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 @@ -999,24 +993,24 @@ proceed cases. @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 -@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 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 @@ -1061,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 @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 @@ -1177,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. +@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