diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2006-08-29 22:47:41 +0000 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2006-08-29 22:47:41 +0000 |
commit | 5b2da4cc18be3dfb97ced8fe2c64d0ae59d98793 (patch) | |
tree | 42534c077a3bf4e2bed486651adb59f529bf505f | |
parent | b5944f66723daaad141f440176b03c8987b6857c (diff) | |
download | guile-5b2da4cc18be3dfb97ced8fe2c64d0ae59d98793.tar.gz |
(Debug on Error): Added paragraph on need to use
debugging evaluator. Added text on what the Guile REPL code does.
-rw-r--r-- | doc/ref/ChangeLog | 5 | ||||
-rw-r--r-- | doc/ref/api-debug.texi | 28 |
2 files changed, 29 insertions, 4 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index 9d9da1f3c..969269e4b 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,8 @@ +2006-08-29 Neil Jerram <neil@ossau.uklinux.net> + + * api-debug.texi (Debug on Error): Added paragraph on need to use + debugging evaluator. Added text on what the Guile REPL code does. + 2006-08-28 Neil Jerram <neil@ossau.uklinux.net> * api-debug.texi (Examining the Stack): Minor improvements to diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index db759cc3a..5f816dc46 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -447,10 +447,19 @@ The other interesting information about an error is the full Scheme stack at the point where the error occurred; in other words what innermost expression was being evaluated, what was the expression that called that one, and so on. If you want to write your code so that it -captures and can display this information as well, there are two +captures and can display this information as well, there are three important things to understand. -Firstly, the stack at the point of the error needs to be explicitly +Firstly, the code in question must be executed using the debugging +version of the evaluator, because information about the Scheme stack is +only available at all from the debugging evaluator. Using the debugging +evaluator means that the debugger option (@pxref{Debugger options}) +called @code{debug} must be enabled; this can be done by running +@code{(debug-enable 'debug)} or @code{(turn-on-debugging)} at the top +level of your program; or by running guile with the @code{--debug} +command line option, if your program begins life as a Scheme script. + +Secondly, the stack at the point of the error needs to be explicitly captured by a @code{make-stack} call (or the C equivalent @code{scm_make_stack}). The Guile library does not do this ``automatically'' for you, so you will need to write code with a @@ -464,7 +473,7 @@ running on top of the Guile library, and which uses @code{catch} and @code{make-stack} in the way we are about to describe to capture the stack when an error occurs.) -Secondly, in order to capture the stack effectively at the point where +Thirdly, in order to capture the stack effectively at the point where the error occurred, the @code{make-stack} call must be made before Guile unwinds the stack back to the location of the prevailing catch expression. This means that the @code{make-stack} call must be made @@ -574,7 +583,14 @@ application frame -- that is, a frame that satisfies the @subsubsection What the Guile REPL does -[To be completed] +The Guile REPL code (in @file{ice-9/boot-9.scm}) uses a @code{catch} +with a pre-unwind handler to capture the stack when an error occurs in +an expression that was typed into the REPL, and saves the captured stack +in a fluid (@pxref{Fluids and Dynamic States}) called +@code{the-last-stack}. You can then use the @code{(backtrace)} command, +which is basically equivalent to @code{(display-backtrace (fluid-ref +the-last-stack))}, to print out this stack at any time until it is +overwritten by the next error that occurs. @deffn {Scheme Procedure} backtrace [highlights] @deffnx {C Function} scm_backtrace_with_highlights (highlights) @@ -585,6 +601,10 @@ it should be a list; the elements of this list will be highlighted wherever they appear in the backtrace. @end deffn +You can also use the @code{(debug)} command to explore the saved stack +using an interactive command-line-driven debugger. See @ref{Interactive +Debugger} for more information about this. + @deffn {Scheme Procedure} debug Invoke the Guile debugger to explore the context of the last error. @end deffn |