X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fdebugger.texinfo;h=15abf7829ea774aac8537f616493591a09ed19cf;hb=c0f9314af1b6f7aa67e6c5db523d6ddef735986c;hp=82a8f27858d78ead5dad2dbcc8ba09a64bf1b7b5;hpb=ef8fd235fa2ca39e444710d1bc275acbc8d3279c;p=sbcl.git diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 82a8f27..15abf78 100644 --- a/doc/manual/debugger.texinfo +++ b/doc/manual/debugger.texinfo @@ -1,33 +1,15 @@ -@node The Debugger +@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 -good support for source-level debugging of compiled code. Although -some other debuggers allow access of variables by name, this seems to -be the first Lisp debugger that: - -@itemize - -@item -Tells you when a variable doesn't have a value because it hasn't been -initialized yet or has already been deallocated, or - -@item -Can display the precise source location corresponding to a code -location in the debugged program. - -@end itemize - -These features allow the debugging of compiled code to be made almost -indistinguishable from interpreted code debugging. - +This chapter documents the debugging facilities of SBCL, including +the debugger, single-stepper and @code{trace}, and the effect of +@code{(optimize debug)} declarations. @menu -* Starting the Debugger:: -* The Debugger Command Loop:: -* Controlling Printing in the Debugger:: +* Debugger Entry:: +* Debugger Command Loop:: * Stack Frames:: * Variable Access:: * Source Location Printing:: @@ -35,111 +17,115 @@ indistinguishable from interpreted code debugging. * Exiting Commands:: * Information Commands:: * Function Tracing:: +* Single Stepping:: +* Enabling and Disabling the Debugger:: @end menu -@node Starting the Debugger +@node Debugger Entry @comment node-name, next, previous, up -@section Starting the Debugger - -The debugger is an interactive command loop that allows a user to examine -the function call stack. The debugger is invoked when: +@section Debugger Entry -@itemize - -@item -A @code{serious-condition} is signaled, and it is not handled, or - -@item -@code{error} is called, and the condition it signals is not handled, -or - -@item -the debugger is explicitly entered with the Lisp @code{break} or -@code{debug} functions. +@menu +* Debugger Banner:: +* Debugger Invocation:: +@end menu -@end itemize +@node Debugger Banner +@comment node-name, next, previous, up +@subsection Debugger Banner -When you enter the TTY debugger, it looks something like this: +When you enter the debugger, it looks something like this: @example debugger invoked on a TYPE-ERROR in thread 11184: The value 3 is not of type LIST. + +You can type HELP for debugger help, or (SB-EXT:QUIT) to exit from SBCL. + restarts (invokable by number or by possibly-abbreviated name): 0: [ABORT ] Reduce debugger level (leaving debugger, returning to toplevel). 1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop. -(CAR 1 3)[:EXTERNAL] +(CAR 1 3) 0] @end example The first group of lines describe what the error was that put us in -the debugger. In this case @code{car} was called on @code{3}. After -@samp{restarts} is a list of all the ways that we can restart -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. +the debugger. In this case @code{car} was called on @code{3}, causing +a @code{type-error}. +This is followed by the ``beginner help line'', which appears only if +@code{sb-ext:*debug-beginner-help-p*} is true (default). -@node The Debugger Command Loop +Next comes a listing of the active restart names, along with their +descriptions -- the ways we can restart execution after this error. In +this case, both options return to top-level. Restarts can be selected +by entering the corresponding number or name. + +The current frame appears right underneath the restarts, immediately +followed by the debugger prompt. + +@node Debugger Invocation @comment node-name, next, previous, up -@section The Debugger Command Loop -@cindex Evaluation, in the debugger - -The debugger is an interactive read-eval-print loop much like the normal -top-level, but some symbols are interpreted as debugger commands instead -of being evaluated. A debugger command starts with the symbol name of -the command, possibly followed by some arguments on the same line. Some -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 -a variable that happens also to be the name of a debugger command, you -can use the @command{list-locals} command or the @code{sb-debug:var} -function, or you can wrap the variable in a @code{progn} to hide it from -the command loop. +@subsection Debugger Invocation -The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is -the number of the current frame. Frames are numbered starting from -zero at the top (most recent call), increasing down to the bottom. -The current frame is the frame that commands refer to. The current -frame also provides the lexical environment for evaluation of -non-command forms. +The debugger is invoked when: - The debugger evaluates forms in the lexical environment of the -functions being debugged. The debugger can only access variables. -You can't @code{go} or @code{return-from} into a function, and you -can't call local functions. Special variable references are evaluated -with their current value (the innermost binding around the debugger -invocation) -- you don't get the value that the special had in the -current frame. For more information on debugger variable access, see -@ref{Variable Access}. +@itemize +@item +@code{error} is called, and the condition it signals is not handled. -@node Controlling Printing in the Debugger -@comment node-name, next, previous, up -@section Controlling Printing in the Debugger +@item +@code{break} is called, or @code{signal} is called with a condition +that matches the current @code{*break-on-signals*}. -In the debugger, it is possible to override the printing behaviour of -the REPL. +@item +the debugger is explicitly entered with the @code{invoke-debugger} +function. -@defvr {Variable} *debug-print-variable-alist* +@end itemize -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. +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. + +@include var-sb-ext-star-invoke-debugger-hook-star.texinfo + +@node Debugger Command Loop +@comment node-name, next, previous, up +@section Debugger Command Loop + +The debugger is an interactive read-eval-print loop much like the +normal top level, but some symbols are interpreted as debugger +commands instead of being evaluated. A debugger command starts with +the symbol name of the command, possibly followed by some arguments on +the same line. Some 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. + +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 a variable that happens also to be the name of a debugger +command you can wrap the variable in a @code{progn} to hide it from +the command loop. -@end defvr +The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is +the number of the current frame. Frames are numbered starting from +zero at the top (most recent call), increasing down to the bottom. +The current frame is the frame that commands refer to. + +It is possible to override the normal printing behaviour in the +debugger by using the @code{sb-ext:*debug-print-variable-alist*}. + +@include var-sb-ext-star-debug-print-variable-alist-star.texinfo @node Stack Frames @comment node-name, next, previous, up @@ -154,25 +140,23 @@ what it is doing. Frames have: @item @dfn{variables} (@pxref{Variable Access}), which are the values being operated -on; +on. @item @dfn{arguments} to the call (which are really just particularly -interesting variables), and +interesting variables). @item -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. +a current source 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. @end itemize - @menu * Stack Motion:: * How Arguments are Printed:: * Function Names:: -* Funny Frames:: * Debug Tail Recursion:: * Unknown Locations and Interrupts:: @end menu @@ -185,25 +169,25 @@ These commands move to a new stack frame and print the name of the function and the values of its arguments in the style of a Lisp function call: -@deffn {Debugger Command} up +@deffn {Debugger Command} @nopkg{up} Move up to the next higher frame. More recent function calls are considered to be higher on the stack. @end deffn -@deffn {Debugger Command} down +@deffn {Debugger Command} @nopkg{down} Move down to the next lower frame. @end deffn -@deffn {Debugger Command} top +@deffn {Debugger Command} @nopkg{top} Move to the highest frame, that is, the frame where the debugger was entered. @end deffn -@deffn {Debugger Command} bottom +@deffn {Debugger Command} @nopkg{bottom} Move to the lowest frame. @end deffn -@deffn {Debugger Command} frame [@var{n}] +@deffn {Debugger Command} @nopkg{frame} [@var{n}] Move to the frame with the specified number. Prompts for the number if not supplied. The frame with number 0 is the frame where the debugger was entered. @@ -289,42 +273,28 @@ 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}. + Note that inline expansion and open-coding affect what frames +are present in the debugger, see @ref{Debugger Policy Control}. +@comment FIXME: link here to section about open coding once it exists. +@c @ref{open-coding} @node Function Names @comment node-name, next, previous, up @subsection Function Names -If a function is defined by @code{defun}, @code{labels}, or -@code{flet}, then the debugger will print the actual function name -after the open parenthesis, like: - -@example -(STRING-UPCASE "test case" :START 0 :END NIL) -((SETF AREF) #\a "for" 1) -@end example - -Otherwise, the function name is a string, and will be printed in -quotes: - -@example -("DEFUN MYFUN" BAR) -("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL) -("SETQ *GC-NOTIFY-BEFORE*") -@end example - -This string name is derived from the @code{def@var{mumble}} form -that encloses or expanded into the lambda, or the outermost enclosing -form if there is no @code{def@var{mumble}}. +If a function is defined by @code{defun} it will appear in backtrace +by that name. Functions defined by @code{labels} and @code{flet} will +appear as @code{(FLET )} and @code{(LABELS )} respectively. +Anonymous lambdas will appear as @code{(LAMDBA )}. +@menu +* Entry Point Details:: +@end menu -@node Funny Frames +@node Entry Point Details @comment node-name, next, previous, up -@subsection Funny Frames +@subsubsection Entry Point Details @cindex External entry points @cindex Entry points, external @cindex Block compilation, debugger implications @@ -332,60 +302,31 @@ form if there is no @code{def@var{mumble}}. @cindex Optional, stack frame kind @cindex Cleanup, stack frame kind -Sometimes the evaluator introduces new functions that are used to +Sometimes the compiler introduces new functions that are used to implement a user function, but are not directly specified in the -source. The main place this is done is for checking argument type and -syntax. Usually these functions do their thing and then go away, and -thus are not seen on the stack in the debugger. But when you get some -sort of error during lambda-list processing, you end up in the -debugger on one of these funny frames. - -These funny frames are flagged by printing -``@code{[@var{keyword}]}'' after the parentheses. For example, -this call: - -@lisp -(car 'a 'b) -@end lisp - -will look like this: - -@example -(CAR 2 A)[:EXTERNAL] -@end example - -And this call: - -@lisp -(string-upcase "test case" :end) -@end lisp - -would look like this: - -@example -("SB!INT:&MORE processing" "test case" 1053984 1)[:OPTIONAL] -@end example - -As you can see, these frames have only a vague resemblance to the -original call. Fortunately, the error message displayed when you -enter the debugger will usually tell you what problem is (in these -cases, too many arguments and odd keyword arguments.) Also, if you go -down the stack to the frame for the calling function, you can display -the original source. @xref{Source Location Printing}. - -@c FIXME: is the block-compilation part correct for SBCL? - -With recursive or block compiled functions, an @code{:EXTERNAL} frame -may appear before the frame representing the first call to the -recursive function or entry to the compiled block. This is a -consequence of the way the compiler does block compilation: there is -nothing odd with your program. You will also see @code{:CLEANUP} -frames during the execution of @code{unwind-protect} cleanup -code. Note that inline expansion and open-coding affect what frames -are present in the debugger, see @ref{Debugger Policy Control}. -@comment FIXME: link here to section about open coding once it exists. -@c @ref{open-coding} - +source. This is mostly done for argument type and count checking. + +@c FIXME: the following bits talked about block-compilation, but +@c we don't currently support it... + +@c With recursive +@c or block compiled +@c functions, an additional @code{:EXTERNAL} frame +@c may appear before the frame representing the first call to the +@c recursive function +@c or entry to the compiled block. +@c This is a +@c consequence of the way the compiler works: there is +@c nothing odd with your program. You will also see @code{:CLEANUP} +@c frames during the execution of @code{unwind-protect} cleanup +@c code. + +With recursive functions, an additional @code{external} frame may +appear before the frame representing the first call to the recursive +function. This is a consequence of the way the compiler works: there +is nothing odd with your program. You may also see @code{cleanup} +frames during the execution of @code{unwind-protect} cleanup code, and +@code{optional} for variable argument entry points. @node Debug Tail Recursion @comment node-name, next, previous, up @@ -393,10 +334,10 @@ are present in the debugger, see @ref{Debugger Policy Control}. @cindex Tail recursion @cindex Recursion, tail -Both the compiler and the interpreter are ``properly tail recursive.'' -If a function call is in a tail-recursive position, the stack frame -will be deallocated @emph{at the time of the call}, rather than after -the call returns. Consider this backtrace: +The compiler is ``properly tail recursive.'' If a function call is in +a tail-recursive position, the stack frame will be deallocated +@emph{at the time of the call}, rather than after the call returns. +Consider this backtrace: @example (BAR ...) @@ -423,8 +364,8 @@ tail-recursively, as in this example: @end lisp Usually the elimination of tail-recursive frames makes debugging more -pleasant, since theses frames are mostly uninformative. If there is -any doubt about how one function called another, it can usually be +pleasant, since these frames are mostly uninformative. If there is any +doubt about how one function called another, it can usually be eliminated by finding the source location in the calling frame. @xref{Source Location Printing}. @@ -436,7 +377,6 @@ optimization quality is greater than @code{2}. @comment FIXME: reinstate this link once the chapter is in the manual. @c For a more thorough discussion of tail recursion, @ref{tail-recursion}. - @node Unknown Locations and Interrupts @comment node-name, next, previous, up @subsection Unknown Locations and Interrupts @@ -515,7 +455,7 @@ X = 1 X#1 = 2 @end example -@deffn {Debugger Command} list-locals [@var{prefix}] +@deffn {Debugger Command} @nopkg{list-locals} [@var{prefix}] This command prints the name and value of all variables in the current frame whose name has the specified @var{prefix}. @var{prefix} may be a string or a symbol. If no @var{prefix} is given, then all available @@ -525,7 +465,7 @@ suffix, where @var{identifier} is the small integer used to make the name unique. @end deffn -@defun sb-debug:var @var{name} &optional @var{identifier} +@defun @sbdebug{var} @var{name} &optional @var{identifier} This function returns the value of the variable in the current frame with the specified @var{name}. If supplied, @var{identifier} determines which value to return when there are ambiguous variables. @@ -658,7 +598,7 @@ One of the debugger's capabilities is source level debugging of compiled code. These commands display the source location for the current frame: -@deffn {Debugger Command} source [@var{context}] +@deffn {Debugger Command} @nopkg{source} [@var{context}] This command displays the file that the current frame's function was defined from (if it was defined from a file), and then the source form responsible for generating the code that the current frame was @@ -775,7 +715,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 @@ -815,7 +755,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}, @@ -886,7 +826,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 @@ -904,6 +844,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. +@item > (max speed space compilation-speed) +If @code{debug} is greater than all of @code{speed}, @code{space} and +@code{compilation-speed} the code will be steppable (@pxref{Single Stepping}). + @end table As you can see, if the @code{speed} quality is @code{3}, debugger performance is @@ -931,34 +875,41 @@ the original function. These commands get you out of the debugger. -@deffn {Debugger Command} toplevel +@deffn {Debugger Command} @nopkg{toplevel} Throw to top level. @end deffn -@deffn {Debugger Command} restart [@var{n}] +@deffn {Debugger Command} @nopkg{restart} [@var{n}] Invokes the @var{n}th restart case as displayed by the @code{error} command. If @var{n} is not specified, the available restart cases are reported. @end deffn -@deffn {Debugger Command} continue +@deffn {Debugger Command} @nopkg{continue} Calls @code{continue} on the condition given to @code{debug}. If there is no restart case named @var{continue}, then an error is signaled. @end deffn -@deffn {Debugger Command} abort +@deffn {Debugger Command} @nopkg{abort} Calls @code{abort} on the condition given to @code{debug}. This is useful for popping debug command loop levels or aborting to top level, as the case may be. @end deffn -@deffn {Debugger Command} return @var{value} +@deffn {Debugger Command} @nopkg{return} @var{value} Returns @var{value} from the current stack frame. This command is available when the @code{debug} optimization quality is greater than both @code{speed} and @code{space}. Care must be taken that the value is of the same type as SBCL expects the stack frame to return. @end deffn +@deffn {Debugger Command} @nopkg{restart-frame} +Restarts execution of the current stack frame. This command is +available when the @code{debug} optimization quality is greater than +both @code{speed} and @code{space} and when the frame is for is a global +function. If the function is redefined in the debugger before the frame +is restarted, the new function will be used. +@end deffn @node Information Commands @comment node-name, next, previous, up @@ -967,45 +918,40 @@ is of the same type as SBCL expects the stack frame to return. Most of these commands print information about the current frame or function, but a few show general information. -@deffn {Debugger Command} help -@deffnx {Debugger Command} ? +@deffn {Debugger Command} @nopkg{help} +@deffnx {Debugger Command} @nopkg{?} Displays a synopsis of debugger commands. @end deffn -@deffn {Debugger Command} describe +@deffn {Debugger Command} @nopkg{describe} Calls @code{describe} on the current function and displays the number of local variables. @end deffn -@deffn {Debugger Command} print +@deffn {Debugger Command} @nopkg{print} Displays the current function call as it would be displayed by moving to this frame. @end deffn -@deffn {Debugger Command} error +@deffn {Debugger Command} @nopkg{error} Prints the condition given to @code{invoke-debugger} and the active 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*}. +@deffn {Debugger Command} @nopkg{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*}. @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. +@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 @@ -1050,12 +996,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 @@ -1166,5 +1106,62 @@ 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. + +The following debugger commands are used for controlling single stepping. + +@deffn {Debugger Command} @nopkg{start} +Selects the @code{continue} restart if one exists and starts single stepping. +None of the other single stepping commands can be used before stepping has +been started either by using @code{start} or by using the standard +@code{step} macro. +@end deffn + +@deffn {Debugger Command} @nopkg{step} +Steps into the current form. Stepping will be resumed when the next +form that has been compiled with stepper instrumentation is evaluated. +@end deffn + +@deffn {Debugger Command} @nopkg{next} +Steps over the current form. Stepping will be disabled until evaluation of +the form is complete. +@end deffn + +@deffn {Debugger Command} @nopkg{out} +Steps out of the current frame. Stepping will be disabled until the +topmost stack frame that had been stepped into returns. +@end deffn + +@deffn {Debugger Command} @nopkg{stop} +Stops the single stepper and resumes normal execution. +@end deffn + +@include macro-common-lisp-step.texinfo + +@node Enabling and Disabling the Debugger +@comment node-name, next, previous, up +@section Enabling and Disabling the Debugger + +@cindex debugger, enabling +@cindex debugger, disabling +@cindex disabling debugger +@cindex ldb, enabling +@cindex ldb, disabling +@cindex disabling ldb + +In certain contexts (e.g., non-interactive applications), it may be +desirable to turn off the SBCL debugger (and possibly re-enable it). +The functions here control the debugger. +@include fun-sb-ext-disable-debugger.texinfo +@include fun-sb-ext-enable-debugger.texinfo