diff options
author | Andy Wingo <wingo@pobox.com> | 2010-10-07 22:57:07 +0200 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2010-10-07 22:57:07 +0200 |
commit | 3b541ca244459492592c65d94d46bf7489da1ce0 (patch) | |
tree | cebb517ffba05f0618fa5fad044d12d8b1913f34 /doc/ref/api-debug.texi | |
parent | de03880abeb1e91c5d4dffaaa0d26a5ee4e94e8e (diff) | |
download | guile-3b541ca244459492592c65d94d46bf7489da1ce0.tar.gz |
remove old debugging examples from api-debug
* doc/ref/api-debug.texi (Debugging Examples): Remove section, as the
tracing bits are adequately covered in tracing, and the breakpoints
and such will get covered in the debugging meta-commands section.
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r-- | doc/ref/api-debug.texi | 292 |
1 files changed, 1 insertions, 291 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index e6fbc7893..b3c7e6564 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -18,8 +18,7 @@ infrastructure that builds on top of those calls. * Evaluation Model:: Evaluation and the Scheme stack. * Source Properties:: From expressions to source locations. * Programmatic Error Handling:: Debugging when an error occurs. -* Traps:: -* Debugging Examples:: +* Traps:: Breakpoints, tracepoints, oh my! @end menu @node Evaluation Model @@ -1236,295 +1235,6 @@ Setting Traps The highest-level trap interface. Use this. @end deffn -@node Debugging Examples -@subsection Debugging Examples - -@c @node Tracing Examples -@subsubheading Tracing Examples - -The following examples show what tracing is and the kind of output that -it generates. In the first example, we define a recursive function for -reversing a list, then watch the effect of the recursive calls by -tracing each call and return value. - -@lisp -guile> (define (rev ls) - (if (null? ls) - ls - (append (rev (cdr ls)) - (list (car ls))))) -guile> (use-modules (ice-9 debugging traps) (ice-9 debugging trace)) -guile> (define t1 (make <procedure-trap> - #:procedure rev - #:behaviour (list trace-trap - trace-at-exit))) -guile> (install-trap t1) -guile> (rev '(a b c)) -| 2: [rev (a b c)] -| 3: [rev (b c)] -| 4: [rev (c)] -| 5: [rev ()] -| 5: =>() -| 4: =>(c) -| 3: =>(c b) -| 2: =>(c b a) -(c b a) -@end lisp - -@noindent -The number before the colon in this output (which follows @code{(ice-9 -debugging trace)}'s default output format) is the number of real frames -on the stack. The fact that this number increases for each recursive -call confirms that the implementation above of @code{rev} is not -tail-recursive. - -In the next example, we probe the @emph{internal} workings of -@code{rev} in more detail by using the @code{trace-until-exit} -behaviour. - -@lisp -guile> (uninstall-trap t1) -guile> (define t2 (make <procedure-trap> - #:procedure rev - #:behaviour (list trace-trap - trace-until-exit))) -guile> (install-trap t2) -guile> (rev '(a b)) -| 2: [rev (a b)] -| 2: (if (null? ls) ls (append (rev (cdr ls)) (list (car ls)))) -| 3: (null? ls) -| 3: [null? (a b)] -| 3: =>#f -| 2: (append (rev (cdr ls)) (list (car ls))) -| 3: (rev (cdr ls)) -| 4: (cdr ls) -| 4: [cdr (a b)] -| 4: =>(b) -| 3: [rev (b)] -| 3: (if (null? ls) ls (append (rev (cdr ls)) (list (car ls)))) -| 4: (null? ls) -| 4: [null? (b)] -| 4: =>#f -| 3: (append (rev (cdr ls)) (list (car ls))) -| 4: (rev (cdr ls)) -| 5: (cdr ls) -| 5: [cdr (b)] -| 5: =>() -| 4: [rev ()] -| 4: (if (null? ls) ls (append (rev (cdr ls)) (list (car ls)))) -| 5: (null? ls) -| 5: [null? ()] -| 5: =>#t -| 4: (list (car ls)) -| 5: (car ls) -| 5: [car (b)] -| 5: =>b -| 4: [list b] -| 4: =>(b) -| 3: [append () (b)] -| 3: =>(b) -| 3: (list (car ls)) -| 4: (car ls) -| 4: [car (a b)] -| 4: =>a -| 3: [list a] -| 3: =>(a) -| 2: [append (b) (a)] -| 2: =>(b a) -(b a) -@end lisp - -@noindent -The output in this case shows every step that the evaluator performs -in evaluating @code{(rev '(a b))}. - - -Here we present some examples of what you can do with the debugging -facilities just described. - -@subsubheading Single Stepping through a Procedure's Code - -A good way to explore in detail what a Scheme procedure does is to set -a trap on it and then single step through what it does. To do this, -make and install a @code{<procedure-trap>} with the @code{debug-trap} -behaviour from @code{(ice-9 debugger)}. - -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 traps)) -guile> (load "matrix.scm") -guile> (install-trap (make <procedure-trap> - #:procedure mkmatrix - #:behaviour debug-trap)) -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 hi!)) -debug> info frame -Stack frame: 3 -This frame is an evaluation. -The expression being evaluated is: -matrix.scm:4:3: - (let ((x 1)) (quote hi!)) -debug> next -Frame 3 at matrix.scm:5:21 - (quote hi!) -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 hi!) -debug> quit -hi! -guile> -@end lisp - -Or you can use Guile's Emacs interface (GDS), by using the module -@code{(ice-9 gds-client)} instead of @code{(ice-9 debugger)} 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. - - -@subsubheading 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? For this requirement you -can install a trap on the procedure, as in the previous example, but -instead of @code{debug-trap} or @code{gds-debug-trap}, 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 traps) (ice-9 debugging trace)) -guile> (load "matrix.scm") -guile> (install-trap (make <procedure-trap> - #:procedure mkmatrix - #:behaviour (list trace-trap trace-until-exit))) -guile> (do-main 4) -| 2: [mkmatrix] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq define (debug)] -| 5: =>#f -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq define (debug)] -| 5: =>#f -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq let (debug)] -| 5: =>#f -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq let (debug)] -| 5: =>#f -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq let (debug)] -| 5: =>#f -| 2: (letrec ((yy 23)) (let ((x 1)) (quote hi!))) -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq let (debug)] -| 5: =>#f -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq let (debug)] -| 5: =>#f -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq let (debug)] -| 5: =>#f -| 2: (let ((x 1)) (quote hi!)) -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] -| 4: (and (memq sym bindings) (let ...)) -| 5: (memq sym bindings) -| 5: [memq let (debug)] -| 5: =>#f -| 2: [let (let # #) (# # #)] -| 2: [let (let # #) (# # #)] -| 2: =>(#@@let* (x 1) #@@let (quote hi!)) -hi! -guile> (do-main 4) -| 2: [mkmatrix] -| 2: (letrec ((yy 23)) (let* ((x 1)) (quote hi!))) -| 2: (let* ((x 1)) (quote hi!)) -| 2: (quote hi!) -| 2: =>hi! -hi! -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 hi!))) -| matrix.scm:3:2: (let* ((x 1)) (quote hi!)) -| matrix.scm:4:4: (quote hi!) -| matrix.scm:4:4: =>hi! -hi! -guile> -@end lisp - @c Local Variables: @c TeX-master: "guile.texi" @c End: |