X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fdebugger.texinfo;h=d1e0c9c851cb30cddb9cee19558082ae278798e9;hb=b0b221088b889b6d3ae67e551b93fe1a6cfec878;hp=7e923ed559d9aedefb05000991f2f8938fbe1aac;hpb=bea5b384106a6734a4b280a76e8ebdd4d51b5323;p=sbcl.git diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 7e923ed..d1e0c9c 100644 --- a/doc/manual/debugger.texinfo +++ b/doc/manual/debugger.texinfo @@ -18,6 +18,7 @@ the debugger, single-stepper and @code{trace}, and the effect of * Information Commands:: * Function Tracing:: * Single Stepping:: +* Enabling and Disabling the Debugger:: @end menu @node Debugger Entry @@ -26,7 +27,7 @@ the debugger, single-stepper and @code{trace}, and the effect of @menu * Debugger Banner:: -* Debugger Invokation:: +* Debugger Invocation:: @end menu @node Debugger Banner @@ -53,7 +54,7 @@ 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:*debugger-beginner-help*} is true (default). +@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 @@ -63,9 +64,9 @@ by entering the corresponding number or name. The current frame appears right underneath the restarts, immediately followed by the debugger prompt. -@node Debugger Invokation +@node Debugger Invocation @comment node-name, next, previous, up -@subsection Debugger Invokation +@subsection Debugger Invocation The debugger is invoked when: @@ -168,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. @@ -332,7 +333,7 @@ function. This is a consequence of the way the compiler works: there is nothing odd with your program. You will also see @code{:CLEANUP} frames during the execution of @code{unwind-protect} cleanup code. The @code{:EXTERNAL} and @code{:CLEANUP} above are entry-point types, -visible only if @code{sb-debug:*show-entry-point-details*} os true. +visible only if @code{sb-debug:*show-entry-point-details*} is true. @node Debug Tail Recursion @comment node-name, next, previous, up @@ -370,8 +371,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}. @@ -461,7 +462,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 @@ -471,7 +472,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. @@ -604,7 +605,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 @@ -850,9 +851,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 @@ -881,34 +882,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 @@ -917,37 +925,32 @@ 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}] +@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 -@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). @@ -1121,23 +1124,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