mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-29 19:30:36 +02:00
Code Activity

remove gds docs, telling users instead to use geiser and paredit

Browse source 
* doc/ref/scheme-using.texi (Using Guile in Emacs): Remove GDS docs, as
  we don't have GDS any more. Instead of surveying the field, be
  opinionated and tell users what to use: Geiser and Paredit.
This commit is contained in:
Andy Wingo 2010-10-12 13:01:10 +02:00
parent ced9917e12
commit 767dbb1af3
1 changed files with 46 additions and 717 deletions
Download patch file Download diff file Expand all files Collapse all files

763
doc/ref/scheme-using.texi
View file

@ -567,735 +567,64 @@ Finally, as a word to the wise: hackers close their REPL prompts with
@node Using Guile in Emacs
@section Using Guile in Emacs
@cindex GDS
@cindex Emacs
There are several options for working on Guile Scheme code in Emacs.
The simplest 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.
Any text editor can edit Scheme, but some are better than others. Emacs
is the best, of course, and not just because it is a fine text editor.
Emacs has good support for Scheme out of the box, with sensible
indentation rules, parenthesis-matching, syntax highlighting, and even a
set of keybindings for structural editing, allowing navigation,
cut-and-paste, and transposition operations that work on balanced
S-expressions.
@iftex
@center @image{scheme,5in}
@end iftex
@ifnottex
@example
@verbatiminclude scheme.txt
@end example
@end ifnottex
As good as it is, though, two things will vastly improve your experience
with Emacs and Guile.
@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.
@cindex Paredit
The first is Taylor Campbell's
@uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not
code in any dialect of Lisp without Paredit. (They say that
unopinionated writing is boring---hence this tone---but it's the
truth, regardless.) Paredit is the bee's knees.
@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.
@cindex Geiser
The second is José Antonio Ortega Ruiz's
@uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs'
@code{scheme-mode} with tight integration to running Guile processes via
a @code{comint-mode} REPL buffer.
@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}.
Of course there are keybindings to switch to the REPL, and a good REPL
environment, but Geiser goes beyond that, providing:
@dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme
combination, but with a 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 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 to run some GDS-specific library code; currently
this code is written as a Guile module and uses features that are
specific to Guile. GDS is now included in the Guile distribution; for
previous Guile releases (1.8.4 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 GDS Introduction
@subsection GDS Introduction
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
@itemize @bullet
@item
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
Form evaluation in the context of the current file's module.
@item
completing the identifier at point, with respect to the set of variable
names that are known to the associated Guile process
Macro expansion.
@item
accessing Guile's built in ``help'' and ``apropos'' commands
File/module loading and/or compilation.
@item
evaluating fragments of code to check what they do, with the results
popping up in a temporary Emacs window.
Namespace-aware identifier completion (including local bindings, names
visible in the current module, and module names).
@item
Autodoc: the echo area shows information about the signature of the
procedure/macro around point automatically.
@item
Jump to definition of identifier at point.
@item
Access to documentation (including docstrings when the implementation
provides it).
@item
Listings of identifiers exported by a given module.
@item
Listings of callers/callees of procedures.
@item
Rudimentary support for debugging and error navigation.
@item
Support for multiple, simultaneous REPLs.
@end itemize
@item
Debugging a Guile Scheme program. When your program hits an error or
stops at a trap, GDS shows you the relevant code and the Scheme stack,
and makes it easy to
@itemize
@item
look at the values of local variables
@item
see what is happening at all levels of the Scheme stack
@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
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.
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.
@node GDS Architecture
@subsection GDS Architecture
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
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
worked on.
@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 must be loaded as a module by each Guile
program that wants to use GDS in any way.
@end itemize
@noindent
The following diagram shows how these components are connected to each
other.
@iftex
@center @image{gds,5in}
@end iftex
@ifnottex
@example
@verbatiminclude gds.txt
@end example
@end ifnottex
@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 client
programs, 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 future.
@node GDS Getting Started
@subsection Getting Started with GDS
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. 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:
@lisp
error in process filter: Wrong type argument: listp, Backtrace:
@end lisp
@noindent
and the @code{gds-debug} buffer will contain a Scheme backtrace ending
with the message:
@lisp
no code for module (ice-9 gds-server)
@end lisp
@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.
When you want to use GDS to work on 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 ways of doing this.
@subsubsection Invoking GDS when an Exception Occurs
One 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
(gds-debug-trap (throw->trap-context key args))
@end lisp
@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
Either way, 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
In addition to setting an exception handler as described above, a
Guile program can in principle set itself up to accept new
instructions from GDS at any time, not just when it has stopped at an
exception. This would allow the GDS user to evaluate code in the
context of the running program, without having to wait for the program
to stop first.
@lisp
(use-modules (ice-9 gds-client))
(gds-accept-input #t)
@end lisp
@code{gds-accept-input} causes the calling program to loop processing
instructions from GDS, until GDS sends the @code{continue} instruction.
This blocks the thread that calls it, however, so it will normally be
more practical for the program to set up a dedicated GDS thread and call
@code{gds-accept-input} from that thread.
For @code{select}-driven applications, an alternative approach would be
for the GDS client code to provide an API which allowed the application
to
@itemize
@item
discover the file descriptors (or Scheme ports) that are used for
receiving instruction from the GDS front end, so that it could include
these in its @code{select} call
@item
call the GDS instruction handler when @code{select} indicated data
available for reading on those descriptors/ports.
@end itemize
@noindent
This approach is not yet implemented, though.
@subsubsection Utility Guile Implementation
The ``utility'' Guile client mentioned above is a simple combination
of the mechanisms that we have just described. In fact the code for
the utility Guile client is essentially just this:
@lisp
(use-modules (ice-9 gds-client))
(named-module-use! '(guile-user) '(ice-9 session))
(gds-accept-input #f))
@end lisp
The @code{named-module-use!} line ensures that the client can process
@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} at its
top level, because it has its own mechanism for catching and reporting
exceptions in the code that it is asked to evaluate. This mechanism
summarizes the exception and gives the user a button they can click to
see the full stack, so the end result is very similar to what
@code{on-lazy-handler-dispatch} provides. Deep inside
@code{gds-accept-input}, in the part that handles evaluating
expressions from Emacs, the GDS client code uses
@code{throw->trap-context} and @code{gds-debug-trap} to implement
this.
@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::
* 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 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 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
If you type @kbd{C-u} before one of these commands, GDS will immediately
pop up a Scheme stack buffer, showing the requested evaluation, so that
you can single step through it. The Scheme stack display, and the
options for continuing through the code, are described in the next two
sections.
@node Displaying the Scheme Stack
@subsection Displaying the Scheme Stack
When you specify @code{gds-debug-trap} as the behaviour for a trap and
the Guile program concerned hits that trap, GDS displays the stack and
the relevant Scheme source code in Emacs, allowing you to explore the
state of the program and then decide what to do next. The same
applies if the program calls @code{(on-lazy-handler-dispatch
gds-debug-trap)} and then throws an exception that passes through
@code{lazy-handler-dispatch}, except that in this case you can only
explore; it isn't possible to continue normal execution after an
exception.
The following commands are available in the stack buffer for exploring
the state of the program.
@table @asis
@item @kbd{u}, @kbd{C-p}, @kbd{@key{up}}
@findex gds-up
Select the stack frame one up from the currently selected frame
(@code{gds-up}). GDS displays stack frames with the innermost at the
top, so moving ``up'' means selecting a more ``inner'' frame.
@item @kbd{d}, @kbd{C-n}, @kbd{@key{down}}
@findex gds-down
Select the stack frame one down from the currently selected frame
(@code{gds-down}). GDS displays stack frames with the innermost at the
top, so moving ``down'' means selecting a more ``outer'' frame.
@item @kbd{@key{RET}}
@findex gds-select-stack-frame
Select the stack frame at point (@code{gds-select-stack-frame}). This
is useful after clicking somewhere in the stack trace with the mouse.
@end table
Selecting a frame means that GDS will display the source code
corresponding to that frame in the adjacent window, and that
subsequent frame-sensitive commands, such as @code{gds-evaluate} (see
below) and @code{gds-step-over} (@pxref{Continuing Execution}), will
refer to that frame.
@table @kbd
@item e
@findex gds-evaluate
Evaluate a variable or expression in the local environment of the
selected stack frame (@code{gds-evaluate}). The result is displayed in
the echo area.
@item I
@findex gds-frame-info
Show summary information about the selected stack frame
(@code{gds-frame-info}). This includes what type of frame it is, the
associated expression, and the frame's source location, if any.
@item A
@findex gds-frame-args
For an application frame, display the frame's arguments
(@code{gds-frame-args}).
@item S
@findex gds-proc-source
For an application frame, show the Scheme source code of the procedure
being called (@code{gds-proc-source}). The source code (where
available) is displayed in the echo area.
@end table
@kbd{S} (@code{gds-proc-source}) is useful when the procedure being
called was created by an anonymous @code{(lambda @dots{})} expression.
Such procedures appear in the stack trace as @code{<procedure #f
(@dots{})>}, which doesn't give you much clue as to what will happen
next. @kbd{S} will show you the procedure's code, which is usually
enough for you to identify it.
@node Continuing Execution
@subsection Continuing Execution
If it makes sense to continue execution from the stack which is being
displayed, GDS provides the following further commands in the stack
buffer.
@table @asis
@item @kbd{g}, @kbd{c}, @kbd{q}
@findex gds-go
Tell the program to continue running (@code{gds-go}). It may of course
stop again if it hits another trap, or another occurrence of the same
trap.
The multiple keystrokes reflect that you can think of this as ``going'',
``continuing'' or ``quitting'' (in the sense of quitting the GDS
display).
@item @kbd{@key{SPC}}
@findex gds-step-file
Tell the program to do a single-step to the next entry or exit of a
frame whose code comes from the same source file as the selected stack
frame (@code{gds-step-file}).
In other words, you can hit @kbd{@key{SPC}} repeatedly to step through
the code in a given file, automatically stepping @emph{over} any
evaluations or procedure calls that use code from other files (or from
no file).
If the selected stack frame has no source, the effect of this command is
the same as that of @kbd{i}, described next.
@item @kbd{i}
@findex gds-step-into
Tell the debugged program to do a single-step to the next frame entry or
exit of any kind (@code{gds-step-into}). @kbd{i} therefore steps
through code at the most detailed level possible.
@item @kbd{o}
@findex gds-step-over
Tell the debugged program to continue running until the selected stack
frame completes, and then to display its result (@code{gds-step-over}).
Note that the program may stop before then if it hits another trap; in
this case the trap telling it to stop when the marked frame completes
remains in place and so will still fire at the appropriate point.
@end table
@node Associating Buffers with Clients
@subsection Associating Buffers with Clients
The first time that you use one of GDS's evaluation, help or completion
commands from a given Scheme mode buffer, GDS will ask which Guile
client program you want to use for the operation, or if you want to
start up a new ``utility'' client. After that GDS considers the buffer
to be ``associated'' with the selected client, and so sends all further
requests to that client, but you can override this by explicitly
associating the buffer with a different client, or by removing the
default association.
@table @kbd
@item M-x gds-associate-buffer
Associate (or re-associate) the current buffer with a particular Guile
client program. The available clients are listed, and you can also
choose to start up a new ``utility'' client for this buffer to associate
with.
@item M-x gds-dissociate-buffer
Dissociate the current buffer from its client, if any. This means that
the next time you use an evaluation, help or completion command, GDS
will ask you again which client to send the request to.
@end table
When a buffer is associated with a client program, the buffer's modeline
shows whether the client is currently able to accept instruction from
GDS. This is done by adding one of the following suffixes to the
``Scheme'' major mode indicator:
@table @asis
@item :ready
The client program (or one of its threads, if multithreaded) is
currently ready to accept instruction from GDS. In other words, if you
send it a help or evaluation request, you should see the result pretty
much immediately.
@item :running
The client program is not currently able to accept instruction from
GDS. This means that it (or all of its threads, if multithreaded) is
busy, or waiting for input other than from GDS.
@item :debug
The client program (or one of its threads, if multithreaded) is stopped
in ``debugging mode'' with GDS displaying the stack for a trap or
exception. It is waiting for instruction from GDS on what to do next.
@end table
@node An Example GDS Session
@subsection An Example GDS Session
Create a file, @file{testgds.scm} say, for experimenting with GDS and
Scheme code, and type this into it:
@lisp
(use-modules (ice-9 debugging traps)
(ice-9 gds-client)
(ice-9 debugging example-fns))
(install-trap (make <procedure-trap>
#:behaviour gds-debug-trap
#:procedure fact1))
@end lisp
@noindent
Now select all of this code and type @kbd{C-c C-r} to send the selected
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{GDS
Getting Started}.
The results of the evaluation pop up in a window like this:
@lisp
(use-modules (ice-9 debugging traps)\n @dots{}
;;; Evaluating subexpression 1 in current module (guile-user)
@result{} no (or unspecified) value
;;; Evaluating subexpression 2 in current module (guile-user)
@result{} no (or unspecified) value
--:** *Guile Evaluation* (Scheme:ready)--All------------
@end lisp
@noindent
this tells you that the evaluation was successful but that the return
values were unspecified. Its effect was to load a module of example
functions and set a trap on one of these functions, @code{fact1}, that
calculates the factorial of its argument.
If you now call @code{fact1}, you can see the trap and GDS's stack
display in action. To do this add
@lisp
(fact1 4)
@end lisp
@noindent
to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which
evaluates the expression that the cursor is just after the end of).
The result should be that a GDS stack window like the following
appears:
@lisp
Calling procedure:
=> s [fact1 4]
s [primitive-eval (fact1 4)]
--:** PID 28729 (Guile-Debug)--All------------
@end lisp
This stack tells you that Guile is about to call the @code{fact1}
procedure, with argument 4, and you can step through this call in
detail by pressing @kbd{i} once and then @kbd{@key{SPC}}
(@pxref{Continuing Execution}).
(@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}},
because the aim here is to step through code in the @code{(ice-9
debugging example-fns)} module, whose source file is
@file{@dots{}/ice-9/debugging/example-fns.scm}, but the initial
@code{(fact1 4)} call comes from the Guile session, whose ``source
file'' Guile presents as @file{standard input}. If the user starts by
pressing @kbd{@key{SPC}} instead of @kbd{i}, the effect is that the
program runs until it hits the first recursive call @code{(fact1 (- n
1))}, where it stops because of the trap on @code{fact1} firing again.
At this point, the source file @emph{is}
@file{@dots{}/ice-9/debugging/example-fns.scm}, because the recursive
@code{(fact1 (- n 1))} call comes from code in that file, so further
pressing of @kbd{@key{SPC}} successfully single-steps through this
file.)
See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more
information.
@c Local Variables: