-@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
* 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
@item
the debugger is explicitly entered with the Lisp @code{break} or
-@code{debug} functions.
+@code{invoke-debugger} functions.
@end itemize
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
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
@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.
@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
@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.
* 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
@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
then @samp{#<unavailable-arg>} 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
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
@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
@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
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
* 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
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
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
* 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
@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
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
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
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
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
@end deffn
-@node Information Commands, Function Tracing, Exiting Commands, The Debugger
+@node Information Commands
@comment node-name, next, previous, up
@section Information Commands
@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 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
@c @end example
-@node Function Tracing, , Information Commands, The Debugger
+@node Function Tracing
@comment node-name, next, previous, up
@section Function Tracing
@cindex Tracing
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
projects / sbcl.git / blobdiff