X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fdebugger.texinfo;h=15abf7829ea774aac8537f616493591a09ed19cf;hb=1ee20a4186d01454f5cf61a3049160c174568305;hp=6a9e137786195db32a29b9b6d82c261dd4e694bc;hpb=3c5609fe910bae51ff885c8cfd4be879151e7489;p=sbcl.git diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 6a9e137..15abf78 100644 --- a/doc/manual/debugger.texinfo +++ b/doc/manual/debugger.texinfo @@ -3,31 +3,13 @@ @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:: @@ -36,125 +18,114 @@ indistinguishable from interpreted code debugging. * 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{invoke-debugger} 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). + +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 +@subsection Debugger Invocation + +The debugger is invoked when: + +@itemize + +@item +@code{error} is called, and the condition it signals is not handled. + +@item +@code{break} is called, or @code{signal} is called with a condition +that matches the current @code{*break-on-signals*}. + +@item +the debugger is explicitly entered with the @code{invoke-debugger} +function. + +@end itemize 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. +@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 The Debugger Command Loop +@node Debugger Command Loop @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 +@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. 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 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}. +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*}. -@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} 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 @@ -169,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 @@ -200,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. @@ -304,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 @@ -347,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 @@ -408,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 ...) @@ -438,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}. @@ -451,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 @@ -530,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 @@ -540,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. @@ -673,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 @@ -919,9 +844,9 @@ 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. +@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 @@ -950,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 @@ -986,34 +918,30 @@ 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*}. -@end deffn - -@deffn {Debugger Command} step -Selects the @code{continue} restart if one exists and starts single stepping. -@xref{Single Stepping}. +@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 @c The new instrumentation based single stepper doesn't support @@ -1189,23 +1117,51 @@ 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. +The following debugger commands are used for controlling single stepping. -@table @strong +@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 -@item Unsteppable -Single stepping is not possible. +@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 -@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. +@deffn {Debugger Command} @nopkg{next} +Steps over the current form. Stepping will be disabled until evaluation of +the form is complete. +@end deffn -@item Fully steppable -Single stepping is possible at individual function call argument -granularity, nested calls can be stepped into, and intermediate values -are available. +@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 -@end table +@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