mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-22 04:30:19 +02:00
Code Activity

update debugger docs

Browse source 
* doc/ref/api-debug.texi (Debug on Error): Update xref.
* doc/ref/scheme-using.texi (REPL Commands): New subsection.
  (Interactive Debugging): Rename from Interactive Debugger, to indicate
  that debugging is just part of the REPL. Update docs.
This commit is contained in:
Andy Wingo 2010-07-16 11:54:19 +02:00
parent 019fdc97d9
commit 3c0b7725ef
2 changed files with 381 additions and 218 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/ref/api-debug.texi
View file

@ -504,7 +504,7 @@ highlighted wherever they appear in the backtrace.
You can also use the @code{(debug)} command to explore the saved stack You can also use the @code{(debug)} command to explore the saved stack
using an interactive command-line-driven debugger. See @ref{Interactive using an interactive command-line-driven debugger. See @ref{Interactive
Debugger} for more information about this. Debugging} for more information about this.
@deffn {Scheme Procedure} debug @deffn {Scheme Procedure} debug
Invoke the Guile debugger to explore the context of the last error. Invoke the Guile debugger to explore the context of the last error.

591
doc/ref/scheme-using.texi
View file

@ -37,8 +37,9 @@ support for languages other than Scheme.
@menu @menu
* Readline:: * Readline::
* Value Historyx:: * Value Historyx::
* REPL Commands::
* Error Handling:: * Error Handling::
* Interactive Debugger:: Using the interactive debugger. * Interactive Debugging::
@end menu @end menu
@ -125,157 +126,365 @@ data structure or closure, they may then be reclaimed by the garbage collector.
@end deffn @end deffn
@node REPL Commands
@subsection REPL Commands
@cindex commands
The REPL exists to read expressions, evaluate them, and then print their
results. But sometimes one wants to tell the REPL to evaluate an
expression in a different way, or to do something else altogether. A
user can affect the way the REPL works with a @dfn{REPL command}.
The previous section had an example of a command, in the form of
@code{,option}.
@lisp
scheme@@(guile-user)> ,option value-history #t
@end lisp
@noindent
Commands are distinguished from expressions by their initial comma
(@samp{,}). Since a comma cannot begin an expression in most languages,
it is an effective indicator to the REPL that the following text forms a
command, not an expression.
REPL commands are convenient because they are always there. Even if the
current module doesn't have a binding for @code{pretty-print}, one can
always @code{,pretty-print}.
The following sections document the various commands, grouped together
by functionality. Many of the commands have abbreviations; see the
online help (@code{,help}) for more information.
@menu
* Help Commands::
* Module Commands::
* Language Commands::
* Compile Commands::
* Profile Commands::
* Debug Commands::
* Inspect Commands::
* System Commands::
@end menu
@node Help Commands
@subsubsection Help Commands
When Guile starts interactively, it notifies the user that help can be
had by typing @samp{,help}. Indeed, @code{help} is a command, and a
particularly useful one, as it allows the user to discover the rest of
the commands.
@deffn {REPL Command} help [@samp{all} | group | @samp{[-c]} command]
Show help.
With one argument, tries to look up the argument as a group name, giving
help on that group if successful. Otherwise tries to look up the
argument as a command, giving help on the command.
If there is a command whose name is also a group name, use the @samp{-c
@var{command}} form to give help on the command instead of the group.
Without any argument, a list of help commands and command groups
are displayed.
@end deffn
@deffn {REPL Command} show [topic]
Gives information about Guile.
With one argument, tries to show a particular piece of information;
currently supported topics are `warranty' (or `w'), `copying' (or `c'),
and `version' (or `v').
Without any argument, a list of topics is displayed.
@end deffn
@deffn {REPL Command} apropos regexp
Find bindings/modules/packages.
@end deffn
@deffn {REPL Command} describe obj
Show description/documentation.
@end deffn
@node Module Commands
@subsubsection Module Commands
@deffn {REPL Command} module [module]
Change modules / Show current module.
@end deffn
@deffn {REPL Command} import [module ...]
Import modules / List those imported.
@end deffn
@deffn {REPL Command} load file
Load a file in the current module.
@end deffn
@deffn {REPL Command} binding
List current bindings.
@end deffn
@node Language Commands
@subsubsection Language Commands
@deffn {REPL Command} language language
Change languages.
@end deffn
@node Compile Commands
@subsubsection Compile Commands
@deffn {REPL Command} compile exp
Generate compiled code.
@end deffn
@deffn {REPL Command} compile-file file
Compile a file.
@end deffn
@deffn {REPL Command} disassemble exp
Disassemble a compiled procedure.
@end deffn
@deffn {REPL Command} disassemble-file file
Disassemble a file.
@end deffn
@node Profile Commands
@subsubsection Profile Commands
@deffn {REPL Command} time exp
Time execution.
@end deffn
@deffn {REPL Command} profile exp
Profile execution.
@end deffn
@deffn {REPL Command} trace exp
Trace execution.
@end deffn
@node Debug Commands
@subsubsection Debug Commands
These debugging commands are only available within a recursive REPL;
they do not work at the top level.
@deffn {REPL Command} backtrace [count] [#:width w] [#:full? f]
Print a backtrace.
Print a backtrace of all stack frames, or innermost @var{COUNT} frames.
If @var{count} is negative, the last @var{count} frames will be shown.
@end deffn
@deffn {REPL Command} up [count]
Select a calling stack frame.
Select and print stack frames that called this one.
An argument says how many frames up to go.
@end deffn
@deffn {REPL Command} down [count]
Select a called stack frame.
Select and print stack frames called by this one.
An argument says how many frames down to go.
@end deffn
@deffn {REPL Command} frame [idx]
Show a frame.
Show the selected frame. With an argument, select a frame by index,
then show it.
@end deffn
@deffn {REPL Command} procedure
Print the procedure for the selected frame.
@end deffn
@deffn {REPL Command} locals
Show local variables.
Show locally-bound variables in the selected frame.
@end deffn
@c FIXME: whenever we regain support for stepping, here are the docs..
@c The commands in this subsection all apply only when the stack is
@c @dfn{continuable} --- in other words when it makes sense for the program
@c that the stack comes from to continue running. Usually this means that
@c the program stopped because of a trap or a breakpoint.
@c @deffn {Debugger Command} step [n]
@c Tell the debugged program to do @var{n} more steps from its current
@c position. One @dfn{step} means executing until the next frame entry or
@c exit of any kind. @var{n} defaults to 1.
@c @end deffn
@c @deffn {Debugger Command} next [n]
@c Tell the debugged program to do @var{n} more steps from its current
@c position, but only counting frame entries and exits where the
@c corresponding source code comes from the same file as the current stack
@c frame. (See @ref{Step Traps} for the details of how this works.) If
@c the current stack frame has no source code, the effect of this command
@c is the same as of @code{step}. @var{n} defaults to 1.
@c @end deffn
@c @deffn {Debugger Command} finish
@c Tell the program being debugged to continue running until the completion
@c of the current stack frame, and at that time to print the result and
@c reenter the command line debugger.
@c @end deffn
@c @deffn {Debugger Command} continue
@c Tell the program being debugged to continue running. (In fact this is
@c the same as the @code{quit} command, because it exits the debugger
@c command loop and so allows whatever code it was that invoked the
@c debugger to continue.)
@c @end deffn
@c The @code{evaluate} command is most useful for querying the value of a
@c variable, either global or local, in the environment of the selected
@c stack frame, but it can be used more generally to evaluate any
@c expression.
@c @deffn {Debugger Command} evaluate expression
@c Evaluate an expression in the environment of the selected stack frame.
@c The expression must appear on the same line as the command, however it
@c may be continued over multiple lines.
@c @end deffn
@node Inspect Commands
@subsubsection Inspect Commands
@deffn {REPL Command} inspect EXP
Inspect the result(s) of evaluating @var{exp}.
@end deffn
@deffn {REPL Command} pretty-print EXP
Pretty-print the result(s) of evaluating @var{exp}.
@end deffn
@node System Commands
@subsubsection System Commands
@deffn {REPL Command} gc
Garbage collection.
@end deffn
@deffn {REPL Command} statistics
Display statistics.
@end deffn
@deffn {REPL Command} option [key value]
List/show/set options.
@end deffn
@deffn {REPL Command} quit
Quit this session.
@end deffn
@node Error Handling @node Error Handling
@subsection Error Handling @subsection Error Handling
When code being evaluated from the REPL hits an error, Guile remembers When code being evaluated from the REPL hits an error, Guile enters a
the execution context where the error occurred and can give you three new prompt, allowing you to inspect the context of the error.
levels of information about what the error was and exactly where it
occurred.
By default, Guile displays only the first level, which is the most
immediate information about where and why the error occurred, for
example:
@lisp @lisp
(make-string (* 4 (+ 3 #\s)) #\space) scheme@@(guile-user)> (map string-append '("a" "b") '("c" #\d))
@print{} ERROR: In procedure string-append:
standard input:2:19: In procedure + in expression (+ 3 #\s): ERROR: Wrong type (expecting string): #\d
standard input:2:19: Wrong type argument: #\s Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
ABORT: (wrong-type-arg) scheme@@(guile-user) [1]>
Type "(backtrace)" to get more information
or "(debug)" to enter the debugger.
@end lisp @end lisp
@noindent The new prompt runs inside the old one, in the dynamic context of the
However, as the message above says, you can obtain more information error. It is a recursive REPL, augmented with a reified representation
about the context of the error by typing @code{(backtrace)} or of the stack, ready for debugging.
@code{(debug)}.
@code{(backtrace)} displays the Scheme call stack at the point where the @code{,backtrace} (abbreviated @code{,bt}) displays the Scheme call
error occurred: stack at the point where the error occurred:
@lisp @lisp
(backtrace) scheme@@(guile-user) [1]> ,bt
@print{} 1 (map #<procedure string-append _> ("a" "b") ("c" #\d))
Backtrace: 0 (string-append "b" #\d)
In standard input:
2: 0* [make-string ...
2: 1* [* 4 ...
2: 2* [+ 3 #\s]
Type "(debug-enable 'backtrace)" if you would like a backtrace
automatically if an error occurs in the future.
@end lisp @end lisp
@noindent In the above example, the backtrace doesn't have much source
In a more complex scenario than this one, this can be extremely useful information, as @code{map} and @code{string-append} are both
for understanding where and why the error occurred. You can make Guile primitives. But in the general case, the space on the left of the
show the backtrace automatically by adding @code{(debug-enable backtrace indicates the line and column in which a given procedure calls
'backtrace)} to your @file{.guile}. another.
@code{(debug)} takes you into Guile's interactive debugger, which You can exit a recursive REPL in the same way that you exit any REPL:
provides commands that allow you to via @samp{(quit)}, @samp{,quit} (abbreviated @samp{,q}), or
@kbd{C-d}, among other options.
@node Interactive Debugging
@subsection Interactive Debugging
A recursive debugging REPL exposes a number of other meta-commands that
inspect the state of the computation at the time of the error. These
commands allow you to
@itemize @bullet @itemize @bullet
@item @item
display the Scheme call stack at the point where the error occurred display the Scheme call stack at the point where the error occurred;
(the @code{backtrace} command --- see @ref{Display Backtrace})
@item @item
move up and down the call stack, to see in detail the expression being move up and down the call stack, to see in detail the expression being
evaluated, or the procedure being applied, in each @dfn{frame} (the evaluated, or the procedure being applied, in each @dfn{frame}; and
@code{up}, @code{down}, @code{frame}, @code{position}, @code{info args}
and @code{info frame} commands --- see @ref{Frame Selection} and
@ref{Frame Information})
@item @item
examine the values of variables and expressions in the context of each examine the values of variables and expressions in the context of each
frame (the @code{evaluate} command --- see @ref{Frame Evaluation}). frame.
@end itemize @end itemize
@noindent @noindent
The interactive debugger is documented further in the following section. @xref{Debug Commands}, for documentation of the individual
commands. This section aims to give more of a walkthrough of a typical
debugging session.
First, we're going to need a good error. Let's try to macroexpand the
@node Interactive Debugger expression @code{(unquote foo)}, outside of a @code{quasiquote} form,
@subsection Using the Interactive Debugger and see how the macroexpander reports this error.
Guile's interactive debugger is a command line application that
accepts commands from you for examining the stack and, if stopped at a
trap, for continuing program execution in various ways. Unlike in the
normal Guile REPL, commands are typed mostly without parentheses.
When you first enter the debugger, it introduces itself with a message
like this:
@lisp @lisp
This is the Guile debugger -- for help, type `help'. scheme@@(guile-user)> (macroexpand '(unquote foo))
There are 3 frames on the stack. ERROR: In procedure macroexpand:
ERROR: unquote: expression not valid outside of quasiquote in (unquote foo)
Frame 2 at standard input:36:19 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
[+ 3 #\s] scheme@@(guile-user) [1]>
debug>
@end lisp @end lisp
@noindent The @code{backtrace} command, which can also be invoked as @code{bt},
``debug>'' is the debugger's prompt, and a reminder that you are not in displays the call stack (aka backtrace) at the point where the debugger
the normal Guile REPL. In case you find yourself in the debugger by was entered:
mistake, the @code{quit} command will return you to the REPL.
@deffn {Debugger Command} quit
Exit the debugger.
@end deffn
The other available commands are described in the following subsections.
@menu
* Display Backtrace:: backtrace.
* Frame Selection:: up, down, frame.
* Frame Information:: info args, info frame, position.
* Frame Evaluation:: evaluate.
* Stepping and Continuing:: step, next, (trace-)finish, continue.
@end menu
@node Display Backtrace
@subsubsection Display Backtrace
The @code{backtrace} command, which can also be invoked as @code{bt} or
@code{where}, displays the call stack (aka backtrace) at the point where
the debugger was entered:
@lisp @lisp
debug> bt scheme@@(guile-user) [1]> ,bt
In standard input: In ice-9/psyntax.scm:
36: 0* [make-string ... 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
36: 1* [* 4 ... 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
36: 2* [+ 3 #\s] 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
In unknown file:
0 (scm-error syntax-error macroexpand "~a: ~a in ~a" # #f)
@end lisp @end lisp
@deffn {Debugger Command} backtrace [count]
@deffnx {Debugger Command} bt [count]
@deffnx {Debugger Command} where [count]
Print backtrace of all stack frames, or of the innermost @var{count}
frames. With a negative argument, print the outermost -@var{count}
frames. If the number of frames isn't explicitly given, the debug
option @code{depth} determines the maximum number of frames printed.
@end deffn
The format of the displayed backtrace is the same as for the
@code{display-backtrace} procedure (@pxref{Examining the Stack}).
@node Frame Selection
@subsubsection Frame Selection
A call stack consists of a sequence of stack @dfn{frames}, with each A call stack consists of a sequence of stack @dfn{frames}, with each
frame describing one level of the nested evaluations and applications frame describing one procedure which is waiting to do something with the
that the program was executing when it hit a breakpoint or an error. values returned by another. Here we see that there are four frames on
Frames are numbered such that frame 0 is the outermost --- i.e. the the stack.
operation on the call stack that began least recently --- and frame N-1
the innermost (where N is the total number of frames on the stack). Note that @code{macroexpand} is not on the stack -- it must have made a
tail call to @code{chi-top}, as indeed we would find if we searched
@code{ice-9/psyntax.scm} for its definition.
When you enter the debugger, the innermost frame is selected, which When you enter the debugger, the innermost frame is selected, which
means that the commands for getting information about the ``current'' means that the commands for getting information about the ``current''
@ -286,113 +495,67 @@ instead, use the @code{up}, @code{down} and @code{frame} commands like
this: this:
@lisp @lisp
debug> up scheme@@(guile-user) [1]> ,up
Frame 1 at standard input:36:14 In ice-9/psyntax.scm:
[* 4 ... 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
debug> frame 0 scheme@@(guile-user) [1]> ,frame 3
Frame 0 at standard input:36:1 In ice-9/psyntax.scm:
[make-string ... 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
debug> down scheme@@(guile-user) [1]> ,down
Frame 1 at standard input:36:14 In ice-9/psyntax.scm:
[* 4 ... 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
@end lisp @end lisp
@deffn {Debugger Command} up [n] Perhaps we're interested in what's going on in frame 2, so we take a
Move @var{n} frames up the stack. For positive @var{n}, this look at its local variables:
advances toward the outermost frame, to lower frame numbers, to
frames that have existed longer. @var{n} defaults to one.
@end deffn
@deffn {Debugger Command} down [n] @lisp
Move @var{n} frames down the stack. For positive @var{n}, this scheme@@(guile-user) [1]> ,locals
advances toward the innermost frame, to higher frame numbers, to frames Local variables:
that were created more recently. @var{n} defaults to one. $1 = e = (unquote foo)
@end deffn $2 = r = ()
$3 = w = ((top))
$4 = s = #f
$5 = rib = #f
$6 = mod = (hygiene guile-user)
$7 = for-car? = #f
$8 = first = unquote
$9 = ftype = macro
$10 = fval = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
$11 = fe = unquote
$12 = fw = ((top))
$13 = fs = #f
$14 = fmod = (hygiene guile-user)
@end lisp
@deffn {Debugger Command} frame [n] All of the values are accessible by their value-history names
Select and print a stack frame. With no argument, print the selected (@code{$@var{n}}):
stack frame. (See also ``info frame''.) An argument specifies the
frame to select; it must be a stack-frame number.
@end deffn
@lisp
scheme@@(guile-user) [1]> $10
$15 = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
@end lisp
@node Frame Information We can even invoke the procedure at the REPL directly:
@subsubsection Frame Information
The following commands return detailed information about the currently @lisp
selected frame. scheme@@(guile-user) [1]> ($10 'not-going-to-work)
ERROR: In procedure macroexpand:
ERROR: source expression failed to match any pattern in not-going-to-work
Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
@end lisp
@deffn {Debugger Command} {info frame} Well at this point we've caused an error within an error. Let's just
Display a verbose description of the selected frame. The information quit back to the top level:
that this command provides is equivalent to what can be deduced from the
one line summary for the frame that appears in a backtrace, but is
presented and explained more clearly.
@end deffn
@deffn {Debugger Command} {info args} @lisp
Display the argument variables of the current stack frame. Arguments scheme@@(guile-user) [2]> ,q
can also be seen in the backtrace, but are presented more clearly by scheme@@(guile-user) [1]> ,q
this command. scheme@@(guile-user)>
@end deffn @end lisp
@deffn {Debugger Command} position Finally, as a word to the wise: hackers close their REPL prompts with
Display the name of the source file that the current expression comes @kbd{C-d}.
from, and the line and column number of the expression's opening
parenthesis within that file. This information is only available when
the @code{positions} read option is enabled (@pxref{Reader options}).
@end deffn
@node Frame Evaluation
@subsubsection Frame Evaluation
The @code{evaluate} command is most useful for querying the value of a
variable, either global or local, in the environment of the selected
stack frame, but it can be used more generally to evaluate any
expression.
@deffn {Debugger Command} evaluate expression
Evaluate an expression in the environment of the selected stack frame.
The expression must appear on the same line as the command, however it
may be continued over multiple lines.
@end deffn
@node Stepping and Continuing
@subsubsection Single Stepping and Continuing Execution
The commands in this subsection all apply only when the stack is
@dfn{continuable} --- in other words when it makes sense for the program
that the stack comes from to continue running. Usually this means that
the program stopped because of a trap or a breakpoint.
@deffn {Debugger Command} step [n]
Tell the debugged program to do @var{n} more steps from its current
position. One @dfn{step} means executing until the next frame entry or
exit of any kind. @var{n} defaults to 1.
@end deffn
@deffn {Debugger Command} next [n]
Tell the debugged program to do @var{n} more steps from its current
position, but only counting frame entries and exits where the
corresponding source code comes from the same file as the current stack
frame. (See @ref{Step Traps} for the details of how this works.) If
the current stack frame has no source code, the effect of this command
is the same as of @code{step}. @var{n} defaults to 1.
@end deffn
@deffn {Debugger Command} finish
Tell the program being debugged to continue running until the completion
of the current stack frame, and at that time to print the result and
reenter the command line debugger.
@end deffn
@deffn {Debugger Command} continue
Tell the program being debugged to continue running. (In fact this is
the same as the @code{quit} command, because it exits the debugger
command loop and so allows whatever code it was that invoked the
debugger to continue.)
@end deffn
@node Using Guile in Emacs @node Using Guile in Emacs