@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Debugging
@section Debugging Infrastructure
+@cindex Debugging
In order to understand Guile's debugging facilities, you first need to
-understand a little about how the evaluator works and what the Scheme
-stack is. With that in place we explain the low level trap calls that
-the evaluator can be configured to make, and the trap and breakpoint
+understand a little about how Guile represent the Scheme control stack.
+With that in place we explain the low level trap calls that the virtual
+machine can be configured to make, and the trap and breakpoint
infrastructure that builds on top of those calls.
@menu
* Evaluation Model:: Evaluation and the Scheme stack.
* Debug on Error:: Debugging when an error occurs.
* Traps::
-* Breakpoints::
* Debugging Examples::
@end menu
@node Evaluation Model
@subsection Evaluation and the Scheme Stack
-The idea of the Scheme stack is central to a lot of debugging. It
-always exists implicitly, as a result of the way that the Guile
-evaluator works, and can be summoned into concrete existence as a
-first-class Scheme value by the @code{make-stack} call, so that an
-introspective Scheme program -- such as a debugger -- can present it in
-some way and allow the user to query its details. The first thing to
-understand, therefore, is how the workings of the evaluator build up the
-stack.
-
-@cindex Evaluations
-@cindex Applications
-Broadly speaking, the evaluator performs @dfn{evaluations} and
-@dfn{applications}. An evaluation means that it is looking at a source
-code expression like @code{(+ x 5)} or @code{(if msg (loop))}, deciding
-whether the top level of the expression is a procedure call, macro,
-builtin syntax, or whatever, and doing some appropriate processing in
-each case. (In the examples here, @code{(+ x 5)} would normally be a
-procedure call, and @code{(if msg (loop))} builtin syntax.) For a
-procedure call, ``appropriate processing'' includes evaluating the
-procedure's arguments, as that must happen before the procedure itself
-can be called. An application means calling a procedure once its
-arguments have been calculated.
-
-@cindex Stack
-@cindex Frames
-@cindex Stack frames
-Typically evaluations and applications alternate with each other, and
-together they form a @dfn{stack} of operations pending completion. This
-is because, on the one hand, evaluation of an expression like @code{(+ x
-5)} requires --- once its arguments have been calculated --- an
-application (in this case, of the procedure @code{+}) before it can
-complete and return a result, and, on the other hand, the application of
-a procedure written in Scheme involves evaluating the sequence of
-expressions that constitute that procedure's code. Each level on this
-stack is called a @dfn{frame}.
+The idea of the Scheme stack is central to a lot of debugging. The
+Scheme stack is a reified representation of the pending function returns
+in an expression's continuation. As Guile implements function calls
+using a stack, this reification takes the form of a number of nested
+stack frames, each of which corresponds to the application of a
+procedure to a set of arguments.
+
+A Scheme stack always exists implicitly, and can be summoned into
+concrete existence as a first-class Scheme value by the
+@code{make-stack} call, so that an introspective Scheme program -- such
+as a debugger -- can present it in some way and allow the user to query
+its details. The first thing to understand, therefore, is how Guile's
+function call convention creates the stack.
+
+Broadly speaking, Guile represents all control flow on a stack. Calling
+a function involves pushing an empty frame on the stack, then evaluating
+the procedure and its arguments, then fixing up the new frame so that it
+points to the old one. Frames on the stack are thus linked together. A
+tail call is the same, except it reuses the existing frame instead of
+pushing on a new one.
+
+In this way, the only frames that are on the stack are ``active''
+frames, frames which need to do some work before the computation is
+complete. On the other hand, a function that has tail-called another
+function will not be on the stack, as it has no work left to do.
Therefore, when an error occurs in a running program, or the program
hits a breakpoint, or in fact at any point that the programmer chooses,
its state at that point can be represented by a @dfn{stack} of all the
-evaluations and procedure applications that are logically in progress at
-that time, each of which is known as a @dfn{frame}. The programmer can
-learn more about the program's state at that point by inspecting the
-stack and its frames.
+procedure applications that are logically in progress at that time, each
+of which is known as a @dfn{frame}. The programmer can learn more about
+the program's state at that point by inspecting the stack and its
+frames.
@menu
* Capturing the Stack or Innermost Stack Frame::
* Examining the Stack::
* Examining Stack Frames::
* Source Properties:: Remembering the source of an expression.
-* Decoding Memoized Source Expressions::
* Starting a New Stack::
@end menu
@lisp
(make-stack #t)
@result{}
-#<stack 805c840:808d250>
+#<stack 25205a0>
@end lisp
@deffn {Scheme Procedure} make-stack obj . args
Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be
-either a debug object or a continuation).
+a continuation or a frame object).
@var{args} should be a list containing any combination of
-integer, procedure and @code{#t} values.
+integer, procedure, prompt tag and @code{#t} values.
These values specify various ways of cutting away uninteresting
stack frames from the top and bottom of the stack that
@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
@var{outer_cut_2} @dots{})}.
-Each @var{inner_cut_N} can be @code{#t}, an integer, or a
-procedure. @code{#t} means to cut away all frames up to but
-excluding the first user module frame. An integer means to cut
-away exactly that number of frames. A procedure means to cut
-away all frames up to but excluding the application frame whose
+Each @var{inner_cut_N} can be @code{#t}, an integer, a prompt
+tag, or a procedure. @code{#t} means to cut away all frames up
+to but excluding the first user module frame. An integer means
+to cut away exactly that number of frames. A prompt tag means
+to cut away all frames that are inside a prompt with the given
+tag. A procedure means to cut away all frames up to but
+excluding the application frame whose procedure matches the
+specified one.
+
+Each @var{outer_cut_N} can be an integer, a prompt tag, or a
+procedure. An integer means to cut away that number of frames.
+A prompt tag means to cut away all frames that are outside a
+prompt with the given tag. A procedure means to cut away
+frames down to but excluding the application frame whose
procedure matches the specified one.
-Each @var{outer_cut_N} can be an integer or a procedure. An
-integer means to cut away that number of frames. A procedure
-means to cut away frames down to but excluding the application
-frame whose procedure matches the specified one.
-
If the @var{outer_cut_N} of the last pair is missing, it is
taken as 0.
@end deffn
-@deffn {Scheme Procedure} last-stack-frame obj
-@deffnx {C Function} scm_last_stack_frame (obj)
-Return the last (innermost) frame of @var{obj}, which must be
-either a debug object or a continuation.
-@end deffn
-
@node Examining the Stack
@subsubsection Examining the Stack
Return @code{#t} if @var{obj} is a stack frame.
@end deffn
-@deffn {Scheme Procedure} frame-number frame
-@deffnx {C Function} scm_frame_number (frame)
-Return the frame number of @var{frame}.
-@end deffn
-
@deffn {Scheme Procedure} frame-previous frame
@deffnx {C Function} scm_frame_previous (frame)
Return the previous frame of @var{frame}, or @code{#f} if
@var{frame} is the first frame in its stack.
@end deffn
-@deffn {Scheme Procedure} frame-next frame
-@deffnx {C Function} scm_frame_next (frame)
-Return the next frame of @var{frame}, or @code{#f} if
-@var{frame} is the last frame in its stack.
-@end deffn
-
-@deffn {Scheme Procedure} frame-source frame
-@deffnx {C Function} scm_frame_source (frame)
-Return the source of @var{frame}.
-@end deffn
-
-@deffn {Scheme Procedure} frame-procedure? frame
-@deffnx {C Function} scm_frame_procedure_p (frame)
-Return @code{#t} if a procedure is associated with @var{frame}.
-@end deffn
-
@deffn {Scheme Procedure} frame-procedure frame
@deffnx {C Function} scm_frame_procedure (frame)
Return the procedure for @var{frame}, or @code{#f} if no
Return the arguments of @var{frame}.
@end deffn
-@deffn {Scheme Procedure} frame-evaluating-args? frame
-@deffnx {C Function} scm_frame_evaluating_args_p (frame)
-Return @code{#t} if @var{frame} contains evaluated arguments.
-@end deffn
-
-@deffn {Scheme Procedure} frame-overflow? frame
-@deffnx {C Function} scm_frame_overflow_p (frame)
-Return @code{#t} if @var{frame} is an overflow frame.
-@end deffn
-
-@deffn {Scheme Procedure} frame-real? frame
-@deffnx {C Function} scm_frame_real_p (frame)
-Return @code{#t} if @var{frame} is a real frame.
-@end deffn
-
@deffn {Scheme Procedure} display-application frame [port [indent]]
@deffnx {C Function} scm_display_application (frame, port, indent)
Display a procedure application @var{frame} to the output port
@cindex source properties
As Guile reads in Scheme code from file or from standard input, it
remembers the file name, line number and column number where each
-expression begins. These pieces of information are known as the
-@dfn{source properties} of the expression. If an expression undergoes
-transformation --- for example, if there is a syntax transformer in
-effect, or the expression is a macro call --- the source properties are
-copied from the untransformed to the transformed expression so that, if
-an error occurs when evaluating the transformed expression, Guile's
-debugger can point back to the file and location where the expression
-originated.
+expression begins. These pieces of information are known as the
+@dfn{source properties} of the expression. Syntax expanders and the
+compiler propagate these source properties to compiled procedures, so
+that, if an error occurs when evaluating the transformed expression,
+Guile's debugger can point back to the file and location where the
+expression originated.
The way that source properties are stored means that Guile can only
associate source properties with parenthesized expressions, and not, for
(where the variable @code{xxx} has not been defined):
@example
-guile> (xxx)
-standard input:2:1: In expression (xxx):
-standard input:2:1: Unbound variable: xxx
-ABORT: (unbound-variable)
-guile> xxx
-<unnamed port>: In expression xxx:
-<unnamed port>: Unbound variable: xxx
-ABORT: (unbound-variable)
+scheme@@(guile-user)> (xxx)
+<unnamed port>:4:1: In procedure module-lookup:
+<unnamed port>:4:1: Unbound variable: xxx
+
+scheme@@(guile-user)> xxx
+ERROR: In procedure module-lookup:
+ERROR: Unbound variable: xxx
@end example
@noindent
-In the latter case, no source properties were stored, so the best that
-Guile could say regarding the location of the problem was ``<unnamed
-port>''.
+In the latter case, no source properties were stored, so the error
+doesn't have any source information.
The recording of source properties is controlled by the read option
-named ``positions'' (@pxref{Reader options}). This option is switched
-@emph{on} by default, together with the debug options ``debug'' and
-``backtrace'' (@pxref{Debugger options}), when Guile is run
-interactively; all these options are @emph{off} by default when Guile
-runs a script non-interactively.
+named ``positions'' (@pxref{Scheme Read}). This option is switched
+@emph{on} by default.
The following procedures can be used to access and set the source
properties of read expressions.
-@deffn {Scheme Procedure} set-source-properties! obj plist
-@deffnx {C Function} scm_set_source_properties_x (obj, plist)
-Install the association list @var{plist} as the source property
+@deffn {Scheme Procedure} set-source-properties! obj alist
+@deffnx {C Function} scm_set_source_properties_x (obj, alist)
+Install the association list @var{alist} as the source property
list for @var{obj}.
@end deffn
@deffn {Scheme Procedure} source-property obj key
@deffnx {C Function} scm_source_property (obj, key)
-Return the source property specified by @var{key} from
-@var{obj}'s source property list.
+Return the property specified by @var{key} from @var{obj}'s source
+properties.
@end deffn
-In practice there are only two ways that you should use the ability to
-set an expression's source breakpoints.
-
-@itemize
-@item
-To set a breakpoint on an expression, use @code{(set-source-property!
-@var{expr} 'breakpoint #t)}. If you do this, you should also set the
-@code{traps} and @code{enter-frame-handler} trap options
-(@pxref{Evaluator trap options}) and @code{breakpoints} debug option
-(@pxref{Debugger options}) appropriately, and the evaluator will then
-call your enter frame handler whenever it is about to evaluate that
-expression.
-
-@item
-To make a read or constructed expression appear to have come from a
-different source than what the expression's source properties already
-say, you can use @code{set-source-property!} to set the expression's
-@code{filename}, @code{line} and @code{column} properties. The
-properties that you set will then show up later if that expression is
-involved in a backtrace or error report.
-@end itemize
-
-If you are looking for a way to attach arbitrary information to an
-expression other than these properties, you should use
-@code{make-object-property} instead (@pxref{Object Properties}), because
-that will avoid bloating the source property hash table, which is really
-only intended for the specific purposes described in this section.
-
+If the @code{positions} reader option is enabled, each parenthesized
+expression will have values set for the @code{filename}, @code{line} and
+@code{column} properties.
-@node Decoding Memoized Source Expressions
-@subsubsection Decoding Memoized Source Expressions
+If you're stuck with defmacros (@pxref{Defmacros}), and want to preserve
+source information, the following helper function might be useful to
+you:
-@deffn {Scheme Procedure} memoized? obj
-@deffnx {C Function} scm_memoized_p (obj)
-Return @code{#t} if @var{obj} is memoized.
-@end deffn
-
-@deffn {Scheme Procedure} unmemoize m
-@deffnx {C Function} scm_unmemoize (m)
-Unmemoize the memoized expression @var{m},
-@end deffn
-
-@deffn {Scheme Procedure} memoized-environment m
-@deffnx {C Function} scm_memoized_environment (m)
-Return the environment of the memoized expression @var{m}.
+@deffn {Scheme Procedure} cons-source xorig x y
+@deffnx {C Function} scm_cons_source (xorig, x, y)
+Create and return a new pair whose car and cdr are @var{x} and @var{y}.
+Any source properties associated with @var{xorig} are also associated
+with the new pair.
@end deffn
the @code{error} or @code{throw} call (or their C code equivalents, if
the error is detected by C code) that signals the error, and is passed
automatically to the handler procedure of the innermost applicable
-@code{catch}, @code{lazy-catch} or @code{with-throw-handler} expression.
+@code{catch} or @code{with-throw-handler} expression.
@subsubsection Intercepting basic error information
Therefore, to catch errors that occur within a chunk of Scheme code, and
to intercept basic information about those errors, you need to execute
-that code inside the dynamic context of a @code{catch},
-@code{lazy-catch} or @code{with-throw-handler} expression, or the
-equivalent in C. In Scheme, this means you need something like this:
+that code inside the dynamic context of a @code{catch} or
+@code{with-throw-handler} expression, or the equivalent in C. In Scheme,
+this means you need something like this:
@lisp
(catch #t
@end lisp
@noindent
-The @code{catch} here can also be @code{lazy-catch} or
-@code{with-throw-handler}; see @ref{Throw Handlers} and @ref{Lazy Catch}
-for the details of how these differ from @code{catch}. The @code{#t}
-means that the catch is applicable to all kinds of error; if you want to
-restrict your catch to just one kind of error, you can put the symbol
-for that kind of error instead of @code{#t}. The equivalent to this in
-C would be something like this:
+The @code{catch} here can also be @code{with-throw-handler}; see @ref{Throw
+Handlers} for information on the when you might want to use
+@code{with-throw-handler} instead of @code{catch}. The @code{#t} means that the
+catch is applicable to all kinds of error; if you want to restrict your catch to
+just one kind of error, you can put the symbol for that kind of error instead of
+@code{#t}. The equivalent to this in C would be something like this:
@lisp
SCM my_body_proc (void *body_data)
@noindent
Again, as with the Scheme version, @code{scm_c_catch} could be replaced
-by @code{scm_internal_lazy_catch} or @code{scm_c_with_throw_handler},
-and @code{SCM_BOOL_T} could instead be the symbol for a particular kind
-of error.
+by @code{scm_c_with_throw_handler}, and @code{SCM_BOOL_T} could instead
+be the symbol for a particular kind of error.
@subsubsection Capturing the full error stack
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 three
+captures and can display this information as well, there are a couple
important things to understand.
-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
+Firstly, 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
@code{make-stack} in the way we are about to describe to capture the
stack when an error occurs.)
-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
-within the handler of a @code{lazy-catch} or @code{with-throw-handler}
-expression, or the optional "pre-unwind" handler of a @code{catch}.
-(For the full story of how these alternatives differ from each other,
-see @ref{Exceptions}. The main difference is that @code{catch}
-terminates the error, whereas @code{lazy-catch} and
-@code{with-throw-handler} only intercept it temporarily and then allow
+And secondly, 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
+within the handler of a @code{with-throw-handler} expression, or the
+optional "pre-unwind" handler of a @code{catch}. (For the full story of
+how these alternatives differ from each other, see @ref{Exceptions}. The
+main difference is that @code{catch} terminates the error, whereas
+@code{with-throw-handler} only intercepts it temporarily and then allow
it to continue propagating up to the next innermost handler.)
So, here are some examples of how to do all this in Scheme and in C.
@subsubsection What the Guile REPL does
-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,
+The Guile REPL code (in @file{system/repl/repl.scm} and related files)
+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.
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.
+Debugging} for more information about this.
@deffn {Scheme Procedure} debug
Invoke the Guile debugger to explore the context of the last error.
@end deffn
+@subsubsection Debug options
+
+The behavior when an error is the @code{backtrace} procedure and of the
+default error handler can be parameterized via the debug options.
+
+@cindex options - debug
+@cindex debug options
+@deffn {Scheme Procedure} debug-options [setting]
+Display the current settings of the debug options. If @var{setting} is
+omitted, only a short form of the current read options is printed.
+Otherwise if @var{setting} is the symbol @code{help}, a complete options
+description is displayed.
+@end deffn
+
+The set of available options, and their default values, may be had by
+invoking @code{debug-options} at the prompt.
+
+@smallexample
+scheme@@(guile-user)>
+backwards no Display backtrace in anti-chronological order.
+width 79 Maximal width of backtrace.
+depth 20 Maximal length of printed backtrace.
+backtrace yes Show backtrace on error.
+stack 1048576 Stack size limit (measured in words;
+ 0 = no check).
+show-file-name #t Show file names and line numbers in backtraces
+ when not `#f'. A value of `base' displays only
+ base names, while `#t' displays full names.
+warn-deprecated no Warn when deprecated features are used.
+@end smallexample
+
+The boolean options may be toggled with @code{debug-enable} and
+@code{debug-disable}. The non-boolean @code{keywords} option must be set
+using @code{debug-set!}.
+
+@deffn {Scheme Procedure} debug-enable option-name
+@deffnx {Scheme Procedure} debug-disable option-name
+@deffnx {Scheme Procedure} debug-set! option-name value
+Modify the debug options. @code{debug-enable} should be used with boolean
+options and switches them on, @code{debug-disable} switches them off.
+@code{debug-set!} can be used to set an option to a specific value.
+@end deffn
+
+@subsubheading Stack overflow
+
+@cindex overflow, stack
+@cindex stack overflow
+Stack overflow errors are caused by a computation trying to use more
+stack space than has been enabled by the @code{stack} option. They are
+reported like this:
+
+@lisp
+(non-tail-recursive-factorial 500)
+@print{}
+ERROR: Stack overflow
+ABORT: (stack-overflow)
+@end lisp
+
+If you get an error like this, you can either try rewriting your code to
+use less stack space, or increase the maximum stack size. To increase
+the maximum stack size, use @code{debug-set!}, for example:
+
+@lisp
+(debug-set! stack 200000)
+@result{}
+(show-file-name #t stack 200000 debug backtrace depth 20
+ maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
+
+(non-tail-recursive-factorial 500)
+@result{}
+122013682599111006870123878542304692625357434@dots{}
+@end lisp
+
+If you prefer to try rewriting your code, you may be able to save stack
+space by making some of your procedures @dfn{tail recursive}
+(@pxref{Tail Calls}).
+
@node Traps
@subsection Traps
@cindex Tracing
@cindex Code coverage
@cindex Profiling
-The low level C code of Guile's evaluator can be configured to call
-out at key points to arbitrary user-specified procedures. These
-procedures, and the circumstances under which the evaluator calls
-them, are configured by the ``evaluator trap options'' interface
-(@pxref{Evaluator trap options}), and by the @code{trace} and
-@code{breakpoints} fields of the ``debug options'' interface
-(@pxref{Debugger options}). In principle this allows Scheme code to
-implement any model it chooses for examining the evaluation stack as
-program execution proceeds, and for suspending execution to be resumed
-later. Possible applications of this feature include breakpoints,
-runtime tracing, code coverage, and profiling.
+Guile's virtual machine can be configured to call out at key points to
+arbitrary user-specified procedures. For more information on these
+hooks, and the circumstances under which the VM calls them, see @ref{VM
+Behaviour}.
+
+In principle, these hooks allow Scheme code to implement any model it
+chooses for examining the evaluation stack as program execution
+proceeds, and for suspending execution to be resumed later. Possible
+applications of this feature include breakpoints, runtime tracing, code
+coverage, and profiling.
@cindex Trap classes
@cindex Trap objects
understanding how the interface hangs together.
+@subsubsection Actually, this section is bitrotten
+
+Dear reader: the following sections have some great ideas, and some code
+that just needs a few days of massaging to get it to work with the VM
+(as opposed to the old interpreter). Want to help? Yes? Yes!
+@code{guile-devel@@gnu.org}, that's where.
+
+
@subsubsection A Quick Note on Terminology
@cindex Trap terminology
@end deffn
-@node Breakpoints
-@subsection Breakpoints
-
-While they are an important piece of infrastructure, and directly
-usable in some scenarios, traps are still too low level to meet some
-of the requirements of interactive development.
-
-A common scenario is that a newly written procedure is not working
-properly, and so you'd like to be able to step or trace through its
-code to find out why. Ideally this should be possible from the IDE
-and without having to modify the source code. There are two problems
-with using traps directly in this scenario.
-
-@enumerate
-@item
-They are too detailed: constructing and installing a trap requires you
-to say what kind of trap you want and to specify fairly low level
-options for it, whereas what you really want is just to say ``break
-here using the most efficient means possible.''
-
-@item
-The most efficient kinds of trap --- that is, @code{<procedure-trap>}
-and @code{<source-trap>} --- can only be specified and installed
-@emph{after} the code that they refer to has been loaded. This is an
-inconvenient detail for the user to deal with, and in some
-applications it might be very difficult to insert an instruction to
-install the required trap in between when the code is loaded and when
-the procedure concerned is first called. It would be better to be
-able to tell Guile about the requirement upfront, and for it to deal
-with installing the trap when possible.
-@end enumerate
-
-We solve these problems by introducing breakpoints. A breakpoint is
-something which says ``I want to break at location X, or in procedure
-P --- just make it happen'', and can be set regardless of whether the
-relevant code has already been loaded. Breakpoints use traps to do
-their work, but that is a detail that the user will usually not have
-to care about.
-
-Breakpoints are provided by a combination of Scheme code in the client
-program, and facilities for setting and managing breakpoints in the
-GDS front end. On the Scheme side the entry points are as follows.
-
-@deffn {Getter with Setter} default-breakpoint-behaviour
-A ``getter with setter'' procedure that can be used to get or set the
-default behaviour for new breakpoints. When a new default behaviour
-is set, by calling
-
-@lisp
-(set! (default-breakpoint-behaviour) @var{new-behaviour})
-@end lisp
-
-@noindent
-the new behaviour applies to all following @code{break-in} and
-@code{break-at} calls, but does not affect breakpoints which have
-already been set. @var{new-behaviour} should be a behaviour procedure
-with the signature
-
-@lisp
-(lambda (trap-context) @dots{})
-@end lisp
-
-@noindent
-as described in @ref{Specifying Trap Behaviour}.
-@end deffn
-
-@deffn {Procedure} break-in procedure-name [module-or-file-name] [options]
-Set a breakpoint on entry to the procedure named @var{procedure-name},
-which should be a symbol. @var{module-or-file-name}, if present, is
-the name of the module (a list of symbols) or file (a string) which
-includes the target procedure. If @var{module-or-file-name} is
-absent, the target procedure is assumed to be in the current module.
-
-The available options are any of the common trap options
-(@pxref{Common Trap Options}), and are used when creating the
-breakpoint's underlying traps. The default breakpoint behaviour
-(given earlier to @code{default-breakpoint-behaviour}) is only used if
-these options do not include @code{#:behaviour @var{behaviour}}.
-@end deffn
-
-@deffn {Procedure} break-at file-name line column [options]
-Set a breakpoint on the expression in file @var{file-name} whose
-opening parenthesis is on line @var{line} at column @var{column}.
-@var{line} and @var{column} both count from 0 (not from 1).
-
-The available options are any of the common trap options
-(@pxref{Common Trap Options}), and are used when creating the
-breakpoint's underlying traps. The default breakpoint behaviour
-(given earlier to @code{default-breakpoint-behaviour}) is only used if
-these options do not include @code{#:behaviour @var{behaviour}}.
-@end deffn
-
-@deffn {Procedure} set-gds-breakpoints
-Ask the GDS front end for a list of breakpoints to set, and set these
-using @code{break-in} and @code{break-at} as appropriate.
-@end deffn
-
-@code{default-breakpoint-behaviour}, @code{break-in} and
-@code{break-at} allow an application's startup code to specify any
-breakpoints that it needs inline in that code. For example, to trace
-calls and arguments to a group of procedures to handle HTTP requests,
-one might write something like this:
-
-@lisp
-(use-modules (ice-9 debugging breakpoints)
- (ice-9 debugging trace))
-
-(set! (default-breakpoint-behaviour) trace-trap)
-
-(break-in 'handle-http-request '(web http))
-(break-in 'read-http-request '(web http))
-(break-in 'decode-form-data '(web http))
-(break-in 'send-http-response '(web http))
-@end lisp
-
-@code{set-gds-breakpoints} can be used as well as or instead of the
-above, and is intended to be the most practical option if you are
-using GDS. The idea is that you only need to add this one call
-somewhere in your application's startup code, like this:
-
-@lisp
-(use-modules (ice-9 gds-client))
-(set-gds-breakpoints)
-@end lisp
-
-@noindent
-and then all the details of the breakpoints that you want to set can
-be managed through GDS. For the details of GDS's breakpoints
-interface, see @ref{Setting and Managing Breakpoints}.
-
-
@node Debugging Examples
@subsection Debugging Examples
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 debugging ice-9-debugger-extensions)}.
+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
@lisp
$ /usr/bin/guile -q
guile> (use-modules (ice-9 debugger)
- (ice-9 debugging ice-9-debugger-extensions)
(ice-9 debugging traps))
guile> (load "matrix.scm")
guile> (install-trap (make <procedure-trap>
[mkmatrix]
debug> next
Frame 3 at matrix.scm:4:3
- (let ((x 1)) (quote this-is-a-matric))
+ (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 this-is-a-matric))
+ (let ((x 1)) (quote hi!))
debug> next
Frame 3 at matrix.scm:5:21
- (quote this-is-a-matric)
+ (quote hi!)
debug> bt
In unknown file:
?: 0* [primitive-eval (do-main 4)]
In matrix.scm:
8: 2 [mkmatrix]
...
- 5: 3 (quote this-is-a-matric)
+ 5: 3 (quote hi!)
debug> quit
-this-is-a-matric
+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
-@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.
+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
| 5: (memq sym bindings)
| 5: [memq let (debug)]
| 5: =>#f
-| 2: (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric)))
+| 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
-| 2: (let ((x 1)) (quote this-is-a-matric))
+| 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: =>#f
| 2: [let (let # #) (# # #)]
| 2: [let (let # #) (# # #)]
-| 2: =>(#@@let* (x 1) #@@let (quote this-is-a-matric))
-this-is-a-matric
+| 2: =>(#@@let* (x 1) #@@let (quote hi!))
+hi!
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
+| 2: (letrec ((yy 23)) (let* ((x 1)) (quote hi!)))
+| 2: (let* ((x 1)) (quote hi!))
+| 2: (quote hi!)
+| 2: =>hi!
+hi!
guile>
@end 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:4: (quote this-is-a-matric)
-| matrix.scm:4:4: =>this-is-a-matric
-this-is-a-matric
+| : (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
-(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.)
-
-
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
HCoop / bpt / guile.git / blobdiff