mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-06-15 08:10:17 +02:00
* scheme-debugging.texi (Debug Last Error, Interactive Debugger):
Moved/merged to scheme-using.texi, as REPL features. (Examples): New. (Intro to Breakpoints): New introductory text here. Removed all subnodes except for Breakpoints Overview. * scheme-using.texi: New. * guile.texi (Programming in Scheme): Include new scheme-using.texi file. * Makefile.am (guile_TEXINFOS): Include new scheme-using.texi file.
This commit is contained in:
Neil Jerram
parent
b49123789f
commit
46f7666d7f
5 changed files with 608 additions and 709 deletions
|
|
@ -28,135 +28,196 @@ execution context at a breakpoint, or when the last error occurred.
|
|||
The details are more complex and more powerful @dots{}
|
||||
|
||||
@menu
|
||||
* Debug Last Error:: Debugging the most recent error.
|
||||
* Examples::
|
||||
* Intro to Breakpoints:: Setting and manipulating them.
|
||||
* Interactive Debugger:: Using the interactive debugger.
|
||||
* Tracing:: Tracing program execution.
|
||||
@end menu
|
||||
|
||||
|
||||
@node Debug Last Error
|
||||
@subsection Debugging the Most Recent Error
|
||||
@node Examples
|
||||
@subsection Examples
|
||||
|
||||
When an error is signalled, Guile remembers the execution context where
|
||||
the error occurred. By default, Guile then displays only the most
|
||||
immediate information about where and why the error occurred, for
|
||||
example:
|
||||
|
||||
@lisp
|
||||
(make-string (* 4 (+ 3 #\s)) #\space)
|
||||
@print{}
|
||||
standard input:2:19: In procedure + in expression (+ 3 #\s):
|
||||
standard input:2:19: Wrong type argument: #\s
|
||||
ABORT: (wrong-type-arg)
|
||||
|
||||
Type "(backtrace)" to get more information or "(debug)" to enter the debugger.
|
||||
@end lisp
|
||||
|
||||
@noindent
|
||||
However, as the message above says, you can obtain much more
|
||||
information about the context of the error by typing
|
||||
@code{(backtrace)} or @code{(debug)}.
|
||||
|
||||
@code{(backtrace)} displays the Scheme call stack at the point where the
|
||||
error occurred:
|
||||
|
||||
@lisp
|
||||
(backtrace)
|
||||
@print{}
|
||||
Backtrace:
|
||||
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
|
||||
|
||||
@noindent
|
||||
In a more complex scenario than this one, this can be extremely useful
|
||||
for understanding where and why the error occurred. For more on the
|
||||
format of the displayed backtrace, see the subsection below.
|
||||
|
||||
@code{(debug)} takes you into Guile's interactive debugger, which
|
||||
provides commands that allow you to
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
display the Scheme call stack at the point where the error occurred
|
||||
(the @code{backtrace} command --- see @ref{Display Backtrace})
|
||||
|
||||
@item
|
||||
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
|
||||
@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
|
||||
examine the values of variables and expressions in the context of each
|
||||
frame (the @code{evaluate} command --- see @ref{Frame Evaluation}).
|
||||
@end itemize
|
||||
|
||||
Use of the interactive debugger, including these commands, is described
|
||||
in @ref{Interactive Debugger}.
|
||||
Before we dive into the details and reference documentation of
|
||||
guile-debugging's features, this chapter sets the scene by presenting a
|
||||
few examples of what you can do with guile-debugging.
|
||||
|
||||
@menu
|
||||
* Backtrace Format:: How to interpret a backtrace.
|
||||
* Single Stepping through a Procedure's Code::
|
||||
* Profiling or Tracing a Procedure's Code::
|
||||
@end menu
|
||||
|
||||
|
||||
@node Backtrace Format
|
||||
@subsubsection How to Interpret a Backtrace
|
||||
@node Single Stepping through a Procedure's Code
|
||||
@subsubsection Single Stepping through a Procedure's Code
|
||||
|
||||
A good way to explore in detail what a Scheme procedure does is to set a
|
||||
breakpoint on it and then single step through what it does. To do this,
|
||||
use the @code{break-in} procedure from the @code{(ice-9 debugging
|
||||
breakpoints)} module with the @code{debug-trap} behaviour from
|
||||
@code{(ice-9 debugging ice-9-debugger-extensions)}. The following
|
||||
sample session illustrates this. It assumes that the file
|
||||
@file{matrix.scm} defines a procedure @code{mkmatrix}, which is the one
|
||||
we want to explore, and another procedure @code{do-main} which calls
|
||||
@code{mkmatrix}.
|
||||
|
||||
@lisp
|
||||
$ /usr/bin/guile -q
|
||||
guile> (use-modules (ice-9 debugger)
|
||||
(ice-9 debugging ice-9-debugger-extensions)
|
||||
(ice-9 debugging breakpoints))
|
||||
guile> (load "matrix.scm")
|
||||
guile> (break-in 'mkmatrix #:behaviour debug-trap)
|
||||
#<<break-in> 808cb70>
|
||||
guile> (do-main 4)
|
||||
This is the Guile debugger -- for help, type `help'.
|
||||
There are 3 frames on the stack.
|
||||
|
||||
Frame 2 at matrix.scm:8:3
|
||||
[mkmatrix]
|
||||
debug> next
|
||||
Frame 3 at matrix.scm:4:3
|
||||
(let ((x 1)) (quote this-is-a-matric))
|
||||
debug> info frame
|
||||
Stack frame: 3
|
||||
This frame is an evaluation.
|
||||
The expression being evaluated is:
|
||||
matrix.scm:4:3:
|
||||
(let ((x 1)) (quote this-is-a-matric))
|
||||
debug> next
|
||||
Frame 3 at matrix.scm:5:21
|
||||
(quote this-is-a-matric)
|
||||
debug> bt
|
||||
In unknown file:
|
||||
?: 0* [primitive-eval (do-main 4)]
|
||||
In standard input:
|
||||
4: 1* [do-main 4]
|
||||
In matrix.scm:
|
||||
8: 2 [mkmatrix]
|
||||
...
|
||||
5: 3 (quote this-is-a-matric)
|
||||
debug> quit
|
||||
this-is-a-matric
|
||||
guile>
|
||||
@end lisp
|
||||
|
||||
Or you can use guile-debugging's Emacs interface (GDS), by using the
|
||||
module @code{(ice-9 gds-client)} instead of @code{(ice-9 debugger)} and
|
||||
@code{(ice-9 debugging ice-9-debugger-extensions)}, and changing
|
||||
@code{debug-trap} to @code{gds-debug-trap}. Then the stack and
|
||||
corresponding source locations are displayed in Emacs instead of on the
|
||||
Guile command line.
|
||||
|
||||
|
||||
@node Profiling or Tracing a Procedure's Code
|
||||
@subsubsection Profiling or Tracing a Procedure's Code
|
||||
|
||||
What if you wanted to get a trace of everything that the Guile evaluator
|
||||
does within a given procedure, but without Guile stopping and waiting
|
||||
for your input at every step? In this case you set a breakpoint on the
|
||||
procedure using @code{break-in} (the same as in the previous example),
|
||||
but use the @code{trace-trap} and @code{trace-until-exit} behaviours
|
||||
provided by the @code{(ice-9 debugging trace)} module.
|
||||
|
||||
@lisp
|
||||
guile> (use-modules (ice-9 debugging breakpoints) (ice-9 debugging trace))
|
||||
guile> (load "matrix.scm")
|
||||
guile> (break-in 'mkmatrix #:behaviour (list trace-trap trace-until-exit))
|
||||
#<<break-in> 808b430>
|
||||
guile> (do-main 4)
|
||||
| 2: [mkmatrix]
|
||||
| 3: [define (define yy 23) ((()) #<eval-closure 4028db30>)]
|
||||
| 3: [define (define yy 23) ((()) #<eval-closure 4028db30>)]
|
||||
| 3: =>(#@@define yy 23)
|
||||
| 3: [let (let # #) (# #)]
|
||||
| 3: [let (let # #) (# #)]
|
||||
| 3: =>(#@@let* (x 1) #@@let (quote this-is-a-matric))
|
||||
| 2: (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric)))
|
||||
| 3: [let (let # #) (# # #)]
|
||||
| 3: [let (let # #) (# # #)]
|
||||
| 3: =>(#@@let* (x 1) #@@let (quote this-is-a-matric))
|
||||
| 2: (let ((x 1)) (quote this-is-a-matric))
|
||||
| 3: [quote (quote this-is-a-matric) ((x . 1) ((yy) 23) (()) ...)]
|
||||
| 3: [quote (quote this-is-a-matric) ((x . 1) ((yy) 23) (()) ...)]
|
||||
| 3: =>(#@@quote this-is-a-matric)
|
||||
| 2: (quote this-is-a-matric)
|
||||
| 2: =>this-is-a-matric
|
||||
this-is-a-matric
|
||||
guile> (do-main 4)
|
||||
| 2: [mkmatrix]
|
||||
| 2: (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric)))
|
||||
| 2: (let ((x 1)) (quote this-is-a-matric))
|
||||
| 2: (quote this-is-a-matric)
|
||||
| 2: =>this-is-a-matric
|
||||
this-is-a-matric
|
||||
guile>
|
||||
@end lisp
|
||||
|
||||
This example shows the default configuration for how each line of trace
|
||||
output is formatted, which is:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
the character @code{|}, a visual clue that the line is a line of trace
|
||||
output, followed by
|
||||
|
||||
@item
|
||||
a number indicating the real evaluator stack depth (where ``real'' means
|
||||
not counting tail-calls), followed by
|
||||
|
||||
@item
|
||||
a summary of the expression being evaluated (@code{(@dots{})}), the
|
||||
procedure being called (@code{[@dots{}]}), or the value being returned
|
||||
from an evaluation or procedure call (@code{=>@dots{}}).
|
||||
@end itemize
|
||||
|
||||
@noindent
|
||||
You can customize @code{(ice-9 debugging trace)} to show different
|
||||
information in each trace line using the @code{set-trace-layout}
|
||||
procedure. The next example shows how to get the source location in
|
||||
each trace line instead of the stack depth.
|
||||
|
||||
@lisp
|
||||
guile> (set-trace-layout "|~16@@a: ~a\n" trace/source trace/info)
|
||||
guile> (do-main 4)
|
||||
| matrix.scm:7:2: [mkmatrix]
|
||||
| : (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric)))
|
||||
| matrix.scm:3:2: (let ((x 1)) (quote this-is-a-matric))
|
||||
| matrix.scm:4:20: (quote this-is-a-matric)
|
||||
| matrix.scm:4:20: =>this-is-a-matric
|
||||
this-is-a-matric
|
||||
guile>
|
||||
@end lisp
|
||||
|
||||
(For anyone wondering why the first @code{(do-main 4)} call above
|
||||
generates lots more trace lines than the subsequent calls: these
|
||||
examples also demonstrate how the Guile evaluator ``memoizes'' code.
|
||||
When Guile evaluates a source code expression for the first time, it
|
||||
changes some parts of the expression so that they will be quicker to
|
||||
evaluate when that expression is evaluated again; this is called
|
||||
memoization. The trace output from the first @code{(do-main 4)} call
|
||||
shows memoization steps, such as an internal define being transformed to
|
||||
a letrec.)
|
||||
|
||||
|
||||
@node Intro to Breakpoints
|
||||
@subsection Intro to Breakpoints
|
||||
|
||||
If you are not already familiar with the concept of breakpoints, the
|
||||
first subsection below explains how they work are why they are useful.
|
||||
Sometimes a piece of Scheme code isn't working and you'd like to go
|
||||
through it step by step. You can do this in Guile by setting a
|
||||
breakpoint at the start of the relevant code, and then using the command
|
||||
line or Emacs interface to step through it.
|
||||
|
||||
Broadly speaking, Guile's breakpoint support consists of
|
||||
A breakpoint can be specified by procedure name or by location -- the
|
||||
relevant code's file name, line number and column number. For details
|
||||
please see the full documentation for @code{break-in} and
|
||||
@code{break-at} in @ref{Intro to Breakpoints}.
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
type-specific features for @emph{creating} breakpoints of various types
|
||||
|
||||
@item
|
||||
relatively generic features for @emph{manipulating} the behaviour of
|
||||
breakpoints once they've been created.
|
||||
@end itemize
|
||||
|
||||
Different breakpoint types are implemented as different classes in a
|
||||
GOOPS hierarchy with common base class @code{<breakpoint>}. The magic
|
||||
of generic functions then allows most of the manipulation functions to
|
||||
be generic by default but specializable (by breakpoint class) if the
|
||||
need arises.
|
||||
|
||||
Generic breakpoint support is provided by the @code{(ice-9 debugger
|
||||
breakpoints)} module, so you will almost always need to use this module
|
||||
in order to access the functionality described here:
|
||||
|
||||
@smalllisp
|
||||
(use-modules (ice-9 debugger breakpoints))
|
||||
@end smalllisp
|
||||
|
||||
@noindent
|
||||
You may like to add this to your @file{.guile} file.
|
||||
When you set a breakpoint, you can specify any ``behaviour'' you like
|
||||
for what should happen when the breakpoint is hit; a breakpoint
|
||||
``behaviour'' is just a Scheme procedure with the right signature.
|
||||
|
||||
@menu
|
||||
* Breakpoints Overview::
|
||||
* Source Breakpoints::
|
||||
* Procedural Breakpoints::
|
||||
* Setting Breakpoints::
|
||||
* break! trace! trace-subtree!::
|
||||
* Accessing Breakpoints::
|
||||
* Breakpoint Behaviours::
|
||||
* Enabling and Disabling::
|
||||
* Deleting Breakpoints::
|
||||
* Breakpoint Information::
|
||||
* Other Breakpoint Types::
|
||||
@end menu
|
||||
|
||||
|
||||
|
|
@ -187,8 +248,9 @@ available:
|
|||
|
||||
@itemize @bullet
|
||||
@item
|
||||
all the commands as described for last error debugging (@pxref{Debug
|
||||
Last Error}), which allow you to explore the stack and so on
|
||||
all the commands as described for last error debugging
|
||||
(@pxref{Interactive Debugger}), which allow you to explore the stack and
|
||||
so on
|
||||
|
||||
@item
|
||||
additional commands for continuing program execution in various ways:
|
||||
|
|
@ -200,607 +262,13 @@ Use of the interactive debugger is described in @ref{Interactive
|
|||
Debugger}.
|
||||
|
||||
|
||||
@node Source Breakpoints
|
||||
@subsubsection Source Breakpoints
|
||||
|
||||
A source breakpoint is a breakpoint that triggers whenever program
|
||||
execution hits a particular source location. A source breakpoint can be
|
||||
conveniently set simply by evaluating code that has @code{##} inserted
|
||||
into it at the position where you want the breakpoint to be.
|
||||
|
||||
For example, to set a breakpoint immediately before evaluation of
|
||||
@code{(= n 0)} in the following procedure definition, evaluate:
|
||||
|
||||
@smalllisp
|
||||
(define (fact1 n)
|
||||
(if ##(= n 0)
|
||||
1
|
||||
(* n (fact1 (- n 1)))))
|
||||
@print{}
|
||||
Set breakpoint 1: standard input:4:9: (= n 0)
|
||||
@end smalllisp
|
||||
|
||||
@noindent
|
||||
Note the message confirming that you have set a breakpoint. If you
|
||||
don't see this, something isn't working.
|
||||
|
||||
@code{##} is provided by the @code{(ice-9 debugger breakpoints source)} module,
|
||||
so you must use this module before trying to set breakpoints in this
|
||||
way:
|
||||
|
||||
@smalllisp
|
||||
(use-modules (ice-9 debugger breakpoints source))
|
||||
@end smalllisp
|
||||
|
||||
@noindent
|
||||
You may like to add this to your @file{.guile} file.
|
||||
|
||||
The default behaviour for source breakpoints is @code{debug-here}
|
||||
(@pxref{Breakpoint Behaviours}), which means to enter the command line
|
||||
debugger when the breakpoint is hit. So, if you now use @code{fact1},
|
||||
that is what happens.
|
||||
|
||||
@smalllisp
|
||||
guile> (fact1 3)
|
||||
Hit breakpoint 1: standard input:4:9: (= n 0)
|
||||
Frame 3 at standard input:4:9
|
||||
(= n 0)
|
||||
debug>
|
||||
@end smalllisp
|
||||
|
||||
|
||||
@node Procedural Breakpoints
|
||||
@subsubsection Procedural Breakpoints
|
||||
|
||||
A procedural breakpoint is a breakpoint that triggers whenever Guile is
|
||||
about to apply a specified procedure to its (already evaluated)
|
||||
arguments. To set a procedural breakpoint, call @code{break!} with the
|
||||
target procedure as a single argument. For example:
|
||||
|
||||
@smalllisp
|
||||
(define (fact1 n)
|
||||
(if (= n 0)
|
||||
1
|
||||
(* n (fact1 (- n 1)))))
|
||||
|
||||
(break! fact1)
|
||||
@print{}
|
||||
Set breakpoint 1: [fact1]
|
||||
@result{}
|
||||
#<<procedure-breakpoint> 808b0b0>
|
||||
@end smalllisp
|
||||
|
||||
Alternatives to @code{break!} are @code{trace!} and
|
||||
@code{trace-subtree!}. The difference is that these three calls create
|
||||
a breakpoint in the same place but with three different behaviours,
|
||||
respectively @code{debug-here}, @code{trace-here} and
|
||||
@code{trace-subtree}. Breakpoint behaviours are documented fully later
|
||||
(@pxref{Breakpoint Behaviours}), but to give a quick taste, here's an
|
||||
example of running code that includes a procedural breakpoint with the
|
||||
@code{trace-here} behaviour.
|
||||
|
||||
@smalllisp
|
||||
(trace! fact1)
|
||||
@print{}
|
||||
Set breakpoint 1: [fact1]
|
||||
@result{}
|
||||
#<<procedure-breakpoint> 808b0b0>
|
||||
|
||||
(fact1 4)
|
||||
@print{}
|
||||
| [fact1 4]
|
||||
| | [fact1 3]
|
||||
| | | [fact1 2]
|
||||
| | | | [fact1 1]
|
||||
| | | | | [fact1 0]
|
||||
| | | | | 1
|
||||
| | | | 2
|
||||
| | | 6
|
||||
| | 24
|
||||
| 24
|
||||
@result{}
|
||||
24
|
||||
@end smalllisp
|
||||
|
||||
To set and use procedural breakpoints, you will need to use the
|
||||
@code{(ice-9 debugger breakpoints procedural)} module:
|
||||
|
||||
@smalllisp
|
||||
(use-modules (ice-9 debugger breakpoints procedural))
|
||||
@end smalllisp
|
||||
|
||||
@noindent
|
||||
You may like to add this to your @file{.guile} file.
|
||||
|
||||
|
||||
@node Setting Breakpoints
|
||||
@subsubsection Setting Breakpoints
|
||||
|
||||
In general, that is. We've already seen how to set source and
|
||||
procedural breakpoints conveniently in practice. This section explains
|
||||
how those conveniences map onto a more general mechanism.
|
||||
|
||||
The general mechanism for setting breakpoints is the generic function
|
||||
@code{set-breakpoint!}. Different kinds of breakpoints define
|
||||
subclasses of the class @code{<breakpoint>} and provide their own
|
||||
methods for @code{set-pbreakpoint!}.
|
||||
|
||||
For example, @code{(ice-9 debugger breakpoints procedural)} implements
|
||||
the @code{<procedure-breakpoint>} subclass and provides a
|
||||
@code{set-breakpoint!} method that takes a procedure argument:
|
||||
|
||||
@smalllisp
|
||||
(set-breakpoint! @var{behavior} fact1)
|
||||
@print{}
|
||||
Set breakpoint 1: [fact1]
|
||||
@result{}
|
||||
#<<procedure-breakpoint> 808b0b0>
|
||||
@end smalllisp
|
||||
|
||||
A non-type-specific @code{set-breakpoint!} method is provided by the
|
||||
generic module @code{(ice-9 debugger breakpoints)}. It allows you to
|
||||
change the behaviour of an existing breakpoint that is identified by
|
||||
its breakpoint number.
|
||||
|
||||
@smalllisp
|
||||
(set-breakpoint! @var{behavior} 1)
|
||||
@end smalllisp
|
||||
|
||||
@node break! trace! trace-subtree!
|
||||
@subsubsection break! trace! trace-subtree!
|
||||
|
||||
We have already talked above about the use of @code{break!},
|
||||
@code{trace!} and @code{trace-subtree!} for setting procedural
|
||||
breakpoints. Now that @code{set-breakpoint!} has been introduced, we
|
||||
can reveal that @code{break!}, @code{trace!} and @code{trace-subtree!}
|
||||
are in fact just wrappers for @code{set-breakpoint!} that specify
|
||||
particular breakpoint behaviours, respectively @code{debug-here},
|
||||
@code{trace-here} and @code{trace-subtree}.
|
||||
|
||||
@smalllisp
|
||||
(break! . @var{args})
|
||||
@equiv{} (set-breakpoint! debug-here . @var{args})
|
||||
(trace! . @var{args})
|
||||
@equiv{} (set-breakpoint! trace-here . @var{args})
|
||||
(trace-subtree! . @var{args})
|
||||
@equiv{} (set-breakpoint! trace-subtree . @var{args})
|
||||
@end smalllisp
|
||||
|
||||
This means that these three procedures can be used to set the
|
||||
corresponding behaviours for any type of breakpoint for which a
|
||||
@code{set-breakpoint!} method exists, not just procedural ones.
|
||||
|
||||
|
||||
@node Accessing Breakpoints
|
||||
@subsubsection Accessing Breakpoints
|
||||
|
||||
Information about the state and behaviour of a breakpoint is stored in
|
||||
an instance of the appropriate breakpoint class. To access and change
|
||||
that information, therefore, you need to get hold of the desired
|
||||
breakpoint instance.
|
||||
|
||||
The generic function @code{get-breakpoint} meets this need: For every
|
||||
@code{set-breakpoint!} method there is a corresponding
|
||||
@code{get-breakpoint} method. Note especially the useful
|
||||
type-independent case:
|
||||
|
||||
@smalllisp
|
||||
(get-breakpoint 1)
|
||||
@result{}
|
||||
#<<procedure-breakpoint> 808b0b0>
|
||||
@end smalllisp
|
||||
|
||||
|
||||
@node Breakpoint Behaviours
|
||||
@subsubsection Breakpoint Behaviours
|
||||
|
||||
A breakpoint's @dfn{behaviour} determines what happens when that
|
||||
breakpoint is hit. Several kinds of behaviour are generally useful.
|
||||
|
||||
@table @code
|
||||
@item debug-here
|
||||
Enter the command line debugger. This gives the opportunity to explore
|
||||
the stack, evaluate expressions in any of the pending stack frames,
|
||||
change breakpoint properties or set new breakpoints, and continue
|
||||
program execution when you are done.
|
||||
|
||||
@item trace-here
|
||||
Trace the current stack frame. For expressions being evaluated, this
|
||||
shows the expression. For procedure applications, it shows the
|
||||
procedure name and its arguments @emph{post-evaluation}. For both
|
||||
expressions and applications, the indentation of the tracing indicates
|
||||
whether the traced items are mutually tail recursive.
|
||||
|
||||
@item trace-subtree
|
||||
Trace the current stack frame, and enable tracing for all future
|
||||
evaluations and applications until the current stack frame is exited.
|
||||
@code{trace-subtree} is a great preliminary exploration tool when all
|
||||
you know is that there is a bug ``somewhere in XXX or in something that
|
||||
XXX calls''.
|
||||
|
||||
@item (at-exit @var{thunk})
|
||||
Don't do anything now, but arrange for @var{thunk} to be executed when
|
||||
the current stack frame is exited. For example, the operation that most
|
||||
debugging tools call ``finish'' is @code{(at-exit debug-here)}.
|
||||
|
||||
@item (at-next @var{count} @var{thunk})
|
||||
@dots{} arrange for @var{thunk} to be executed when beginning the
|
||||
@var{count}th next evaluation or application with source location in the
|
||||
current file.
|
||||
|
||||
@item (at-entry @var{count} @var{thunk})
|
||||
@dots{} arrange for @var{thunk} to be executed when beginning the
|
||||
@var{count}th next evaluation (regardless of source location).
|
||||
|
||||
@item (at-apply @var{count} @var{thunk})
|
||||
@dots{} arrange for @var{thunk} to be executed just before performing
|
||||
the @var{count}th next application (regardless of source location).
|
||||
|
||||
@item (at-step @var{count} @var{thunk})
|
||||
Synthesis of @code{at-entry} and @code{at-apply}; counts both
|
||||
evaluations and applications.
|
||||
@end table
|
||||
|
||||
Every breakpoint instance has a slot in which its behaviour is stored.
|
||||
If you have a breakpoint instance in hand, you can change its behaviour
|
||||
using the @code{bp-behaviour} accessor.
|
||||
|
||||
An @dfn{accessor} supports the setting of a property like this:
|
||||
|
||||
@smalllisp
|
||||
(set! (bp-behaviour @var{breakpoint}) @var{new-behaviour})
|
||||
@end smalllisp
|
||||
|
||||
@noindent
|
||||
See the GOOPS manual for further information on accessors.
|
||||
|
||||
Alternatively, if you know how to specify the @var{location-args} for
|
||||
the breakpoint in question, you can change its behaviour using
|
||||
@code{set-breakpoint!}. For example:
|
||||
|
||||
@smalllisp
|
||||
;; Change behaviour of breakpoint number 2.
|
||||
(set-breakpoint! @var{new-behaviour} 2)
|
||||
|
||||
;; Change behaviour of procedural breakpoint on [fact1].
|
||||
(set-breakpoint! @var{new-behaviour} fact1)
|
||||
@end smalllisp
|
||||
|
||||
In all cases, the behaviour that you specify should be either a single
|
||||
thunk, or a list of thunks, to be called when the breakpoint is hit.
|
||||
|
||||
The most common behaviours above are exported as thunks from the
|
||||
@code{(ice-9 debugger behaviour)} module. So, if you use this module, you can
|
||||
use those behaviours directly like this:
|
||||
|
||||
@smalllisp
|
||||
(use-modules (ice-9 debugger behaviour))
|
||||
(set-breakpoint! trace-subtree 2)
|
||||
(set! (bp-behaviour (get-breakpoint 3)) debug-here)
|
||||
@end smalllisp
|
||||
|
||||
@noindent
|
||||
You can also use the list option to combine common behaviours:
|
||||
|
||||
@smalllisp
|
||||
(set-breakpoint! (list trace-here debug-here) 2)
|
||||
@end smalllisp
|
||||
|
||||
@noindent
|
||||
Or, for more customized behaviour, you could build and use your own
|
||||
thunk like this:
|
||||
|
||||
@smalllisp
|
||||
(define (my-behaviour)
|
||||
(trace-here)
|
||||
(at-exit (lambda ()
|
||||
(display "Exiting frame of my-behaviour bp\n")
|
||||
... do something unusual ...)))
|
||||
|
||||
(set-breakpoint my-behaviour 2)
|
||||
@end smalllisp
|
||||
|
||||
|
||||
@node Enabling and Disabling
|
||||
@subsubsection Enabling and Disabling
|
||||
|
||||
Independently of its behaviour, each breakpoint also keeps track of
|
||||
whether it is currently enabled. This is a straightforward convenience
|
||||
to allow breakpoints to be temporarily switched off without losing all
|
||||
their carefully constructed properties.
|
||||
|
||||
If you have a breakpoint instance in hand, you can enable or disable it
|
||||
using the @code{bp-enabled?} accessor.
|
||||
|
||||
Alternatively, you can enable or disable a breakpoint via its location
|
||||
args by using @code{enable-breakpoint!} or @code{disable-breakpoint!}.
|
||||
|
||||
@smalllisp
|
||||
(disable-breakpoint! fact1) ; disable the procedural breakpoint on fact1
|
||||
(enable-breakpoint! 1) ; enable breakpoint 1
|
||||
@end smalllisp
|
||||
|
||||
@code{enable-breakpoint!} and @code{disable-breakpoint!} are implemented
|
||||
using @code{get-breakpoint} and @code{bp-enabled?}, so any
|
||||
@var{location-args} that are valid for @code{get-breakpoint} will work
|
||||
also for these procedures.
|
||||
|
||||
|
||||
@node Deleting Breakpoints
|
||||
@subsubsection Deleting Breakpoints
|
||||
|
||||
Given a breakpoint instance in hand, you can deactivate it and remove
|
||||
it from the global list of current breakpoints by calling
|
||||
@code{bp-delete!}.
|
||||
|
||||
Alternatively, you can delete a breakpoint by its location args:
|
||||
|
||||
@smalllisp
|
||||
(delete-breakpoint! 1) ; delete breakpoint 1
|
||||
@end smalllisp
|
||||
|
||||
@code{delete-breakpoint!} is implemented using @code{get-breakpoint} and
|
||||
@code{bp-delete!}, so any @var{location-args} that are valid for
|
||||
@code{get-breakpoint} will work also for @code{delete-breakpoint!}.
|
||||
|
||||
There is no way to reinstate a deleted breakpoint. Final destruction of
|
||||
the breakpoint instance is determined by the usual garbage collection
|
||||
rules.
|
||||
|
||||
|
||||
@node Breakpoint Information
|
||||
@subsubsection Breakpoint Information
|
||||
|
||||
To get Guile to print a description of a breakpoint instance, use
|
||||
@code{bp-describe}:
|
||||
|
||||
@smalllisp
|
||||
(bp-describe (get-breakpoint 1) #t) ; #t specifies standard output
|
||||
@print{}
|
||||
Breakpoint 1: [fact1]
|
||||
enabled? = #t
|
||||
behaviour = #<procedure trace-here ()>
|
||||
@end smalllisp
|
||||
|
||||
Following the usual model, @code{describe-breakpoint} is also provided:
|
||||
|
||||
@smalllisp
|
||||
(describe-breakpoint 1)
|
||||
@print{}
|
||||
Breakpoint 1: [fact1]
|
||||
enabled? = #t
|
||||
behaviour = #<procedure trace-here ()>
|
||||
@end smalllisp
|
||||
|
||||
Finally, two stragglers. @code{all-breakpoints} returns a list of all
|
||||
current breakpoints. @code{describe-all-breakpoints} combines
|
||||
@code{bp-describe} and @code{all-breakpoints} by printing a description
|
||||
of all current breakpoints to standard output.
|
||||
|
||||
@node Other Breakpoint Types
|
||||
@subsubsection Other Breakpoint Types
|
||||
|
||||
Besides source and procedural breakpoints, Guile includes an early
|
||||
implementation of a third class of breakpoints: @dfn{range} breakpoints.
|
||||
These are breakpoints that trigger when program execution enters (or
|
||||
perhaps exits) a defined range of source locations.
|
||||
|
||||
Sadly, these don't yet work well. The apparent problem is that the
|
||||
extra methods for @code{set-breakpoint!} and @code{get-breakpoint} cause
|
||||
some kind of explosion in the time taken by GOOPS to construct its
|
||||
method cache and to dispatch calls involving these generic functions.
|
||||
But we haven't really investigated enough to be sure that this is the
|
||||
real issue.
|
||||
|
||||
If you're interested in looking and/or investigating anyway, please feel
|
||||
free to check out and play with the @code{(ice-9 debugger breakpoints
|
||||
range)} module.
|
||||
|
||||
The other kind of breakpoint that we'd like to have is watchpoints, but
|
||||
this hasn't been implemented at all yet. Watchpoints may turn out to be
|
||||
impractical for performance reasons.
|
||||
|
||||
|
||||
@node Interactive Debugger
|
||||
@subsection Using the Interactive Debugger
|
||||
|
||||
Guile's interactive debugger is a command line application that accepts
|
||||
commands from you for examining the stack and, if at a breakpoint, 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
|
||||
This is the Guile debugger -- for help, type `help'.
|
||||
There are 3 frames on the stack.
|
||||
|
||||
Frame 2 at standard input:36:19
|
||||
[+ 3 #\s]
|
||||
debug>
|
||||
@end lisp
|
||||
|
||||
@noindent
|
||||
``debug>'' is the debugger's prompt, and a useful reminder that you are
|
||||
not in the normal Guile REPL. The available commands are described in
|
||||
detail in the following subsections.
|
||||
|
||||
@menu
|
||||
* Display Backtrace:: backtrace.
|
||||
* Frame Selection:: up, down, frame.
|
||||
* Frame Information:: info args, info frame, position.
|
||||
* Frame Evaluation:: evaluate.
|
||||
* Single Stepping:: step, next.
|
||||
* Run To Frame Exit:: finish, trace-finish.
|
||||
* Continue Execution:: continue.
|
||||
* Leave Debugger:: quit.
|
||||
@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
|
||||
debug> bt
|
||||
In standard input:
|
||||
36: 0* [make-string ...
|
||||
36: 1* [* 4 ...
|
||||
36: 2* [+ 3 #\s]
|
||||
@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{backtrace} procedure --- see @ref{Backtrace Format} for details.
|
||||
|
||||
|
||||
@node Frame Selection
|
||||
@subsubsection Frame Selection
|
||||
|
||||
A call stack consists of a sequence of stack @dfn{frames}, with each
|
||||
frame describing one level of the nested evaluations and applications
|
||||
that the program was executing when it hit a breakpoint or an error.
|
||||
Frames are numbered such that frame 0 is the outermost --- i.e. the
|
||||
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).
|
||||
|
||||
When you enter the debugger, the innermost frame is selected, which
|
||||
means that the commands for getting information about the ``current''
|
||||
frame, or for evaluating expressions in the context of the current
|
||||
frame, will do so by default with respect to the innermost frame. To
|
||||
select a different frame, so that these operations will apply to it
|
||||
instead, use the @code{up}, @code{down} and @code{frame} commands like
|
||||
this:
|
||||
|
||||
@lisp
|
||||
debug> up
|
||||
Frame 1 at standard input:36:14
|
||||
[* 4 ...
|
||||
debug> frame 0
|
||||
Frame 0 at standard input:36:1
|
||||
[make-string ...
|
||||
debug> down
|
||||
Frame 1 at standard input:36:14
|
||||
[* 4 ...
|
||||
@end lisp
|
||||
|
||||
@deffn {Debugger Command} up [n]
|
||||
Move @var{n} frames up the stack. For positive @var{n}, this
|
||||
advances toward the outermost frame, to higher frame numbers, to
|
||||
frames that have existed longer. @var{n} defaults to one.
|
||||
@end deffn
|
||||
|
||||
@deffn {Debugger Command} down [n]
|
||||
Move @var{n} frames down the stack. For positive @var{n}, this
|
||||
advances toward the innermost frame, to lower frame numbers, to frames
|
||||
that were created more recently. @var{n} defaults to one.
|
||||
@end deffn
|
||||
|
||||
@deffn {Debugger Command} frame [n]
|
||||
Select and print a stack frame. With no argument, print the selected
|
||||
stack frame. (See also ``info frame''.) An argument specifies the
|
||||
frame to select; it must be a stack-frame number.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Frame Information
|
||||
@subsubsection Frame Information
|
||||
|
||||
[to be completed]
|
||||
|
||||
@deffn {Debugger Command} {info frame}
|
||||
All about selected stack frame.
|
||||
@end deffn
|
||||
|
||||
@deffn {Debugger Command} {info args}
|
||||
Argument variables of current stack frame.
|
||||
@end deffn
|
||||
|
||||
@deffn {Debugger Command} position
|
||||
Display the position of the current expression.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Frame Evaluation
|
||||
@subsubsection Frame Evaluation
|
||||
|
||||
[to be completed]
|
||||
|
||||
@deffn {Debugger Command} evaluate expression
|
||||
Evaluate an expression.
|
||||
The expression must appear on the same line as the command,
|
||||
however it may be continued over multiple lines.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Single Stepping
|
||||
@subsubsection Single Stepping
|
||||
|
||||
[to be completed]
|
||||
|
||||
@deffn {Debugger Command} step [n]
|
||||
Continue until entry to @var{n}th next frame.
|
||||
@end deffn
|
||||
|
||||
@deffn {Debugger Command} next [n]
|
||||
Continue until entry to @var{n}th next frame in same file.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Run To Frame Exit
|
||||
@subsubsection Run To Frame Exit
|
||||
|
||||
[to be completed]
|
||||
|
||||
@deffn {Debugger Command} finish
|
||||
Continue until evaluation of the current frame is complete, and
|
||||
print the result obtained.
|
||||
@end deffn
|
||||
|
||||
@deffn {Debugger Command} trace-finish
|
||||
Trace until evaluation of the current frame is complete.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Continue Execution
|
||||
@subsubsection Continue Execution
|
||||
|
||||
[to be completed]
|
||||
|
||||
@deffn {Debugger Command} continue
|
||||
Continue program execution.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Leave Debugger
|
||||
@subsubsection Leave Debugger
|
||||
|
||||
[to be completed]
|
||||
|
||||
@deffn {Debugger Command} quit
|
||||
Exit the debugger.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Tracing
|
||||
@subsection Tracing
|
||||
|
||||
Tracing has already been described as a breakpoint behaviour
|
||||
(@pxref{Breakpoint Behaviours}), but we mention it again here because it
|
||||
is so useful, and because Guile actually now has @emph{two} mechanisms
|
||||
for tracing, and its worth clarifying the differences between them.
|
||||
Tracing has already been described as a breakpoint behaviour, but we
|
||||
mention it again here because it is so useful, and because Guile
|
||||
actually now has @emph{two} mechanisms for tracing, and its worth
|
||||
clarifying the differences between them.
|
||||
|
||||
@menu
|
||||
* Old Tracing:: Tracing provided by (ice-9 debug).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue