summaryrefslogtreecommitdiff
path: root/doc/ref/debugging.texi
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2001-11-11 15:01:52 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2001-11-11 15:01:52 +0000
commit9401323e63278a7053c54565e8d688f6cbe34f54 (patch)
tree01e0840bac67d78e974b03200f9cf16f894fea37 /doc/ref/debugging.texi
parenta0a9b9ad4263e129e46e31a8c0c2e7775b037ee9 (diff)
downloadguile-9401323e63278a7053c54565e8d688f6cbe34f54.tar.gz
* Documentation work.
Diffstat (limited to 'doc/ref/debugging.texi')
-rw-r--r--doc/ref/debugging.texi179
1 files changed, 179 insertions, 0 deletions
diff --git a/doc/ref/debugging.texi b/doc/ref/debugging.texi
new file mode 100644
index 000000000..28607c551
--- /dev/null
+++ b/doc/ref/debugging.texi
@@ -0,0 +1,179 @@
+@page
+@node Debugger User Interface
+@chapter Debugger User Interface
+
+@c --- The title and introduction of this appendix need to
+@c distinguish this clearly from the chapter on the internal
+@c debugging interface.
+
+When debugging a program, programmers often find it helpful to examine
+the program's internal status while it runs: the values of internal
+variables, the choices made in @code{if} and @code{cond} statements, and
+so forth. Guile Scheme provides a debugging interface that programmers
+can use to single-step through Scheme functions and examine symbol
+bindings. This is different from the @ref{Debugging}, which permits
+programmers to debug the Guile interpreter itself. Most programmers
+will be more interested in debugging their own Scheme programs than the
+interpreter which evaluates them.
+
+[FIXME: should we include examples of traditional debuggers
+and explain why they can't be used to debug interpreted Scheme or Lisp?]
+
+@menu
+* Single-Step:: Execute a program or function one step at a time.
+* Trace:: Print a report each time a given function is called.
+* Backtrace:: See a list of the statements that caused an error.
+* Stacks and Frames:: Examine the state of an interrupted program.
+@end menu
+
+
+@node Single-Step
+@section Single-Step
+
+
+@node Trace
+@section Trace
+
+When a function is @dfn{traced}, it means that every call to that
+function is reported to the user during a program run. This can help a
+programmer determine whether a function is being called at the wrong
+time or with the wrong set of arguments.
+
+@defun trace function
+Enable debug tracing on @code{function}. While a program is being run, Guile
+will print a brief report at each call to a traced function,
+advising the user which function was called and the arguments that were
+passed to it.
+@end defun
+
+@defun untrace function
+Disable debug tracing for @code{function}.
+@end defun
+
+Example:
+
+@lisp
+(define (rev ls)
+ (if (null? ls)
+ '()
+ (append (rev (cdr ls))
+ (cons (car ls) '())))) @result{} rev
+
+(trace rev) @result{} (rev)
+
+(rev '(a b c d e))
+@result{} [rev (a b c d e)]
+ | [rev (b c d e)]
+ | | [rev (c d e)]
+ | | | [rev (d e)]
+ | | | | [rev (e)]
+ | | | | | [rev ()]
+ | | | | | ()
+ | | | | (e)
+ | | | (e d)
+ | | (e d c)
+ | (e d c b)
+ (e d c b a)
+ (e d c b a)
+@end lisp
+
+Note the way Guile indents the output, illustrating the depth of
+execution at each function call. This can be used to demonstrate, for
+example, that Guile implements self-tail-recursion properly:
+
+@lisp
+(define (rev ls sl)
+ (if (null? ls)
+ sl
+ (rev (cdr ls)
+ (cons (car ls) sl)))) @result{} rev
+
+(trace rev) @result{} (rev)
+
+(rev '(a b c d e) '())
+@result{} [rev (a b c d e) ()]
+ [rev (b c d e) (a)]
+ [rev (c d e) (b a)]
+ [rev (d e) (c b a)]
+ [rev (e) (d c b a)]
+ [rev () (e d c b a)]
+ (e d c b a)
+ (e d c b a)
+@end lisp
+
+Since the tail call is effectively optimized to a @code{goto} statement,
+there is no need for Guile to create a new stack frame for each
+iteration. Using @code{trace} here helps us see why this is so.
+
+@node Backtrace
+@appendixsec Backtrace
+
+@node Stacks and Frames
+@appendixsec Stacks and Frames
+
+When a running program is interrupted, usually upon reaching an error or
+breakpoint, its state is represented by a @dfn{stack} of suspended
+function calls, each of which is called a @dfn{frame}. The programmer
+can learn more about the program's state at the point of interruption by
+inspecting and modifying these frames.
+
+@deffn primitive stack? obj
+Return @code{#t} if @var{obj} is a calling stack.
+@end deffn
+
+@deffn primitive make-stack
+@end deffn
+
+@deffn syntax start-stack id exp
+Evaluate @var{exp} on a new calling stack with identity @var{id}. If
+@var{exp} is interrupted during evaluation, backtraces will not display
+frames farther back than @var{exp}'s top-level form. This macro is a
+way of artificially limiting backtraces and stack procedures, largely as
+a convenience to the user.
+@end deffn
+
+@deffn primitive stack-id stack
+Return the identifier given to @var{stack} by @code{start-stack}.
+@end deffn
+
+@deffn primitive stack-ref
+@end deffn
+
+@deffn primitive stack-length
+@end deffn
+
+@deffn primitive frame?
+@end deffn
+
+@deffn primitive last-stack-frame
+@end deffn
+
+@deffn primitive frame-number
+@end deffn
+
+@deffn primitive frame-source
+@end deffn
+
+@deffn primitive frame-procedure
+@end deffn
+
+@deffn primitive frame-arguments
+@end deffn
+
+@deffn primitive frame-previous
+@end deffn
+
+@deffn primitive frame-next
+@end deffn
+
+@deffn primitive frame-real?
+@end deffn
+
+@deffn primitive frame-procedure?
+@end deffn
+
+@deffn primitive frame-evaluating-args?
+@end deffn
+
+@deffn primitive frame-overflow
+@end deffn