levels of information about what the error was and exactly where it
occurred.
-By default, Guile then displays only the first level, which is the most
+By default, Guile displays only the first level, which is the most
immediate information about where and why the error occurred, for
example:
standard input:2:19: Wrong type argument: #\s
ABORT: (wrong-type-arg)
-Type "(backtrace)" to get more information or "(debug)" to enter the debugger.
+Type "(backtrace)" to get more information
+or "(debug)" to enter the debugger.
@end lisp
@noindent
@end itemize
@noindent
-This is documented further in the following section.
+The interactive debugger is documented further in the following section.
@node Interactive Debugger
@noindent
``debug>'' is the debugger's prompt, and a reminder that you are not in
-the normal Guile REPL. The available commands are described in the
-following subsections.
+the normal Guile REPL. In case you find yourself in the debugger by
+mistake, the @code{quit} command will return you to the REPL.
+
+@deffn {Debugger Command} quit
+Exit the debugger.
+@end deffn
+
+The other available commands are described in the following subsections.
@menu
* Display Backtrace:: backtrace.
* Frame Selection:: up, down, frame.
* Frame Information:: info args, info frame, position.
* Frame Evaluation:: evaluate.
-* Single Stepping:: step, next.
-* Run To Frame Exit:: finish, trace-finish.
-* Continue Execution:: continue.
-* Leave Debugger:: quit.
+* Stepping and Continuing:: step, next, (trace-)finish, continue.
@end menu
@end deffn
The format of the displayed backtrace is the same as for the
-@code{backtrace} procedure.
+@code{display-backtrace} procedure (@pxref{Examining the Stack}).
@node Frame Selection
@deffn {Debugger Command} up [n]
Move @var{n} frames up the stack. For positive @var{n}, this
-advances toward the outermost frame, to higher frame numbers, to
+advances toward the outermost frame, to lower frame numbers, to
frames that have existed longer. @var{n} defaults to one.
@end deffn
@deffn {Debugger Command} down [n]
Move @var{n} frames down the stack. For positive @var{n}, this
-advances toward the innermost frame, to lower frame numbers, to frames
+advances toward the innermost frame, to higher frame numbers, to frames
that were created more recently. @var{n} defaults to one.
@end deffn
@node Frame Information
@subsubsection Frame Information
-[to be completed]
+The following commands return detailed information about the currently
+selected frame.
@deffn {Debugger Command} {info frame}
-All about selected stack frame.
+Display a verbose description of the selected frame. The information
+that this command provides is equivalent to what can be deduced from the
+one line summary for the frame that appears in a backtrace, but is
+presented and explained more clearly.
@end deffn
@deffn {Debugger Command} {info args}
-Argument variables of current stack frame.
+Display the argument variables of the current stack frame. Arguments
+can also be seen in the backtrace, but are presented more clearly by
+this command.
@end deffn
@deffn {Debugger Command} position
-Display the position of the current expression.
+Display the name of the source file that the current expression comes
+from, and the line and column number of the expression's opening
+parenthesis within that file. This information is only available when
+the @code{positions} read option is enabled (@pxref{Reader options}).
@end deffn
@node Frame Evaluation
@subsubsection Frame Evaluation
-[to be completed]
+The @code{evaluate} command is most useful for querying the value of a
+variable, either global or local, in the environment of the selected
+stack frame, but it can be used more generally to evaluate any
+expression.
@deffn {Debugger Command} evaluate expression
-Evaluate an expression.
-The expression must appear on the same line as the command,
-however it may be continued over multiple lines.
+Evaluate an expression in the environment of the selected stack frame.
+The expression must appear on the same line as the command, however it
+may be continued over multiple lines.
@end deffn
-@node Single Stepping
-@subsubsection Single Stepping
+@node Stepping and Continuing
+@subsubsection Single Stepping and Continuing Execution
-[to be completed]
+The commands in this subsection all apply only when the stack is
+@dfn{continuable} --- in other words when it makes sense for the program
+that the stack comes from to continue running. Usually this means that
+the program stopped because of a trap or a breakpoint.
@deffn {Debugger Command} step [n]
-Tell the debugged program to do @var{n} single-steps to the next frame
-entry or exit of any kind. @var{n} defaults to 1.
+Tell the debugged program to do @var{n} more steps from its current
+position. One @dfn{step} means executing until the next frame entry or
+exit of any kind. @var{n} defaults to 1.
@end deffn
@deffn {Debugger Command} next [n]
-Tell the debugged program to do @var{n} single-steps to the entry or
-exit of a frame whose code comes from the same source file as the
-selected stack frame. (See @ref{Step Traps} for the details of how
-this works.) If the selected stack frame has no source, the effect of
-this command is the same as of @code{step}. @var{n} defaults to 1.
+Tell the debugged program to do @var{n} more steps from its current
+position, but only counting frame entries and exits where the
+corresponding source code comes from the same file as the current stack
+frame. (See @ref{Step Traps} for the details of how this works.) If
+the current stack frame has no source code, the effect of this command
+is the same as of @code{step}. @var{n} defaults to 1.
@end deffn
-
-@node Run To Frame Exit
-@subsubsection Run To Frame Exit
-
-[to be completed]
-
@deffn {Debugger Command} finish
-Tell the program being debugged to continue running until the
-completion of the selected stack frame, and at that time to print the
-result and reenter the command line debugger.
+Tell the program being debugged to continue running until the completion
+of the current stack frame, and at that time to print the result and
+reenter the command line debugger.
@end deffn
-@deffn {Debugger Command} trace-finish
-Trace until evaluation of the current frame is complete.
-@end deffn
-
-
-@node Continue Execution
-@subsubsection Continue Execution
-
-[to be completed]
-
@deffn {Debugger Command} continue
-Tell the program being debugged to continue running.
+Tell the program being debugged to continue running. (In fact this is
+the same as the @code{quit} command, because it exits the debugger
+command loop and so allows whatever code it was that invoked the
+debugger to continue.)
@end deffn
-@node Leave Debugger
-@subsubsection Leave Debugger
+@node Using Guile in Emacs
+@section Using Guile in Emacs
-[to be completed]
+There are quite a few options for working on Guile Scheme code in
+Emacs. The simplest options are to use Emacs's standard
+@code{scheme-mode} for editing code, and to run the interpreter when you
+need it by typing ``guile'' at the prompt of a @code{*shell*} buffer,
+but there are Emacs libraries available which add various bells and
+whistles to this. The following diagram shows these libraries and how
+they relate to each other, with the arrows indicating ``builds on'' or
+``extends''. For example, the Quack library builds on cmuscheme, which
+in turn builds on the standard scheme mode.
-@deffn {Debugger Command} quit
-Exit the debugger.
-@end deffn
+@example
+ scheme
+ ^
+ |
+ .-----+-----.
+ | |
+ cmuscheme xscheme
+ ^
+ |
+ .-----+-----.
+ | |
+ Quack GDS
+@end example
+@dfn{scheme}, written by Bill Rozas and Dave Love, is Emacs's standard
+mode for Scheme code files. It provides Scheme-sensitive syntax
+highlighting, parenthesis matching, indentation and so on.
+
+@dfn{cmuscheme}, written by Olin Shivers, provides a comint-based Scheme
+interaction buffer, so that you can run an interpreter more directly
+than with the @code{*shell*} buffer approach by typing @kbd{M-x
+run-scheme}. It also extends @code{scheme-mode} so that there are key
+presses for sending selected bits of code from a Scheme buffer to this
+interpreter. This means that when you are writing some code and want to
+check what an expression evaluates to, you can easily select that code
+and send it to the interpreter for evaluation, then switch to the
+interpreter to see what the result is. cmuscheme is included in the
+standard Emacs distribution.
+
+@dfn{Quack}, written by Neil Van Dyke, adds a number of incremental
+improvements to the scheme/cmuscheme combination: convenient menu
+entries for looking up Scheme-related references (such as the SRFIs);
+enhanced indentation rules that are customized for particular Scheme
+interpreters, including Guile; an enhanced version of the
+@code{run-scheme} command that knows the names of the common Scheme
+interpreters and remembers which one you used last time; and so on.
+Quack is available from @uref{http://www.neilvandyke.org/quack}.
+
+@dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme
+combination, but with a fundamental change to the way that Scheme code
+fragments are sent to the interpreter for evaluation. cmuscheme and
+Quack send code fragments to the interpreter's standard input, on the
+assumption that the interpreter is expecting to read Scheme expressions
+there, and then monitor the interpreter's standard output to infer what
+the result of the evaluation is. GDS doesn't use standard input and
+output like this. Instead, it sets up a socket connection between the
+Scheme interpreter and Emacs, and sends and receives messages using a
+simple protocol through this socket. The messages include requests to
+evaluate Scheme code, and responses conveying the results of an
+evaluation, thus providing similar function to cmuscheme or Quack. They
+also include requests for setting breakpoints, stack exploration and
+debugging, which go beyond what cmuscheme or Quack can do. The price of
+this extra power, however, is that GDS is Guile-specific. GDS requires
+the Scheme interpreter, or any program that GDS is debugging, to run
+some GDS-specific library code; currently this code is written as a
+Guile module and uses a lot of debugging-related features that are
+specific to Guile. GDS is now included in the Guile distribution; for
+previous Guile releases (1.8.x and earlier) it can be obtained as part
+of the @code{guile-debugging} package from
+@uref{http://www.ossau.uklinux.net/guile}.
+
+Finally, @dfn{xscheme} is similar to cmuscheme --- in that it starts up
+a Scheme interaction process and sends commands to that process's
+standard input --- and to GDS --- in that it has support beyond
+cmuscheme or Quack for exploring the Scheme stack when an error has
+occurred --- but is implemented specifically for MIT/GNU Scheme. Hence
+it isn't really relevant to Guile work in Emacs, except as a reference
+for useful features that could be implemented in one of the other
+libraries mentioned here.
+
+In summary, the best current choice for working on Guile code in Emacs
+is either Quack or GDS, depending on which of these libraries' features
+you find most important. For more information on Quack, please see the
+website referenced above. GDS is documented further in the rest of this
+section.
+
+@menu
+* GDS Introduction::
+* GDS Architecture::
+* GDS Getting Started::
+* Working with GDS in Scheme Buffers::
+* Displaying the Scheme Stack::
+* Continuing Execution::
+* Associating Buffers with Clients::
+* An Example GDS Session::
+@end menu
-@node Using Guile in Emacs
-@section Using Guile in Emacs
-The Guile distribution includes a rich environment for working on Guile
-Scheme code within Emacs. The idea of this environment is to allow you
-to work on Guile Scheme code in the same kind of way that Emacs allows
-you to work on Emacs Lisp code: providing easy access to help,
-evaluating arbitrary fragments of code, a nice debugging interface, and
-so on.@footnote{You can also, of course, run a Guile session in Emacs
-simply by typing ``guile'' in a @code{*shell*} buffer. The environment
-described here provides a much better integration than that, though.}
+@node GDS Introduction
+@subsection GDS Introduction
-The thinking behind this environment is that you will usually be doing
-one of two things.
+GDS aims to allow you to work on Guile Scheme code in the same kind of
+way that Emacs allows you to work on Emacs Lisp code: providing easy
+access to help, evaluating arbitrary fragments of code, a nice debugging
+interface, and so on. The thinking behind the GDS library is that you
+will usually be doing one of two things.
@enumerate
@item
-Writing or editing code. The code will be in a normal Emacs Scheme
-mode buffer, and the Guile/Emacs environment extends Scheme mode to
-add keystrokes and menu items for the things that are likely to be
-useful to you when working on code:
+Writing or editing code. The code will be in a normal Emacs Scheme mode
+buffer, and GDS extends Scheme mode to add keystrokes and menu items for
+the things that are likely to be useful to you when working on code:
@itemize
@item
-completing the identifier at point
+completing the identifier at point, with respect to the set of variable
+names that are known to the associated Guile process
@item
-accessing Guile's built in help
+accessing Guile's built in ``help'' and ``apropos'' commands
@item
-evaluating fragments of code to check what they do.
+evaluating fragments of code to check what they do, with the results
+popping up in a temporary Emacs window.
@end itemize
@item
-Debugging a Guile Scheme program. When your program hits an error or
-a breakpoint, the Guile/Emacs environment shows you the relevant code
-and the Scheme stack, and makes it easy to
+Debugging a Guile Scheme program. When your program hits an error or a
+breakpoint, GDS shows you the relevant code and the Scheme stack, and
+makes it easy to
@itemize
@item
@item
see what is happening at all levels of the Scheme stack
@item
+set new breakpoints (by simply typing @kbd{C-x @key{SPC}}) or modify
+existing ones
+@item
continue execution, either normally or step by step.
@end itemize
+
+The presentation makes it very easy to move up and down the stack,
+showing whenever possible the source code for each frame in another
+Emacs buffer. It also provides convenient keystrokes for telling Guile
+what to do next; for example, you can select a stack frame and tell
+Guile to run until that frame completes, at which point GDS will display
+the frame's return value.
@end enumerate
-Combinations of these work well too. You can evaluate a fragment of
-code (in a Scheme buffer) that contains a breakpoint, then use the
-debugging interface to step through the code at the breakpoint. You
-can also run a program until it hits a breakpoint, then examine,
-modify and reevaluate some of the relevant code, and then tell the
-program to continue running.
+Combinations of these well too. You can evaluate a fragment of code (in
+a Scheme buffer) that contains a breakpoint, then use the debugging
+interface to step through the code at the breakpoint. You can also run
+a program until it hits a breakpoint, then examine, modify and
+reevaluate some of the relevant code, and then tell the program to
+continue running.
+
+GDS can provide these facilities for any number of Guile Scheme programs
+(which we often refer to as ``clients'') at once, and these programs can
+be started either independently of GDS, including outside Emacs, or
+specifically @emph{by} GDS.
-GDS is a user interface for working on Guile Scheme programs in Emacs.
-It aims to provide whatever facilities are needed to make the writing,
-debugging and maintenance of Scheme code in Emacs as fluid and
-productive as possible. These facilities currently include the
-following.
+Communication between each Guile client program and GDS uses a TCP
+socket, which means that it is orthogonal to any other interfaces that
+the client program has. In particular GDS does not interfere with a
+program's standard input and output.
-@table @asis
-@item Displaying the Scheme stack
-When running Scheme code hits a trap or throws an exception, GDS can
-display the stack at the point of the trap or exception. The
-presentation makes it very easy to move up and down the stack, showing
-whenever possible the source code for each frame in another Emacs
-buffer, and allowing you to evaluate test expressions in the context of
-the selected frame.
-
-@item Continuing execution from a trap
-When GDS is showing the stack for code that has hit a trap, it also
-allows you to control how execution continues from that point. For
-example you can select a stack frame and tell Guile to run until that
-frame completes, at which point GDS will display the frame's return
-value.
-
-@item Evaluating Scheme code
-GDS allows you to select a region of a Scheme buffer and send it to
-Guile for evaluation, or to enter a Scheme expression to be evaluated in
-the Emacs minibuffer. In both cases the evaluation results are popped
-up in a temporary Emacs window.
-
-@item Setting breakpoints in Scheme code
-GDS makes it easy to set breakpoints in Scheme code from within Emacs.
-Deep down this uses the traps described in previous chapters, but GDS
-makes the practicalities as simple as typing @kbd{C-x @key{SPC}}. When
-a GDS breakpoint is hit, the stack at that point is popped up in Emacs.
-GDS also remembers your breakpoints between editing sessions, so you
-don't have to set them again when you visit the relevant files.
-
-@item Access to Guile's built in help system
-GDS makes it easy to query Guile's ``help'' and ``apropos'' commands,
-and pops up the results in a temporary Emacs window.
-
-@item Symbol completion
-GDS provides a keystroke which tries to complete a partially entered
-symbol by asking Guile to match it against all the accessible bindings.
-@end table
-(For a hands-on, tutorial introduction to using GDS, use Emacs to open
-the file @file{gds-tutorial.txt}, which is included with the
-guile-debugging distribution, and then follow the steps in that file.)
+@node GDS Architecture
+@subsection GDS Architecture
-GDS can provide these facilities for any number of Guile Scheme programs
-(which we often call ``clients'') at once, and these programs can be
-started either completely independently of GDS, including outside Emacs,
-or specifically @emph{by} GDS. The two common cases are:
+In order to understand the following documentation fully it will help to
+have a picture in mind of how GDS works, so we briefly describe that
+here. GDS consists of three components.
@itemize
@item
-a Guile application, such as @uref{http://www.gnucash.org, GnuCash},
-which is started from your desktop, and which connects to GDS as a
-result of some incantation added to its startup code
+The GDS @dfn{interface} code is written in Emacs Lisp and runs inside
+Emacs. This code, consisting of the installed files @file{gds.el} and
+@file{gds-server.el}, is responsible for displaying information from
+Guile in Emacs windows, and for responding to Emacs commands and
+keystrokes by sending instructions back to the Guile program being
+debugged.
+
+@item
+The GDS @dfn{server} code is written in Scheme and runs as an Emacs
+inferior process. It acts as a multiplexer between the (possibly
+multiple) Guile programs being debugged and the interface code running
+in Emacs. The server code is the installed file
+@file{gds-server.scm}.
@item
-a ``utility'' Guile process which is run by GDS to provide help,
-completion and evaluation for Scheme code that you are working on in
-Emacs.
+The GDS @dfn{client} code is written in Scheme (installed file
+@file{gds-client.scm}), and must be loaded as a module by each Guile
+program that wants to use GDS in any way.
@end itemize
@noindent
-The user experience --- in other words the ways that the GDS front end
-allows you to interact with the client --- is much the same in all
-cases.
-
-Communication between the Guile client program and GDS uses a TCP
-socket, which means that it is orthogonal to any other interfaces that
-the client program has. In particular GDS does not interfere with a
-program's standard input and output.
+The following diagram shows how these components are connected to each
+other.
-@menu
-* GDS Setup::
-* How To Use GDS::
-* Displaying the Scheme Stack::
-* Continuing Execution::
-* Evaluating Scheme Code::
-* Setting and Managing Breakpoints::
-* Access to Guile Help and Completion::
-* Associating Buffers with Clients::
-* An Example GDS Session::
-* GDS Architecture::
-@end menu
+@example
++----------------+
+| Program #1 |
+| |
+| +------------+ |
+| | GDS Client |-_
+| +------------+ |-_ +-------------------+
++----------------+ -_TCP | Emacs |
+ -_ | |
+ -_+------------+ | +---------------+ |
+ _| GDS Server |-----| GDS Interface | |
++----------------+ _- +------------+ | +---------------+ |
+| Program #2 | _- +-------------------+
+| | _- TCP
+| +------------+ _-
+| | GDS Client |-|
+| +------------+ |
++----------------+
+@end example
+@cindex TCP, use of
+The data exchanged between client and server components, and between
+server and interface, is a sequence of sexps (parenthesised expressions)
+that are designed so as to be directly readable by both Scheme and Emacs
+Lisp. The use of a TCP connection means that the server and Emacs
+interface can theoretically be on a different computer from the programs
+being debugged, but in practice there are currently two problems with
+this. Firstly the GDS API doesn't provide any way of specifying a
+non-local server to connect to, and secondly there is no security or
+authentication mechanism in the GDS protocol. These are issues that
+should be addressed in the near future.
-@node GDS Setup
-@subsection GDS Setup
+
+@node GDS Getting Started
+@subsection Getting Started with GDS
-GDS's Scheme and Emacs Lisp files will have been installed in
-the correct places system-wide when the @code{guile-debugging} package
-as a whole was installed. To enable the use of GDS in your own Emacs
-sessions, simply add
+To enable the use of GDS in your own Emacs sessions, simply add
@lisp
(require 'gds)
@end lisp
@noindent
-somewhere in your @file{.emacs} file.
+somewhere in your @file{.emacs} file. This will cause Emacs to load the
+GDS Emacs Lisp code when starting up, and to start the inferior GDS
+server process so that it is ready and waiting for any Guile programs
+that want to use GDS.
+(If GDS's Scheme code is not installed in one of the locations in
+Guile's load path, you may find that the server process fails to start.
+When this happens you will see an error message from Emacs:
-@node How To Use GDS
-@subsection How To Use GDS
+@lisp
+error in process filter: Wrong type argument: listp, Backtrace:
+@end lisp
-There are lots of ways to use GDS, but they boil down to two overall
-approaches.
+@noindent
+and the @code{gds-debug} buffer will contain a Scheme backtrace ending
+with the message:
-@enumerate
-@item
-When you are writing Scheme code in Emacs, you can use GDS while you are
-writing to help with things like name completion, looking up help, and
-evaluating fragments of code to check that they do what you expect.
-
-The first time you do something that needs a running Guile process, GDS
-will automatically create one as an Emacs subprocess. This Guile
-program does nothing but wait for and act on instructions from GDS, and
-we refer to it as a @dfn{utility} Guile client.
-
-Over time this utility Guile will accumulate the code that you ask it to
-evaluate, and you can also tell it to load complete files or modules by
-sending it @code{load} or @code{use-modules} expressions. You can set
-breakpoints and evaluate code which hits those breakpoints, and GDS will
-pop up the stack at the breakpoint so you can explore your code by
-single-stepping and evaluating test expressions.
+@lisp
+no code for module (ossau gds-server)
+@end lisp
-@item
-Alternatively, you can use GDS to explore and debug a Guile program or
-script which is started independently of GDS. This could be a script
-that you invoke from the command line, or a graphical Guile-using
-application which is launched from your desktop's start menu.
-
-In this case the program has to put something in its startup code to
-cause it to connect to GDS at some point: either immediately during the
-startup processing, or later when an error occurs or a trap is hit.
-Several possibilities for this are described below.
-
-Under certain conditions, then, the program will stop, pass its current
-Scheme stack to GDS, and then wait for instruction before continuing
-execution. At such points you can use GDS to explore the stack,
-obviously, but also to set or delete other breakpoints, modify the
-program's code (by editing and then reevaluating it from Emacs), and use
-the help and completion facilities, before eventually telling the
-program to single-step or to continue running normally.
-@end enumerate
+@noindent
+The solution for this is to customize the Emacs variable
+@code{gds-scheme-directory} so that it specifies where the GDS Scheme
+code is installed. Then either restart Emacs or type @kbd{M-x
+gds-run-debug-server} to try starting the GDS server process again.)
+
+For evaluations, help and completion from Scheme code buffers that you
+are working on, this is all you need. The first time you do any of
+these things, GDS will automatically start a new Guile client program as
+an Emacs subprocess. This Guile program does nothing but wait for and
+act on instructions from GDS, and we refer to it as a @dfn{utility}
+Guile client. Over time this utility client will accumulate the code
+that you ask it to evaluate, and you can also tell it to load complete
+files or modules by sending it @code{load} or @code{use-modules}
+expressions. You can set breakpoints and evaluate code which hits those
+breakpoints, and GDS will pop up the stack at the breakpoint so you can
+explore your code by single-stepping and evaluating test expressions.
+For a hands-on, tutorial introduction to using GDS in this way, use
+Emacs to open the file @file{gds-tutorial.txt} (which should have been
+installed as part of Guile, perhaps under @file{/usr/share/doc/guile}),
+and then follow the steps in that file.
+
+When you want to use GDS to explore or debug an independent Guile
+application, you need to add something to that application's Scheme code
+to cause it to connect to and interact with GDS at the right times. The
+following subsections describe the various ways of doing this.
-Here are some of the ways that a Guile program or script can arrange in
-its startup code to use GDS.
+@subsubsection Setting Specific Breakpoints
-@subsubsection Invoking GDS when an Exception Occurs
+The first option is to use @code{break-in} or @code{break-at} to set
+specific breakpoints in the application's code. This requires code like
+the following.
@lisp
-(use-modules (ice-9 gds-client)
- (ice-9 debugging traps))
+(use-modules (ice-9 debugging breakpoints)
+ (ice-9 gds-client))
-(on-lazy-handler-dispatch gds-debug-trap)
+(break-in 'fact2 "ice-9/debugging/example-fns"
+ #:behaviour gds-debug-trap)
+(break-in 'facti "ice-9/debugging/example-fns"
+ #:behaviour gds-debug-trap)
@end lisp
-This means that the program will use GDS to display the stack whenever
-it hits an exception that is protected by a @code{lazy-catch} using
-Guile's standard @code{lazy-catch-handler} (defined in
-@file{boot-9.scm}).
-
-@code{lazy-catch-handler} is used by the @code{stack-catch} procedure,
-provided by the @code{(ice-9 stack-catch)} module, so this will include
-exceptions within a @code{stack-catch}. @code{lazy-catch-handler} is
-also used by the standard Guile REPL, when you run Guile interactively,
-so you can add the above lines to your @file{.guile} file if you want to
-use GDS whenever something that you type into the REPL throws an
-exception.
+@noindent
+The @code{#:behaviour gds-debug-trap} clauses mean to use GDS to display
+the stack when one of these breakpoints is hit. For more on
+breakpoints, @code{break-in} and @code{break-at}, see @ref{Intro to
+Breakpoints}.
@subsubsection Setting GDS-managed Breakpoints
+Instead of listing specific breakpoints in application code, you can use
+GDS to manage the set of breakpoints that you want from Emacs, and tell
+the application to download the breakpoints that it should set from
+GDS. The code for this is:
+
@lisp
(use-modules (ice-9 gds-client))
(set-gds-breakpoints)
its code, then continues running.
When the program later hits one of the breakpoints, it will use GDS to
-display the stack and wait for instruction on what to do next, as
-described above.
+display the stack and wait for instruction on what to do next.
-@subsubsection Setting Specific Breakpoints
+@subsubsection Invoking GDS when an Exception Occurs
+
+Another option is to use GDS to catch and display any exceptions that
+are thrown by the application's code. If you already have a
+@code{lazy-catch} or @code{with-throw-handler} around the area of code
+that you want to monitor, you just need to add the following to the
+handler code:
@lisp
-(use-modules (ice-9 debugging breakpoints)
- (ice-9 gds-client))
+(gds-debug-trap (throw->trap-context key args))
+@end lisp
-(break-in 'fact2 "ice-9/debugging/example-fns"
- #:behaviour gds-debug-trap)
+@noindent
+where @code{key} and @code{args} are the first and rest arguments that
+Guile passes to the handler. (In other words, they assume the handler
+signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or
+later, you can also do this with a @code{catch}, by adding this same
+code to the catch's pre-unwind handler.
+
+If you don't already have any of these, insert a whole
+@code{with-throw-handler} expression (or @code{lazy-catch} if your Guile
+is pre-1.8) around the code of interest like this:
+
+@lisp
+(with-throw-handler #t
+ (lambda ()
+ ;; Protected code here.
+ )
+ (lambda (key . args)
+ (gds-debug-trap (throw->trap-context key args))))
@end lisp
-In this example, the program chooses to define its breakpoint explicitly
-in its code, rather than downloading definitions from GDS, but it still
-uses GDS to control what happens when the breakpoint is hit, by
-specifying @code{gds-debug-trap} as the breakpoint behaviour.
+In all cases you will need to use the @code{(ice-9 gds-client)} and
+@code{(ice-9 debugging traps)} modules.
+
+Two special cases of this are the lazy-catch that the Guile REPL code
+uses to catch exceptions in user code, and the lazy-catch inside the
+@code{stack-catch} utility procedure that is provided by the
+@code{(ice-9 stack-catch)} module. Both of these use a handler called
+@code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you
+can hook into such that it calls GDS to display the stack when an
+exception occurs. To do this, use the @code{on-lazy-handler-dispatch}
+procedure as follows.
+
+@lisp
+(use-modules (ice-9 gds-client)
+ (ice-9 debugging traps))
+
+(on-lazy-handler-dispatch gds-debug-trap)
+@end lisp
+
+@noindent
+After this the program will use GDS to display the stack whenever it
+hits an exception that is protected by a @code{lazy-catch} using
+@code{lazy-handler-dispatch}.
@subsubsection Accepting GDS Instructions at Any Time
@subsubsection Utility Guile Implementation
-We bring this subsection full circle by noting that the ``utility'' Guile
-client, which GDS starts automatically when you use GDS as described
-under approach 1 above, is really just a special case of ``a Guile
-program or script which is started independently'' (approach 2), and
-provides the services that the GDS front end needs by a simple
-combination of some of the code fragments just described.
+We conclude this subsection with an aside, by noting that the
+``utility'' Guile client described above is nothing more than a
+combination of the previous options.
-To be precise, the code for the utility Guile client is essentially
+To be precise, the code for the utility Guile client is essentially just
this:
@lisp
@code{set-gds-breakpoints} works as already described. The
@code{named-module-use!} line ensures that the client can process
-@code{help} and @code{apropos} expressions, which is what the front end
-sends to implement lookups in Guile's online help. The @code{#f}
-parameter to @code{gds-accept-input} means that the @code{continue}
-instruction will not cause the instruction loop to exit, which makes
-sense here because the utility client has nothing to do except to
-process GDS instructions.
+@code{help} and @code{apropos} expressions, to implement lookups in
+Guile's online help. The @code{#f} parameter to @code{gds-accept-input}
+means that the @code{continue} instruction will not cause the
+instruction loop to exit, which makes sense here because the utility
+client has nothing to do except to process GDS instructions.
(The utility client does not use @code{on-lazy-handler-dispatch},
because it has its own mechanism for catching and reporting exceptions
@code{on-lazy-handler-dispatch} provides.)
+@node Working with GDS in Scheme Buffers
+@subsection Working with GDS in Scheme Buffers
+
+The following subsections describe the facilities and key sequences that
+GDS provides for working on code in @code{scheme-mode} buffers.
+
+@menu
+* Access to Guile Help and Completion::
+* Setting and Managing Breakpoints::
+* Evaluating Scheme Code::
+@end menu
+
+
+@node Access to Guile Help and Completion
+@subsubsection Access to Guile Help and Completion
+
+The following keystrokes provide fast and convenient access to Guile's
+built in help, and to completion with respect to the set of defined and
+accessible symbols.
+
+@table @kbd
+@item C-h g
+@findex gds-help-symbol
+Get Guile help for a particular symbol, with the same results as if
+you had typed @code{(help SYMBOL)} into the Guile REPL
+(@code{gds-help-symbol}). The symbol to query defaults to the word at
+or before the cursor but can also be entered or edited in the
+minibuffer. The available help is popped up in a temporary Emacs
+window.
+
+@item C-h C-g
+@findex gds-apropos
+List all accessible Guile symbols matching a given regular expression,
+with the same results as if you had typed @code{(apropos REGEXP)} into
+the Guile REPL (@code{gds-apropos}). The regexp to query defaults to
+the word at or before the cursor but can also be entered or edited in
+the minibuffer. The list of matching symbols is popped up in a
+temporary Emacs window.
+
+@item M-@key{TAB}
+@findex gds-complete-symbol
+Try to complete the symbol at the cursor by matching it against the
+set of all defined and accessible bindings in the associated Guile
+process (@code{gds-complete-symbol}). If there are any extra
+characters that can be definitively added to the symbol at point, they
+are inserted. Otherwise, if there are any completions available, they
+are popped up in a temporary Emacs window, where one of them can be
+selected using either @kbd{@key{RET}} or the mouse.
+@end table
+
+
+@node Setting and Managing Breakpoints
+@subsubsection Setting and Managing Breakpoints
+
+You can create a breakpoint in GDS by typing @kbd{C-x @key{SPC}} in a
+Scheme mode buffer. To create a breakpoint on calls to a procedure ---
+i.e. the equivalent of calling @code{break-in} --- place the cursor
+anywhere within the procedure's definition, make sure that the region is
+unset, and type @kbd{C-x @key{SPC}}. To create breakpoints on a
+particular expression, or on the series of expressions in a particular
+region --- i.e. as with @code{break-at} --- select a region containing
+the open parentheses of the expressions where you want breakpoints, and
+type @kbd{C-x @key{SPC}}. In other words, GDS assumes that you want a
+@code{break-at} breakpoint if there is an active region, and a
+@code{break-in} breakpoint otherwise.
+
+There are three supported breakpoint behaviours, known as @code{debug},
+@code{trace} and @code{trace-subtree}. @code{debug} means that GDS will
+display the stack and wait for instruction when the breakpoint is hit.
+@code{trace} means that a line will be written to the trace output
+buffer (@code{*GDS Trace*}) when the breakpoint is hit, and when the
+relevant expression or procedure call returns. @code{trace-subtree}
+means that a line is written to the trace output buffer for every
+evaluation step between when the breakpoint is hit and when the
+expression or procedure returns.
+
+@kbd{C-x @key{SPC}} creates a breakpoint with behaviour according to the
+@code{gds-default-breakpoint-type} variable, which by default is
+@code{debug}; you can customize this if you prefer a different default.
+You can also create a breakpoint with behaviour other than the current
+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.)
+
+
+@node Evaluating Scheme Code
+@subsubsection Evaluating Scheme Code
+
+The following keystrokes and commands provide various ways of sending
+code to a Guile client process for evaluation.
+
+@table @kbd
+@item M-C-x
+@findex gds-eval-defun
+Evaluate the ``top level defun'' that the cursor is in, in other words
+the smallest balanced expression which includes the cursor and whose
+opening parenthesis is in column 0 (@code{gds-eval-defun}).
+
+@item C-x C-e
+@findex gds-eval-last-sexp
+Evaluate the expression that ends just before the cursor
+(@code{gds-eval-last-sexp}). This is designed so that it is easy to
+evaluate an expression that you have just finished typing.
+
+@item C-c C-e
+@findex gds-eval-expression
+Read a Scheme expression using the minibuffer, and evaluate that
+expression (@code{gds-eval-expression}).
+
+@item C-c C-r
+@findex gds-eval-region
+Evaluate the Scheme code in the marked region of the current buffer
+(@code{gds-eval-region}). Note that GDS does not check whether the
+region contains a balanced expression, or try to expand the region so
+that it does; it uses the region exactly as it is.
+@end table
+
+
@node Displaying the Scheme Stack
@subsection Displaying the Scheme Stack
@end table
-@node Evaluating Scheme Code
-@subsection Evaluating Scheme Code
-
-The following keystrokes and commands provide various ways of sending
-code to a Guile client process for evaluation.
-
-@table @kbd
-@item M-C-x
-@findex gds-eval-defun
-Evaluate the ``top level defun'' that the cursor is in, in other words
-the smallest balanced expression which includes the cursor and whose
-opening parenthesis is in column 0 (@code{gds-eval-defun}).
-
-@item C-x C-e
-@findex gds-eval-last-sexp
-Evaluate the expression that ends just before the cursor
-(@code{gds-eval-last-sexp}). This is designed so that it is easy to
-evaluate an expression that you have just finished typing.
-
-@item C-c C-e
-@findex gds-eval-expression
-Read a Scheme expression using the minibuffer, and evaluate that
-expression (@code{gds-eval-expression}).
-
-@item C-c C-r
-@findex gds-eval-region
-Evaluate the Scheme code in the marked region of the current buffer
-(@code{gds-eval-region}). Note that GDS does not check whether the
-region contains a balanced expression, or try to expand the region so
-that it does; it uses the region exactly as it is.
-@end table
-
-
-@node Setting and Managing Breakpoints
-@subsection Setting and Managing Breakpoints
-
-You can create a breakpoint in GDS by typing @kbd{C-x @key{SPC}} in a
-Scheme mode buffer. To create a breakpoint on calls to a procedure
---- i.e. the equivalent of calling @code{break-in} --- place the
-cursor on the procedure's name and type @kbd{C-x @key{SPC}}. To
-create breakpoints on a particular expression, or on the series of
-expressions in a particular region --- i.e. as with @code{break-at}
---- select the expression or region in the usual way and type @kbd{C-x
-@key{SPC}}. In general, GDS assumes that you want a @code{break-at}
-breakpoint if there is an active region, and a @code{break-in}
-breakpoint otherwise.
-
-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 ---
-which in my experience happens often.@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.)
-
-
-@node Access to Guile Help and Completion
-@subsection Access to Guile Help and Completion
-
-The following keystrokes provide fast and convenient access to Guile's
-built in help, and to completion with respect to the set of defined and
-accessible symbols.
-
-@table @kbd
-@item C-h g
-@findex gds-help-symbol
-Get Guile help for a particular symbol, with the same results as if
-you had typed @code{(help SYMBOL)} into the Guile REPL
-(@code{gds-help-symbol}). The symbol to query defaults to the word at
-or before the cursor but can also be entered or edited in the
-minibuffer. The available help is popped up in a temporary Emacs
-window.
-
-@item C-h C-g
-@findex gds-apropos
-List all accessible Guile symbols matching a given regular expression,
-with the same results as if you had typed @code{(apropos REGEXP)} into
-the Guile REPL (@code{gds-apropos}). The regexp to query defaults to
-the word at or before the cursor but can also be entered or edited in
-the minibuffer. The list of matching symbols is popped up in a
-temporary Emacs window.
-
-@item M-@key{TAB}
-@findex gds-complete-symbol
-Try to complete the symbol at the cursor by matching it against the
-set of all defined and accessible bindings in the associated Guile
-process (@code{gds-complete-symbol}). If there are any extra
-characters that can be definitively added to the symbol at point, they
-are inserted. Otherwise, if there are any completions available, they
-are popped up in a temporary Emacs window, where one of them can be
-selected using either @kbd{@key{RET}} or the mouse.
-@end table
-
-
@node Associating Buffers with Clients
@subsection Associating Buffers with Clients
region to Guile for evaluation. GDS will ask you which Guile process to
use; unless you know that you already have another Guile application
running and connected to GDS, choose the ``Start a new Guile'' option,
-which starts one of the ``utility'' processes described in @ref{How To
-Use GDS}.
+which starts one of the ``utility'' processes described in @ref{GDS
+Getting Started}.
The results of the evaluation pop up in a window like this:
GDS's most compelling feature is its single-stepping. To get an
immediate feel for what this is like, make sure your Emacs is prepared
-as described in @ref{GDS Setup}, then type the following code into an
-interactive Guile session.
+as described in @ref{GDS Getting Started}, then type the following code
+into an interactive Guile session.
@lisp
(fact1 4)
file.)
-@node GDS Architecture
-@subsection GDS Architecture
-
-Ths following information may be of interest to readers who would like
-to know how GDS works. Please note that understanding the details of
-this subsection is completely optional so far as just using GDS is
-concerned!
-
-GDS consists of three components.
-
-@itemize
-@item
-The GDS @dfn{interface} code is written in Emacs Lisp and runs inside
-Emacs. This code, consisting of the installed files @file{gds.el} and
-@file{gds-server.el}, is responsible for displaying information from
-Guile in Emacs windows, and for responding to Emacs commands and
-keystrokes by sending instructions back to the Guile program being
-debugged.
-
-@item
-The GDS @dfn{server} code is written in Scheme and runs as an Emacs
-inferior process. It acts as a multiplexer between the (possibly
-multiple) Guile programs being debugged and the interface code running
-in Emacs. The server code is the installed file
-@file{gds-server.scm}.
-
-@item
-The GDS @dfn{client} code is written in Scheme (installed file
-@file{gds-client.scm}), and is loaded as a module by each Guile
-program that wants to use GDS for debugging. When a trap occurs whose
-behaviour is @code{gds-debug-trap}, it feeds information about the
-trap context through the server to Emacs, then waits for instruction
-back from the Emacs interface on what to do next.
-@end itemize
-
-@noindent
-Summarized in glorious ASCII art, this looks as follows.
-
-@example
-+------------+
-| Program #1 |
-| |
-| +--------+ |
-| | Client |-_
-| +--------+ |-_ +---------------+
-+------------+ -_TCP | Emacs |
- -_ | |
- -_+--------+ | +-----------+ |
- _| Server |-----| Interface | |
-+------------+ _- +--------+ | +-----------+ |
-| Program #2 | _- +---------------+
-| | _- TCP
-| +--------+ _-
-| | Client |-|
-| +--------+ |
-+------------+
-@end example
-
-@noindent
-@cindex TCP, use of
-The communication between the client and server components is over a
-TCP connection, which has two implications. Firstly, that GDS is
-independent of whatever other interfaces the programs being debugged
-have, whether graphical or through standard input and output.
-Secondly, that the server and Emacs interface can be on a different
-computer from the programs being debugged (only theoretically, though,
-because GDS doesn't yet provide an interface to connect to any server
-other than the default, on localhost at TCP port 8333). The data
-exchanged between client and server components, and between server and
-interface components, is in the form of sexps that are organized so as
-to be directly readable by both Scheme and Emacs Lisp.
-
-
-@subsubsection Security Note
-
-@cindex Security
-GDS currently has no authentication between its client and server
-components, so in an untrusted environment the use of TCP probably
-raises important security issues. If you are thinking of using GDS in
-such an environment, please consider any such issues carefully before
-proceeding!
-
-
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
HCoop / bpt / guile.git / blobdiff