X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fdebugger.texinfo;h=6a9e137786195db32a29b9b6d82c261dd4e694bc;hb=15d6e7c9a2c3234f95dfe278046fa2fee1b0c007;hp=86f6ad295b327af646cf29e0330cf2241f9e6ec6;hpb=01b53542be411ba6ede003da5e7292e16602ab6e;p=sbcl.git diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 86f6ad2..6a9e137 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 @@ -786,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 -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 +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 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 +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). - + @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 +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. +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 @@ -1003,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 -@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 +1068,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 +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. +@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