summaryrefslogtreecommitdiff
path: root/doc/ref/api-debug.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r--doc/ref/api-debug.texi134
1 files changed, 1 insertions, 133 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index d99a56724..0d4398015 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -1,6 +1,6 @@
@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
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -19,7 +19,6 @@ infrastructure that builds on top of those calls.
* Evaluation Model:: Evaluation and the Scheme stack.
* Debug on Error:: Debugging when an error occurs.
* Traps::
-* Breakpoints::
* Debugging Examples::
@end menu
@@ -1691,137 +1690,6 @@ if there isn't one.
@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