summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-using.texi
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2006-10-10 21:52:40 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2006-10-10 21:52:40 +0000
commitc1ab3a6d6b490c73740419326b4e2b35f64cc0a3 (patch)
tree82e6ec3e6599b3829ceeba9ef897b6e85f9545b5 /doc/ref/scheme-using.texi
parentbdb55624ca1fb984aa6b74ac6bdc384186a60e37 (diff)
downloadguile-c1ab3a6d6b490c73740419326b4e2b35f64cc0a3.tar.gz
(Setting and Managing Breakpoints): New text
about what happens when a breakpoint is created. (Listing and Deleting Breakpoints, Moving and Losing Breakpoints): New.
Diffstat (limited to 'doc/ref/scheme-using.texi')
-rw-r--r--doc/ref/scheme-using.texi74
1 files changed, 51 insertions, 23 deletions
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index 445c8f32d..93d0949f8 100644
--- a/doc/ref/scheme-using.texi
+++ b/doc/ref/scheme-using.texi
@@ -827,6 +827,8 @@ GDS provides for working on code in @code{scheme-mode} buffers.
@menu
* Access to Guile Help and Completion::
* Setting and Managing Breakpoints::
+* Listing and Deleting Breakpoints::
+* Moving and Losing Breakpoints::
* Evaluating Scheme Code::
@end menu
@@ -902,29 +904,55 @@ default by using the alternative key sequences @kbd{C-c C-b d} (for
@code{debug}), @kbd{C-c C-b t} (for @code{trace}) and @kbd{C-c C-b T}
(for @code{trace-subtree}).
-When you create a breakpoint like this, two things happen. Firstly,
-if the current buffer is associated with a Guile client program, the
-new breakpoint definition is immediately sent to that client (or, if
-the client cannot accept input immediately, it is held in readiness to
-pass to the client at the next possible opportunity). This allows the
-new breakpoint to take effect as soon as possible in the relevant
-client program.
-
-Secondly, it is added to GDS's @emph{global} list of all breakpoints.
-This list holds the breakpoint information that will be given to any
-client program that asks for it by calling @code{set-gds-breakpoints}.
-The fact that this list is global, rather than client-specific, means
-that the breakpoints you have set will automatically be recreated if the
-program you are debugging has to be stopped and restarted.@footnote{An
-important point here is that there is nothing that unambiguously relates
-two subsequent runs of the same client program, which might allow GDS to
-pass on breakpoint settings more precisely.}
-
-(The only possible downside of this last point is that if you are
-debugging two programs in parallel, which have some code in common,
-you might not want a common code breakpoint in one program to be set
-in the other program as well. But this feels like a small concern in
-comparison to the benefit of breakpoints persisting as just described.)
+GDS keeps all the breakpoints that you create in a single list, and
+tries to set them in every Guile program that connects to GDS and calls
+@code{set-gds-breakpoints}. That may sound surprising, because you are
+probably thinking of one particular program when you create a
+breakpoint; but GDS assumes that you would want the breakpoint to continue
+taking effect if you stop and restart that program, and this is
+currently achieved by giving all breakpoints to every program that asks
+for them. In practice it doesn't matter if a program gets a breakpoint
+definition --- such as ``break in procedure @code{foo}'' --- that it
+can't actually map to any of its code.
+
+If there are already Guile programs connected to GDS when you create a
+new breakpoint, GDS also tries to set the new breakpoint in each of
+those programs at the earliest opportunity, which is usually when they
+decide to stop and talk to GDS for some other reason.
+
+
+@node Listing and Deleting Breakpoints
+@subsubsection Listing and Deleting Breakpoints
+
+To see a list of all breakpoints, type @kbd{C-c C-b ?} (or @kbd{M-x
+gds-describe-breakpoints}). GDS will then pop up a buffer that
+describes each breakpoint and reports whether it is actually set in each
+of the Guile programs connected to GDS.
+
+To delete a breakpoint, type @kbd{C-c C-b @key{backspace}}. If the
+region is active when you do this, GDS will delete all of the
+breakpoints in the region. If the region is not active, GDS tries to
+delete a ``break-in'' breakpoint for the procedure whose definition
+contains point (the Emacs cursor). In either case, deletion means that
+the breakpoint is removed both from GDS's global list and from all of
+the connected Guile programs that had previously managed to set it.
+
+
+@node Moving and Losing Breakpoints
+@subsubsection Moving and Losing Breakpoints
+
+Imagine that you set a breakpoint at line 80 of a Scheme code file, and
+execute some code that hits this breakpoint; then you add some new code
+at line 40, or delete some code that is no longer needed, and save the
+file. Now the breakpoint will have moved up or down from line 80, and
+any attached Guile program needs to be told about the new line number.
+Otherwise, when a program loads this file again, it will try incorrectly
+to set a breakpoint on whatever code is now at line 80, and will
+@emph{not} set a breakpoint on the code where you want it.
+
+For this reason, GDS checks all breakpoint positions whenever you save a
+Scheme file, and sends the new position to connected Guile programs for
+any breakpoints that have moved. @dots{} [to be continued]
@node Evaluating Scheme Code