X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;ds=inline;f=doc%2Fmanual%2Fdebugger.texinfo;h=3e639d4570019b27e8b31464a4dd874ee4f08dea;hb=8a8a8922802460741d6f8f6c11d71b1f414cf3a7;hp=3713a9af5c3a882fdd49e199c3ed644f971425e2;hpb=78867137cd2b9e689fd07640d60e4cf3942bf719;p=sbcl.git diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 3713a9a..3e639d4 100644 --- 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 -@chapter The Debugger +@chapter Debugger @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:: +* Single Stepping:: @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 @@ -55,7 +56,7 @@ or @item the debugger is explicitly entered with the Lisp @code{break} or -@code{debug} functions. +@code{invoke-debugger} functions. @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. +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 @@ -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}. +@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 @@ -117,14 +133,14 @@ current frame. For more information on debugger variable access, see @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. -@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. @@ -140,7 +156,7 @@ initially. @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 @@ -152,15 +168,15 @@ what it is doing. Frames have: @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 -@dfn{Arguments} to the call (which are really just particularly +@dfn{arguments} to the call (which are really just particularly 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. @@ -176,7 +192,7 @@ another function, or because of an interrupt or error. * 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 @@ -209,7 +225,7 @@ was entered. @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 @@ -288,12 +304,13 @@ unavailable or not known to be available (@pxref{Variable Access}), then @samp{#} 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}. -@node Function Names, Funny Frames, How Arguments are Printed, Stack Frames +@node 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}}. -@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 @@ -385,7 +402,7 @@ are present in the debugger, see @ref{Debugger Policy Control}. @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 @@ -435,7 +452,7 @@ optimization quality is greater than @code{2}. @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 @@ -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. -@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 @@ -545,7 +562,7 @@ that must unambiguously complete to the name of a valid variable. * 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 @@ -628,7 +645,7 @@ values to be available, and even then, values are only available at 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 @@ -647,7 +664,7 @@ proved the variable could never take on. This may result in bad 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 @@ -726,7 +743,7 @@ print: * 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 @@ -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. -@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 @@ -835,7 +852,7 @@ next conditional (but watch out because the compiler may have changed the 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 @@ -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). - + @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. +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 @@ -923,7 +944,7 @@ but the call is to an optimized local version of the function, not to 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 @@ -958,7 +979,7 @@ is of the same type as SBCL expects the stack frame to return. @end deffn -@node Information Commands, Function Tracing, Exiting Commands, The Debugger +@node 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 -@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 @@ -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 @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 @@ -1137,7 +1151,7 @@ Displays all the frames from the current to the bottom. Only shows @c @end example -@node Function Tracing, , Information Commands, The Debugger +@node Function 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. -@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. +@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