doc/ref/debugging.texi

   1 @page
   2 @node Debugging Features
   3 @chapter Debugging Features
   4
   5 @c      --- The title and introduction of this appendix need to
   6 @c          distinguish this clearly from the chapter on the internal
   7 @c          debugging interface.
   8
   9 When debugging a program, programmers often find it helpful to examine
  10 the program's internal status while it runs: the values of internal
  11 variables, the choices made in @code{if} and @code{cond} statements, and
  12 so forth.  Guile Scheme provides a debugging interface that programmers
  13 can use to single-step through Scheme functions and examine symbol
  14 bindings.  This is different from the @ref{Debugging}, which permits
  15 programmers to debug the Guile interpreter itself.  Most programmers
  16 will be more interested in debugging their own Scheme programs than the
  17 interpreter which evaluates them.
  18
  19 [FIXME: should we include examples of traditional debuggers
  20 and explain why they can't be used to debug interpreted Scheme or Lisp?]
  21
  22 @menu
  23 * Single-Step::         Execute a program or function one step at a time.
  24 * Trace::               Print a report each time a given function is called.
  25 * Backtrace::           See a list of the statements that caused an error.
  26 @end menu
  27
  28
  29 @node Single-Step
  30 @section Single-Step
  31
  32
  33 @node Trace
  34 @section Trace
  35
  36 When a function is @dfn{traced}, it means that every call to that
  37 function is reported to the user during a program run.  This can help a
  38 programmer determine whether a function is being called at the wrong
  39 time or with the wrong set of arguments.
  40
  41 @defun trace function
  42 Enable debug tracing on @code{function}.  While a program is being run, Guile
  43 will print a brief report at each call to a traced function,
  44 advising the user which function was called and the arguments that were
  45 passed to it.
  46 @end defun
  47
  48 @defun untrace function
  49 Disable debug tracing for @code{function}.
  50 @end defun
  51
  52 Example:
  53
  54 @lisp
  55 (define (rev ls)
  56   (if (null? ls)
  57       '()
  58       (append (rev (cdr ls))
  59               (cons (car ls) '())))) @result{} rev
  60
  61 (trace rev) @result{} (rev)
  62
  63 (rev '(a b c d e))
  64 @result{} [rev (a b c d e)]
  65    |  [rev (b c d e)]
  66    |  |  [rev (c d e)]
  67    |  |  |  [rev (d e)]
  68    |  |  |  |  [rev (e)]
  69    |  |  |  |  |  [rev ()]
  70    |  |  |  |  |  ()
  71    |  |  |  |  (e)
  72    |  |  |  (e d)
  73    |  |  (e d c)
  74    |  (e d c b)
  75    (e d c b a)
  76    (e d c b a)
  77 @end lisp
  78
  79 Note the way Guile indents the output, illustrating the depth of
  80 execution at each function call.  This can be used to demonstrate, for
  81 example, that Guile implements self-tail-recursion properly:
  82
  83 @lisp
  84 (define (rev ls sl)
  85   (if (null? ls)
  86       sl
  87       (rev (cdr ls)
  88            (cons (car ls) sl)))) @result{} rev
  89
  90 (trace rev) @result{} (rev)
  91
  92 (rev '(a b c d e) '())
  93 @result{} [rev (a b c d e) ()]
  94    [rev (b c d e) (a)]
  95    [rev (c d e) (b a)]
  96    [rev (d e) (c b a)]
  97    [rev (e) (d c b a)]
  98    [rev () (e d c b a)]
  99    (e d c b a)
 100    (e d c b a)
 101 @end lisp
 102
 103 Since the tail call is effectively optimized to a @code{goto} statement,
 104 there is no need for Guile to create a new stack frame for each
 105 iteration.  Using @code{trace} here helps us see why this is so.
 106
 107
 108 @node Backtrace
 109 @section Backtrace
 110
 111 @deffn {Scheme Procedure} backtrace
 112 @deffnx {C Function} scm_backtrace ()
 113 Display a backtrace of the stack saved by the last error
 114 to the current output port.
 115 @end deffn