Commit | Line | Data |
---|---|---|
46f7666d NJ |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
749c2532 | 3 | @c Copyright (C) 2006, 2010 |
46f7666d NJ |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @node Using Guile Interactively | |
8 | @section Using Guile Interactively | |
9 | ||
10 | When you start up Guile by typing just @code{guile}, without a | |
11 | @code{-c} argument or the name of a script to execute, you get an | |
12 | interactive interpreter where you can enter Scheme expressions, and | |
13 | Guile will evaluate them and print the results for you. Here are some | |
14 | simple examples. | |
15 | ||
16 | @lisp | |
749c2532 | 17 | scheme@@(guile-user)> (+ 3 4 5) |
46f7666d | 18 | 12 |
749c2532 | 19 | scheme@@(guile-user)> (display "Hello world!\n") |
46f7666d | 20 | Hello world! |
749c2532 | 21 | scheme@@(guile-user)> (values 'a 'b) |
46f7666d NJ |
22 | a |
23 | b | |
24 | @end lisp | |
25 | ||
26 | @noindent | |
27 | This mode of use is called a @dfn{REPL}, which is short for | |
28 | ``Read-Eval-Print Loop'', because the Guile interpreter first reads the | |
29 | expression that you have typed, then evaluates it, and then prints the | |
30 | result. | |
31 | ||
749c2532 AW |
32 | The prompt shows you what language and module you are in. In this case, the |
33 | current language is @code{scheme}, and the current module is | |
34 | @code{(guile-user)}. @xref{Other Languages}, for more information on Guile's | |
35 | support for languages other than Scheme. | |
36 | ||
46f7666d NJ |
37 | @menu |
38 | * Readline:: | |
39 | * Value Historyx:: | |
40 | * Error Handling:: | |
41 | * Interactive Debugger:: Using the interactive debugger. | |
42 | @end menu | |
43 | ||
44 | ||
45 | @node Readline | |
46 | @subsection Readline | |
47 | ||
48 | To make it easier for you to repeat and vary previously entered | |
49 | expressions, or to edit the expression that you're typing in, Guile | |
50 | can use the GNU Readline library. This is not enabled by default | |
51 | because of licensing reasons, but all you need to activate Readline is | |
52 | the following pair of lines. | |
53 | ||
54 | @lisp | |
749c2532 AW |
55 | scheme@@(guile-user)> (use-modules (ice-9 readline)) |
56 | scheme@@(guile-user)> (activate-readline) | |
46f7666d NJ |
57 | @end lisp |
58 | ||
749c2532 | 59 | It's a good idea to put these two lines (without the ``scheme@@(guile-user)>'' |
46f7666d NJ |
60 | prompts) in your @file{.guile} file. Guile reads this file when it |
61 | starts up interactively, so anything in this file has the same effect | |
749c2532 | 62 | as if you type it in by hand at the ``scheme@@(guile-user)>'' prompt. |
46f7666d NJ |
63 | |
64 | ||
65 | @node Value Historyx | |
66 | @subsection Value History | |
67 | ||
68 | Just as Readline helps you to reuse a previous input line, @dfn{value | |
69 | history} allows you to use the @emph{result} of a previous evaluation | |
70 | in a new expression. When value history is enabled, each evaluation | |
71 | result is automatically assigned to the next in the sequence of | |
72 | variables @code{$1}, @code{$2}, @dots{}, and you can then use these | |
73 | variables in subsequent expressions. | |
74 | ||
75 | @lisp | |
749c2532 | 76 | scheme@@(guile-user)> (iota 10) |
46f7666d | 77 | $1 = (0 1 2 3 4 5 6 7 8 9) |
749c2532 | 78 | scheme@@(guile-user)> (apply * (cdr $1)) |
46f7666d | 79 | $2 = 362880 |
749c2532 | 80 | scheme@@(guile-user)> (sqrt $2) |
46f7666d | 81 | $3 = 602.3952191045344 |
749c2532 | 82 | scheme@@(guile-user)> (cons $2 $1) |
46f7666d NJ |
83 | $4 = (362880 0 1 2 3 4 5 6 7 8 9) |
84 | @end lisp | |
85 | ||
86 | To enable value history, type @code{(use-modules (ice-9 history))} at | |
87 | the Guile prompt, or add this to your @file{.guile} file. (It is not | |
88 | enabled by default, to avoid the possibility of conflicting with some | |
89 | other use you may have for the variables @code{$1}, @code{$2}, | |
90 | @dots{}, and also because it prevents the stored evaluation results | |
91 | from being garbage collected, which some people may not want.) | |
92 | ||
93 | ||
94 | @node Error Handling | |
95 | @subsection Error Handling | |
96 | ||
97 | When code being evaluated from the REPL hits an error, Guile remembers | |
98 | the execution context where the error occurred and can give you three | |
99 | levels of information about what the error was and exactly where it | |
100 | occurred. | |
101 | ||
ee6be719 | 102 | By default, Guile displays only the first level, which is the most |
46f7666d NJ |
103 | immediate information about where and why the error occurred, for |
104 | example: | |
105 | ||
106 | @lisp | |
107 | (make-string (* 4 (+ 3 #\s)) #\space) | |
108 | @print{} | |
109 | standard input:2:19: In procedure + in expression (+ 3 #\s): | |
110 | standard input:2:19: Wrong type argument: #\s | |
111 | ABORT: (wrong-type-arg) | |
112 | ||
ee6be719 NJ |
113 | Type "(backtrace)" to get more information |
114 | or "(debug)" to enter the debugger. | |
46f7666d NJ |
115 | @end lisp |
116 | ||
117 | @noindent | |
118 | However, as the message above says, you can obtain more information | |
119 | about the context of the error by typing @code{(backtrace)} or | |
120 | @code{(debug)}. | |
121 | ||
122 | @code{(backtrace)} displays the Scheme call stack at the point where the | |
123 | error occurred: | |
124 | ||
125 | @lisp | |
126 | (backtrace) | |
127 | @print{} | |
128 | Backtrace: | |
129 | In standard input: | |
130 | 2: 0* [make-string ... | |
131 | 2: 1* [* 4 ... | |
132 | 2: 2* [+ 3 #\s] | |
133 | ||
134 | Type "(debug-enable 'backtrace)" if you would like a backtrace | |
135 | automatically if an error occurs in the future. | |
136 | @end lisp | |
137 | ||
138 | @noindent | |
139 | In a more complex scenario than this one, this can be extremely useful | |
140 | for understanding where and why the error occurred. You can make Guile | |
141 | show the backtrace automatically by adding @code{(debug-enable | |
142 | 'backtrace)} to your @file{.guile}. | |
143 | ||
144 | @code{(debug)} takes you into Guile's interactive debugger, which | |
145 | provides commands that allow you to | |
146 | ||
147 | @itemize @bullet | |
148 | @item | |
149 | display the Scheme call stack at the point where the error occurred | |
150 | (the @code{backtrace} command --- see @ref{Display Backtrace}) | |
151 | ||
152 | @item | |
153 | move up and down the call stack, to see in detail the expression being | |
154 | evaluated, or the procedure being applied, in each @dfn{frame} (the | |
155 | @code{up}, @code{down}, @code{frame}, @code{position}, @code{info args} | |
156 | and @code{info frame} commands --- see @ref{Frame Selection} and | |
157 | @ref{Frame Information}) | |
158 | ||
159 | @item | |
160 | examine the values of variables and expressions in the context of each | |
161 | frame (the @code{evaluate} command --- see @ref{Frame Evaluation}). | |
162 | @end itemize | |
163 | ||
164 | @noindent | |
ee6be719 | 165 | The interactive debugger is documented further in the following section. |
46f7666d NJ |
166 | |
167 | ||
168 | @node Interactive Debugger | |
169 | @subsection Using the Interactive Debugger | |
170 | ||
24dbb5ed NJ |
171 | Guile's interactive debugger is a command line application that |
172 | accepts commands from you for examining the stack and, if stopped at a | |
173 | trap, for continuing program execution in various ways. Unlike in the | |
174 | normal Guile REPL, commands are typed mostly without parentheses. | |
46f7666d NJ |
175 | |
176 | When you first enter the debugger, it introduces itself with a message | |
177 | like this: | |
178 | ||
179 | @lisp | |
180 | This is the Guile debugger -- for help, type `help'. | |
181 | There are 3 frames on the stack. | |
182 | ||
183 | Frame 2 at standard input:36:19 | |
184 | [+ 3 #\s] | |
185 | debug> | |
186 | @end lisp | |
187 | ||
188 | @noindent | |
189 | ``debug>'' is the debugger's prompt, and a reminder that you are not in | |
ee6be719 NJ |
190 | the normal Guile REPL. In case you find yourself in the debugger by |
191 | mistake, the @code{quit} command will return you to the REPL. | |
192 | ||
193 | @deffn {Debugger Command} quit | |
194 | Exit the debugger. | |
195 | @end deffn | |
196 | ||
197 | The other available commands are described in the following subsections. | |
46f7666d NJ |
198 | |
199 | @menu | |
200 | * Display Backtrace:: backtrace. | |
201 | * Frame Selection:: up, down, frame. | |
202 | * Frame Information:: info args, info frame, position. | |
203 | * Frame Evaluation:: evaluate. | |
ee6be719 | 204 | * Stepping and Continuing:: step, next, (trace-)finish, continue. |
46f7666d NJ |
205 | @end menu |
206 | ||
207 | ||
208 | @node Display Backtrace | |
209 | @subsubsection Display Backtrace | |
210 | ||
211 | The @code{backtrace} command, which can also be invoked as @code{bt} or | |
212 | @code{where}, displays the call stack (aka backtrace) at the point where | |
213 | the debugger was entered: | |
214 | ||
215 | @lisp | |
216 | debug> bt | |
217 | In standard input: | |
218 | 36: 0* [make-string ... | |
219 | 36: 1* [* 4 ... | |
220 | 36: 2* [+ 3 #\s] | |
221 | @end lisp | |
222 | ||
223 | @deffn {Debugger Command} backtrace [count] | |
224 | @deffnx {Debugger Command} bt [count] | |
225 | @deffnx {Debugger Command} where [count] | |
226 | Print backtrace of all stack frames, or of the innermost @var{count} | |
227 | frames. With a negative argument, print the outermost -@var{count} | |
228 | frames. If the number of frames isn't explicitly given, the debug | |
229 | option @code{depth} determines the maximum number of frames printed. | |
230 | @end deffn | |
231 | ||
232 | The format of the displayed backtrace is the same as for the | |
ee6be719 | 233 | @code{display-backtrace} procedure (@pxref{Examining the Stack}). |
46f7666d NJ |
234 | |
235 | ||
236 | @node Frame Selection | |
237 | @subsubsection Frame Selection | |
238 | ||
239 | A call stack consists of a sequence of stack @dfn{frames}, with each | |
240 | frame describing one level of the nested evaluations and applications | |
241 | that the program was executing when it hit a breakpoint or an error. | |
242 | Frames are numbered such that frame 0 is the outermost --- i.e. the | |
243 | operation on the call stack that began least recently --- and frame N-1 | |
244 | the innermost (where N is the total number of frames on the stack). | |
245 | ||
246 | When you enter the debugger, the innermost frame is selected, which | |
247 | means that the commands for getting information about the ``current'' | |
248 | frame, or for evaluating expressions in the context of the current | |
249 | frame, will do so by default with respect to the innermost frame. To | |
250 | select a different frame, so that these operations will apply to it | |
251 | instead, use the @code{up}, @code{down} and @code{frame} commands like | |
252 | this: | |
253 | ||
254 | @lisp | |
255 | debug> up | |
256 | Frame 1 at standard input:36:14 | |
257 | [* 4 ... | |
258 | debug> frame 0 | |
259 | Frame 0 at standard input:36:1 | |
260 | [make-string ... | |
261 | debug> down | |
262 | Frame 1 at standard input:36:14 | |
263 | [* 4 ... | |
264 | @end lisp | |
265 | ||
266 | @deffn {Debugger Command} up [n] | |
267 | Move @var{n} frames up the stack. For positive @var{n}, this | |
ee6be719 | 268 | advances toward the outermost frame, to lower frame numbers, to |
46f7666d NJ |
269 | frames that have existed longer. @var{n} defaults to one. |
270 | @end deffn | |
271 | ||
272 | @deffn {Debugger Command} down [n] | |
273 | Move @var{n} frames down the stack. For positive @var{n}, this | |
ee6be719 | 274 | advances toward the innermost frame, to higher frame numbers, to frames |
46f7666d NJ |
275 | that were created more recently. @var{n} defaults to one. |
276 | @end deffn | |
277 | ||
278 | @deffn {Debugger Command} frame [n] | |
279 | Select and print a stack frame. With no argument, print the selected | |
280 | stack frame. (See also ``info frame''.) An argument specifies the | |
281 | frame to select; it must be a stack-frame number. | |
282 | @end deffn | |
283 | ||
284 | ||
285 | @node Frame Information | |
286 | @subsubsection Frame Information | |
287 | ||
ee6be719 NJ |
288 | The following commands return detailed information about the currently |
289 | selected frame. | |
46f7666d NJ |
290 | |
291 | @deffn {Debugger Command} {info frame} | |
ee6be719 NJ |
292 | Display a verbose description of the selected frame. The information |
293 | that this command provides is equivalent to what can be deduced from the | |
294 | one line summary for the frame that appears in a backtrace, but is | |
295 | presented and explained more clearly. | |
46f7666d NJ |
296 | @end deffn |
297 | ||
298 | @deffn {Debugger Command} {info args} | |
ee6be719 NJ |
299 | Display the argument variables of the current stack frame. Arguments |
300 | can also be seen in the backtrace, but are presented more clearly by | |
301 | this command. | |
46f7666d NJ |
302 | @end deffn |
303 | ||
304 | @deffn {Debugger Command} position | |
ee6be719 NJ |
305 | Display the name of the source file that the current expression comes |
306 | from, and the line and column number of the expression's opening | |
307 | parenthesis within that file. This information is only available when | |
308 | the @code{positions} read option is enabled (@pxref{Reader options}). | |
46f7666d NJ |
309 | @end deffn |
310 | ||
311 | ||
312 | @node Frame Evaluation | |
313 | @subsubsection Frame Evaluation | |
314 | ||
ee6be719 NJ |
315 | The @code{evaluate} command is most useful for querying the value of a |
316 | variable, either global or local, in the environment of the selected | |
317 | stack frame, but it can be used more generally to evaluate any | |
318 | expression. | |
46f7666d NJ |
319 | |
320 | @deffn {Debugger Command} evaluate expression | |
ee6be719 NJ |
321 | Evaluate an expression in the environment of the selected stack frame. |
322 | The expression must appear on the same line as the command, however it | |
323 | may be continued over multiple lines. | |
46f7666d NJ |
324 | @end deffn |
325 | ||
326 | ||
ee6be719 NJ |
327 | @node Stepping and Continuing |
328 | @subsubsection Single Stepping and Continuing Execution | |
46f7666d | 329 | |
ee6be719 NJ |
330 | The commands in this subsection all apply only when the stack is |
331 | @dfn{continuable} --- in other words when it makes sense for the program | |
332 | that the stack comes from to continue running. Usually this means that | |
333 | the program stopped because of a trap or a breakpoint. | |
46f7666d NJ |
334 | |
335 | @deffn {Debugger Command} step [n] | |
ee6be719 NJ |
336 | Tell the debugged program to do @var{n} more steps from its current |
337 | position. One @dfn{step} means executing until the next frame entry or | |
338 | exit of any kind. @var{n} defaults to 1. | |
46f7666d NJ |
339 | @end deffn |
340 | ||
341 | @deffn {Debugger Command} next [n] | |
ee6be719 NJ |
342 | Tell the debugged program to do @var{n} more steps from its current |
343 | position, but only counting frame entries and exits where the | |
344 | corresponding source code comes from the same file as the current stack | |
345 | frame. (See @ref{Step Traps} for the details of how this works.) If | |
346 | the current stack frame has no source code, the effect of this command | |
347 | is the same as of @code{step}. @var{n} defaults to 1. | |
46f7666d NJ |
348 | @end deffn |
349 | ||
46f7666d | 350 | @deffn {Debugger Command} finish |
ee6be719 NJ |
351 | Tell the program being debugged to continue running until the completion |
352 | of the current stack frame, and at that time to print the result and | |
353 | reenter the command line debugger. | |
46f7666d NJ |
354 | @end deffn |
355 | ||
46f7666d | 356 | @deffn {Debugger Command} continue |
ee6be719 NJ |
357 | Tell the program being debugged to continue running. (In fact this is |
358 | the same as the @code{quit} command, because it exits the debugger | |
359 | command loop and so allows whatever code it was that invoked the | |
360 | debugger to continue.) | |
46f7666d NJ |
361 | @end deffn |
362 | ||
363 | ||
364 | @node Using Guile in Emacs | |
365 | @section Using Guile in Emacs | |
366 | ||
b20ef3a6 NJ |
367 | @cindex GDS |
368 | @cindex Emacs | |
24dbb5ed NJ |
369 | There are several options for working on Guile Scheme code in Emacs. |
370 | The simplest are to use Emacs's standard @code{scheme-mode} for | |
371 | editing code, and to run the interpreter when you need it by typing | |
372 | ``guile'' at the prompt of a @code{*shell*} buffer, but there are | |
373 | Emacs libraries available which add various bells and whistles to | |
374 | this. The following diagram shows these libraries and how they relate | |
375 | to each other, with the arrows indicating ``builds on'' or | |
376 | ``extends''. For example, the Quack library builds on cmuscheme, | |
377 | which in turn builds on the standard scheme mode. | |
01d2ee15 | 378 | |
e163dd34 BG |
379 | @iftex |
380 | @center @image{scheme,5in} | |
381 | @end iftex | |
382 | @ifnottex | |
01d2ee15 | 383 | @example |
e163dd34 | 384 | @verbatiminclude scheme.txt |
01d2ee15 | 385 | @end example |
e163dd34 | 386 | @end ifnottex |
01d2ee15 NJ |
387 | |
388 | @dfn{scheme}, written by Bill Rozas and Dave Love, is Emacs's standard | |
389 | mode for Scheme code files. It provides Scheme-sensitive syntax | |
390 | highlighting, parenthesis matching, indentation and so on. | |
391 | ||
392 | @dfn{cmuscheme}, written by Olin Shivers, provides a comint-based Scheme | |
393 | interaction buffer, so that you can run an interpreter more directly | |
94a2c24a | 394 | than with the @code{*shell*} buffer approach by typing @kbd{M-x |
01d2ee15 NJ |
395 | run-scheme}. It also extends @code{scheme-mode} so that there are key |
396 | presses for sending selected bits of code from a Scheme buffer to this | |
397 | interpreter. This means that when you are writing some code and want to | |
398 | check what an expression evaluates to, you can easily select that code | |
399 | and send it to the interpreter for evaluation, then switch to the | |
400 | interpreter to see what the result is. cmuscheme is included in the | |
401 | standard Emacs distribution. | |
402 | ||
403 | @dfn{Quack}, written by Neil Van Dyke, adds a number of incremental | |
404 | improvements to the scheme/cmuscheme combination: convenient menu | |
405 | entries for looking up Scheme-related references (such as the SRFIs); | |
406 | enhanced indentation rules that are customized for particular Scheme | |
407 | interpreters, including Guile; an enhanced version of the | |
408 | @code{run-scheme} command that knows the names of the common Scheme | |
409 | interpreters and remembers which one you used last time; and so on. | |
410 | Quack is available from @uref{http://www.neilvandyke.org/quack}. | |
411 | ||
412 | @dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme | |
24dbb5ed NJ |
413 | combination, but with a change to the way that Scheme code fragments |
414 | are sent to the interpreter for evaluation. cmuscheme and Quack send | |
415 | code fragments to the interpreter's standard input, on the assumption | |
416 | that the interpreter is expecting to read Scheme expressions there, | |
417 | and then monitor the interpreter's standard output to infer what the | |
418 | result of the evaluation is. GDS doesn't use standard input and | |
01d2ee15 NJ |
419 | output like this. Instead, it sets up a socket connection between the |
420 | Scheme interpreter and Emacs, and sends and receives messages using a | |
421 | simple protocol through this socket. The messages include requests to | |
422 | evaluate Scheme code, and responses conveying the results of an | |
24dbb5ed NJ |
423 | evaluation, thus providing similar function to cmuscheme or Quack. |
424 | They also include requests for stack exploration and debugging, which | |
425 | go beyond what cmuscheme or Quack can do. The price of this extra | |
426 | power, however, is that GDS is Guile-specific. GDS requires the | |
427 | Scheme interpreter to run some GDS-specific library code; currently | |
428 | this code is written as a Guile module and uses features that are | |
01d2ee15 | 429 | specific to Guile. GDS is now included in the Guile distribution; for |
24dbb5ed | 430 | previous Guile releases (1.8.4 and earlier) it can be obtained as part |
01d2ee15 NJ |
431 | of the @code{guile-debugging} package from |
432 | @uref{http://www.ossau.uklinux.net/guile}. | |
433 | ||
94a2c24a NJ |
434 | Finally, @dfn{xscheme} is similar to cmuscheme --- in that it starts up |
435 | a Scheme interaction process and sends commands to that process's | |
436 | standard input --- and to GDS --- in that it has support beyond | |
437 | cmuscheme or Quack for exploring the Scheme stack when an error has | |
438 | occurred --- but is implemented specifically for MIT/GNU Scheme. Hence | |
439 | it isn't really relevant to Guile work in Emacs, except as a reference | |
440 | for useful features that could be implemented in one of the other | |
441 | libraries mentioned here. | |
442 | ||
443 | In summary, the best current choice for working on Guile code in Emacs | |
444 | is either Quack or GDS, depending on which of these libraries' features | |
445 | you find most important. For more information on Quack, please see the | |
446 | website referenced above. GDS is documented further in the rest of this | |
447 | section. | |
01d2ee15 NJ |
448 | |
449 | @menu | |
450 | * GDS Introduction:: | |
94a2c24a | 451 | * GDS Architecture:: |
01d2ee15 | 452 | * GDS Getting Started:: |
72bcfa04 | 453 | * Working with GDS in Scheme Buffers:: |
01d2ee15 NJ |
454 | * Displaying the Scheme Stack:: |
455 | * Continuing Execution:: | |
01d2ee15 NJ |
456 | * Associating Buffers with Clients:: |
457 | * An Example GDS Session:: | |
01d2ee15 NJ |
458 | @end menu |
459 | ||
460 | ||
461 | @node GDS Introduction | |
462 | @subsection GDS Introduction | |
463 | ||
464 | GDS aims to allow you to work on Guile Scheme code in the same kind of | |
465 | way that Emacs allows you to work on Emacs Lisp code: providing easy | |
466 | access to help, evaluating arbitrary fragments of code, a nice debugging | |
94a2c24a | 467 | interface, and so on. The thinking behind the GDS library is that you |
01d2ee15 | 468 | will usually be doing one of two things. |
46f7666d NJ |
469 | |
470 | @enumerate | |
471 | @item | |
01d2ee15 NJ |
472 | Writing or editing code. The code will be in a normal Emacs Scheme mode |
473 | buffer, and GDS extends Scheme mode to add keystrokes and menu items for | |
474 | the things that are likely to be useful to you when working on code: | |
46f7666d NJ |
475 | |
476 | @itemize | |
477 | @item | |
94a2c24a NJ |
478 | completing the identifier at point, with respect to the set of variable |
479 | names that are known to the associated Guile process | |
46f7666d | 480 | @item |
94a2c24a | 481 | accessing Guile's built in ``help'' and ``apropos'' commands |
46f7666d | 482 | @item |
94a2c24a NJ |
483 | evaluating fragments of code to check what they do, with the results |
484 | popping up in a temporary Emacs window. | |
46f7666d NJ |
485 | @end itemize |
486 | ||
487 | @item | |
69986e21 NJ |
488 | Debugging a Guile Scheme program. When your program hits an error or |
489 | stops at a trap, GDS shows you the relevant code and the Scheme stack, | |
490 | and makes it easy to | |
46f7666d NJ |
491 | |
492 | @itemize | |
493 | @item | |
494 | look at the values of local variables | |
495 | @item | |
496 | see what is happening at all levels of the Scheme stack | |
497 | @item | |
498 | continue execution, either normally or step by step. | |
499 | @end itemize | |
46f7666d | 500 | |
94a2c24a NJ |
501 | The presentation makes it very easy to move up and down the stack, |
502 | showing whenever possible the source code for each frame in another | |
503 | Emacs buffer. It also provides convenient keystrokes for telling Guile | |
504 | what to do next; for example, you can select a stack frame and tell | |
505 | Guile to run until that frame completes, at which point GDS will display | |
506 | the frame's return value. | |
4f6e3015 | 507 | @end enumerate |
94a2c24a | 508 | |
94a2c24a NJ |
509 | GDS can provide these facilities for any number of Guile Scheme programs |
510 | (which we often refer to as ``clients'') at once, and these programs can | |
511 | be started either independently of GDS, including outside Emacs, or | |
512 | specifically @emph{by} GDS. | |
62ae9557 | 513 | |
94a2c24a NJ |
514 | Communication between each Guile client program and GDS uses a TCP |
515 | socket, which means that it is orthogonal to any other interfaces that | |
516 | the client program has. In particular GDS does not interfere with a | |
517 | program's standard input and output. | |
62ae9557 | 518 | |
94a2c24a NJ |
519 | |
520 | @node GDS Architecture | |
521 | @subsection GDS Architecture | |
522 | ||
523 | In order to understand the following documentation fully it will help to | |
524 | have a picture in mind of how GDS works, so we briefly describe that | |
525 | here. GDS consists of three components. | |
46f7666d | 526 | |
62ae9557 NJ |
527 | @itemize |
528 | @item | |
94a2c24a NJ |
529 | The GDS @dfn{interface} code is written in Emacs Lisp and runs inside |
530 | Emacs. This code, consisting of the installed files @file{gds.el} and | |
531 | @file{gds-server.el}, is responsible for displaying information from | |
532 | Guile in Emacs windows, and for responding to Emacs commands and | |
533 | keystrokes by sending instructions back to the Guile program being | |
24dbb5ed | 534 | worked on. |
94a2c24a NJ |
535 | |
536 | @item | |
537 | The GDS @dfn{server} code is written in Scheme and runs as an Emacs | |
538 | inferior process. It acts as a multiplexer between the (possibly | |
539 | multiple) Guile programs being debugged and the interface code running | |
540 | in Emacs. The server code is the installed file | |
541 | @file{gds-server.scm}. | |
62ae9557 NJ |
542 | |
543 | @item | |
94a2c24a NJ |
544 | The GDS @dfn{client} code is written in Scheme (installed file |
545 | @file{gds-client.scm}), and must be loaded as a module by each Guile | |
546 | program that wants to use GDS in any way. | |
62ae9557 NJ |
547 | @end itemize |
548 | ||
549 | @noindent | |
94a2c24a NJ |
550 | The following diagram shows how these components are connected to each |
551 | other. | |
62ae9557 | 552 | |
e163dd34 BG |
553 | @iftex |
554 | @center @image{gds,5in} | |
555 | @end iftex | |
556 | @ifnottex | |
94a2c24a | 557 | @example |
e163dd34 | 558 | @verbatiminclude gds.txt |
94a2c24a | 559 | @end example |
e163dd34 | 560 | @end ifnottex |
62ae9557 | 561 | |
94a2c24a NJ |
562 | @cindex TCP, use of |
563 | The data exchanged between client and server components, and between | |
564 | server and interface, is a sequence of sexps (parenthesised expressions) | |
565 | that are designed so as to be directly readable by both Scheme and Emacs | |
566 | Lisp. The use of a TCP connection means that the server and Emacs | |
24dbb5ed NJ |
567 | interface can theoretically be on a different computer from the client |
568 | programs, but in practice there are currently two problems with | |
94a2c24a NJ |
569 | this. Firstly the GDS API doesn't provide any way of specifying a |
570 | non-local server to connect to, and secondly there is no security or | |
571 | authentication mechanism in the GDS protocol. These are issues that | |
24dbb5ed | 572 | should be addressed in the future. |
62ae9557 | 573 | |
94a2c24a | 574 | |
01d2ee15 NJ |
575 | @node GDS Getting Started |
576 | @subsection Getting Started with GDS | |
62ae9557 | 577 | |
94a2c24a | 578 | To enable the use of GDS in your own Emacs sessions, simply add |
62ae9557 NJ |
579 | |
580 | @lisp | |
581 | (require 'gds) | |
582 | @end lisp | |
583 | ||
584 | @noindent | |
94a2c24a NJ |
585 | somewhere in your @file{.emacs} file. This will cause Emacs to load the |
586 | GDS Emacs Lisp code when starting up, and to start the inferior GDS | |
587 | server process so that it is ready and waiting for any Guile programs | |
588 | that want to use GDS. | |
62ae9557 | 589 | |
94a2c24a NJ |
590 | (If GDS's Scheme code is not installed in one of the locations in |
591 | Guile's load path, you may find that the server process fails to start. | |
592 | When this happens you will see an error message from Emacs: | |
62ae9557 | 593 | |
94a2c24a NJ |
594 | @lisp |
595 | error in process filter: Wrong type argument: listp, Backtrace: | |
596 | @end lisp | |
62ae9557 | 597 | |
94a2c24a NJ |
598 | @noindent |
599 | and the @code{gds-debug} buffer will contain a Scheme backtrace ending | |
600 | with the message: | |
62ae9557 | 601 | |
94a2c24a | 602 | @lisp |
24dbb5ed | 603 | no code for module (ice-9 gds-server) |
94a2c24a | 604 | @end lisp |
62ae9557 | 605 | |
94a2c24a NJ |
606 | @noindent |
607 | The solution for this is to customize the Emacs variable | |
608 | @code{gds-scheme-directory} so that it specifies where the GDS Scheme | |
609 | code is installed. Then either restart Emacs or type @kbd{M-x | |
610 | gds-run-debug-server} to try starting the GDS server process again.) | |
611 | ||
612 | For evaluations, help and completion from Scheme code buffers that you | |
613 | are working on, this is all you need. The first time you do any of | |
614 | these things, GDS will automatically start a new Guile client program as | |
615 | an Emacs subprocess. This Guile program does nothing but wait for and | |
616 | act on instructions from GDS, and we refer to it as a @dfn{utility} | |
617 | Guile client. Over time this utility client will accumulate the code | |
618 | that you ask it to evaluate, and you can also tell it to load complete | |
619 | files or modules by sending it @code{load} or @code{use-modules} | |
69986e21 | 620 | expressions. |
94a2c24a | 621 | |
24dbb5ed | 622 | When you want to use GDS to work on an independent Guile |
94a2c24a NJ |
623 | application, you need to add something to that application's Scheme code |
624 | to cause it to connect to and interact with GDS at the right times. The | |
24dbb5ed | 625 | following subsections describe the ways of doing this. |
62ae9557 | 626 | |
94a2c24a | 627 | @subsubsection Invoking GDS when an Exception Occurs |
62ae9557 | 628 | |
69986e21 | 629 | One option is to use GDS to catch and display any exceptions that |
1e1387ca NJ |
630 | are thrown by the application's code. If you already have a |
631 | @code{lazy-catch} or @code{with-throw-handler} around the area of code | |
632 | that you want to monitor, you just need to add the following to the | |
633 | handler code: | |
634 | ||
635 | @lisp | |
636 | (gds-debug-trap (throw->trap-context key args)) | |
637 | @end lisp | |
638 | ||
639 | @noindent | |
640 | where @code{key} and @code{args} are the first and rest arguments that | |
641 | Guile passes to the handler. (In other words, they assume the handler | |
642 | signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or | |
643 | later, you can also do this with a @code{catch}, by adding this same | |
aeb9d8e0 | 644 | code to the catch's pre-unwind handler. |
1e1387ca NJ |
645 | |
646 | If you don't already have any of these, insert a whole | |
aeb9d8e0 NJ |
647 | @code{with-throw-handler} expression (or @code{lazy-catch} if your Guile |
648 | is pre-1.8) around the code of interest like this: | |
1e1387ca NJ |
649 | |
650 | @lisp | |
651 | (with-throw-handler #t | |
652 | (lambda () | |
653 | ;; Protected code here. | |
654 | ) | |
655 | (lambda (key . args) | |
656 | (gds-debug-trap (throw->trap-context key args)))) | |
657 | @end lisp | |
658 | ||
24dbb5ed | 659 | Either way, you will need to use the @code{(ice-9 gds-client)} and |
1e1387ca NJ |
660 | @code{(ice-9 debugging traps)} modules. |
661 | ||
662 | Two special cases of this are the lazy-catch that the Guile REPL code | |
663 | uses to catch exceptions in user code, and the lazy-catch inside the | |
664 | @code{stack-catch} utility procedure that is provided by the | |
665 | @code{(ice-9 stack-catch)} module. Both of these use a handler called | |
aeb9d8e0 NJ |
666 | @code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you |
667 | can hook into such that it calls GDS to display the stack when an | |
668 | exception occurs. To do this, use the @code{on-lazy-handler-dispatch} | |
669 | procedure as follows. | |
1e1387ca | 670 | |
62ae9557 | 671 | @lisp |
94a2c24a NJ |
672 | (use-modules (ice-9 gds-client) |
673 | (ice-9 debugging traps)) | |
94a2c24a | 674 | (on-lazy-handler-dispatch gds-debug-trap) |
62ae9557 NJ |
675 | @end lisp |
676 | ||
1e1387ca NJ |
677 | @noindent |
678 | After this the program will use GDS to display the stack whenever it | |
679 | hits an exception that is protected by a @code{lazy-catch} using | |
aeb9d8e0 | 680 | @code{lazy-handler-dispatch}. |
62ae9557 NJ |
681 | |
682 | @subsubsection Accepting GDS Instructions at Any Time | |
683 | ||
69986e21 NJ |
684 | In addition to setting an exception handler as described above, a |
685 | Guile program can in principle set itself up to accept new | |
686 | instructions from GDS at any time, not just when it has stopped at an | |
687 | exception. This would allow the GDS user to evaluate code in the | |
688 | context of the running program, without having to wait for the program | |
689 | to stop first. | |
62ae9557 NJ |
690 | |
691 | @lisp | |
692 | (use-modules (ice-9 gds-client)) | |
693 | (gds-accept-input #t) | |
694 | @end lisp | |
695 | ||
696 | @code{gds-accept-input} causes the calling program to loop processing | |
697 | instructions from GDS, until GDS sends the @code{continue} instruction. | |
698 | This blocks the thread that calls it, however, so it will normally be | |
699 | more practical for the program to set up a dedicated GDS thread and call | |
700 | @code{gds-accept-input} from that thread. | |
701 | ||
702 | For @code{select}-driven applications, an alternative approach would be | |
703 | for the GDS client code to provide an API which allowed the application | |
704 | to | |
705 | ||
706 | @itemize | |
707 | @item | |
708 | discover the file descriptors (or Scheme ports) that are used for | |
709 | receiving instruction from the GDS front end, so that it could include | |
710 | these in its @code{select} call | |
711 | ||
712 | @item | |
713 | call the GDS instruction handler when @code{select} indicated data | |
714 | available for reading on those descriptors/ports. | |
715 | @end itemize | |
716 | ||
717 | @noindent | |
718 | This approach is not yet implemented, though. | |
719 | ||
720 | @subsubsection Utility Guile Implementation | |
721 | ||
24dbb5ed NJ |
722 | The ``utility'' Guile client mentioned above is a simple combination |
723 | of the mechanisms that we have just described. In fact the code for | |
724 | the utility Guile client is essentially just this: | |
62ae9557 NJ |
725 | |
726 | @lisp | |
727 | (use-modules (ice-9 gds-client)) | |
62ae9557 NJ |
728 | (named-module-use! '(guile-user) '(ice-9 session)) |
729 | (gds-accept-input #f)) | |
730 | @end lisp | |
731 | ||
69986e21 | 732 | The @code{named-module-use!} line ensures that the client can process |
1e1387ca | 733 | @code{help} and @code{apropos} expressions, to implement lookups in |
24dbb5ed NJ |
734 | Guile's online help. The @code{#f} parameter to |
735 | @code{gds-accept-input} means that the @code{continue} instruction | |
736 | will not cause the instruction loop to exit, which makes sense here | |
737 | because the utility client has nothing to do except to process GDS | |
738 | instructions. | |
739 | ||
740 | The utility client does not use @code{on-lazy-handler-dispatch} at its | |
741 | top level, because it has its own mechanism for catching and reporting | |
742 | exceptions in the code that it is asked to evaluate. This mechanism | |
743 | summarizes the exception and gives the user a button they can click to | |
744 | see the full stack, so the end result is very similar to what | |
745 | @code{on-lazy-handler-dispatch} provides. Deep inside | |
746 | @code{gds-accept-input}, in the part that handles evaluating | |
747 | expressions from Emacs, the GDS client code uses | |
748 | @code{throw->trap-context} and @code{gds-debug-trap} to implement | |
749 | this. | |
62ae9557 NJ |
750 | |
751 | ||
72bcfa04 NJ |
752 | @node Working with GDS in Scheme Buffers |
753 | @subsection Working with GDS in Scheme Buffers | |
754 | ||
755 | The following subsections describe the facilities and key sequences that | |
756 | GDS provides for working on code in @code{scheme-mode} buffers. | |
757 | ||
758 | @menu | |
759 | * Access to Guile Help and Completion:: | |
72bcfa04 NJ |
760 | * Evaluating Scheme Code:: |
761 | @end menu | |
762 | ||
763 | ||
7e5a256c | 764 | @node Access to Guile Help and Completion |
72bcfa04 | 765 | @subsubsection Access to Guile Help and Completion |
7e5a256c NJ |
766 | |
767 | The following keystrokes provide fast and convenient access to Guile's | |
768 | built in help, and to completion with respect to the set of defined and | |
72bcfa04 | 769 | accessible symbols. |
7e5a256c NJ |
770 | |
771 | @table @kbd | |
772 | @item C-h g | |
773 | @findex gds-help-symbol | |
774 | Get Guile help for a particular symbol, with the same results as if | |
775 | you had typed @code{(help SYMBOL)} into the Guile REPL | |
776 | (@code{gds-help-symbol}). The symbol to query defaults to the word at | |
777 | or before the cursor but can also be entered or edited in the | |
778 | minibuffer. The available help is popped up in a temporary Emacs | |
779 | window. | |
780 | ||
24dbb5ed | 781 | @item C-h G |
7e5a256c NJ |
782 | @findex gds-apropos |
783 | List all accessible Guile symbols matching a given regular expression, | |
784 | with the same results as if you had typed @code{(apropos REGEXP)} into | |
785 | the Guile REPL (@code{gds-apropos}). The regexp to query defaults to | |
786 | the word at or before the cursor but can also be entered or edited in | |
787 | the minibuffer. The list of matching symbols is popped up in a | |
788 | temporary Emacs window. | |
789 | ||
790 | @item M-@key{TAB} | |
791 | @findex gds-complete-symbol | |
792 | Try to complete the symbol at the cursor by matching it against the | |
793 | set of all defined and accessible bindings in the associated Guile | |
794 | process (@code{gds-complete-symbol}). If there are any extra | |
795 | characters that can be definitively added to the symbol at point, they | |
796 | are inserted. Otherwise, if there are any completions available, they | |
797 | are popped up in a temporary Emacs window, where one of them can be | |
798 | selected using either @kbd{@key{RET}} or the mouse. | |
799 | @end table | |
800 | ||
801 | ||
7e5a256c | 802 | @node Evaluating Scheme Code |
72bcfa04 | 803 | @subsubsection Evaluating Scheme Code |
7e5a256c NJ |
804 | |
805 | The following keystrokes and commands provide various ways of sending | |
806 | code to a Guile client process for evaluation. | |
807 | ||
808 | @table @kbd | |
809 | @item M-C-x | |
810 | @findex gds-eval-defun | |
811 | Evaluate the ``top level defun'' that the cursor is in, in other words | |
812 | the smallest balanced expression which includes the cursor and whose | |
813 | opening parenthesis is in column 0 (@code{gds-eval-defun}). | |
814 | ||
815 | @item C-x C-e | |
816 | @findex gds-eval-last-sexp | |
817 | Evaluate the expression that ends just before the cursor | |
818 | (@code{gds-eval-last-sexp}). This is designed so that it is easy to | |
819 | evaluate an expression that you have just finished typing. | |
820 | ||
821 | @item C-c C-e | |
822 | @findex gds-eval-expression | |
823 | Read a Scheme expression using the minibuffer, and evaluate that | |
824 | expression (@code{gds-eval-expression}). | |
825 | ||
826 | @item C-c C-r | |
827 | @findex gds-eval-region | |
828 | Evaluate the Scheme code in the marked region of the current buffer | |
829 | (@code{gds-eval-region}). Note that GDS does not check whether the | |
830 | region contains a balanced expression, or try to expand the region so | |
831 | that it does; it uses the region exactly as it is. | |
832 | @end table | |
833 | ||
091baf9e NJ |
834 | If you type @kbd{C-u} before one of these commands, GDS will |
835 | immediately pop up a Scheme stack buffer, showing the requested | |
836 | evaluation, so that you can single step through it. (This is achieved | |
837 | by setting a @code{<source-trap>} trap at the start of the requested | |
838 | evaluation; see @ref{Source Traps} for more on how those work.) The | |
839 | Scheme stack display, and the options for continuing through the code, | |
840 | are described in the next two sections. | |
841 | ||
7e5a256c | 842 | |
62ae9557 NJ |
843 | @node Displaying the Scheme Stack |
844 | @subsection Displaying the Scheme Stack | |
845 | ||
69986e21 NJ |
846 | When you specify @code{gds-debug-trap} as the behaviour for a trap and |
847 | the Guile program concerned hits that trap, GDS displays the stack and | |
848 | the relevant Scheme source code in Emacs, allowing you to explore the | |
849 | state of the program and then decide what to do next. The same | |
850 | applies if the program calls @code{(on-lazy-handler-dispatch | |
851 | gds-debug-trap)} and then throws an exception that passes through | |
852 | @code{lazy-handler-dispatch}, except that in this case you can only | |
853 | explore; it isn't possible to continue normal execution after an | |
854 | exception. | |
62ae9557 NJ |
855 | |
856 | The following commands are available in the stack buffer for exploring | |
857 | the state of the program. | |
858 | ||
859 | @table @asis | |
860 | @item @kbd{u}, @kbd{C-p}, @kbd{@key{up}} | |
861 | @findex gds-up | |
862 | Select the stack frame one up from the currently selected frame | |
863 | (@code{gds-up}). GDS displays stack frames with the innermost at the | |
864 | top, so moving ``up'' means selecting a more ``inner'' frame. | |
865 | ||
866 | @item @kbd{d}, @kbd{C-n}, @kbd{@key{down}} | |
867 | @findex gds-down | |
868 | Select the stack frame one down from the currently selected frame | |
869 | (@code{gds-down}). GDS displays stack frames with the innermost at the | |
870 | top, so moving ``down'' means selecting a more ``outer'' frame. | |
871 | ||
872 | @item @kbd{@key{RET}} | |
873 | @findex gds-select-stack-frame | |
874 | Select the stack frame at point (@code{gds-select-stack-frame}). This | |
875 | is useful after clicking somewhere in the stack trace with the mouse. | |
876 | @end table | |
877 | ||
878 | Selecting a frame means that GDS will display the source code | |
879 | corresponding to that frame in the adjacent window, and that | |
880 | subsequent frame-sensitive commands, such as @code{gds-evaluate} (see | |
881 | below) and @code{gds-step-over} (@pxref{Continuing Execution}), will | |
882 | refer to that frame. | |
883 | ||
884 | @table @kbd | |
885 | @item e | |
886 | @findex gds-evaluate | |
887 | Evaluate a variable or expression in the local environment of the | |
888 | selected stack frame (@code{gds-evaluate}). The result is displayed in | |
889 | the echo area. | |
890 | ||
891 | @item I | |
892 | @findex gds-frame-info | |
893 | Show summary information about the selected stack frame | |
894 | (@code{gds-frame-info}). This includes what type of frame it is, the | |
895 | associated expression, and the frame's source location, if any. | |
896 | ||
897 | @item A | |
898 | @findex gds-frame-args | |
899 | For an application frame, display the frame's arguments | |
900 | (@code{gds-frame-args}). | |
901 | ||
902 | @item S | |
903 | @findex gds-proc-source | |
904 | For an application frame, show the Scheme source code of the procedure | |
905 | being called (@code{gds-proc-source}). The source code (where | |
906 | available) is displayed in the echo area. | |
907 | @end table | |
908 | ||
909 | @kbd{S} (@code{gds-proc-source}) is useful when the procedure being | |
910 | called was created by an anonymous @code{(lambda @dots{})} expression. | |
911 | Such procedures appear in the stack trace as @code{<procedure #f | |
912 | (@dots{})>}, which doesn't give you much clue as to what will happen | |
913 | next. @kbd{S} will show you the procedure's code, which is usually | |
914 | enough for you to identify it. | |
915 | ||
916 | ||
917 | @node Continuing Execution | |
918 | @subsection Continuing Execution | |
919 | ||
920 | If it makes sense to continue execution from the stack which is being | |
921 | displayed, GDS provides the following further commands in the stack | |
922 | buffer. | |
923 | ||
924 | @table @asis | |
925 | @item @kbd{g}, @kbd{c}, @kbd{q} | |
926 | @findex gds-go | |
927 | Tell the program to continue running (@code{gds-go}). It may of course | |
928 | stop again if it hits another trap, or another occurrence of the same | |
929 | trap. | |
930 | ||
931 | The multiple keystrokes reflect that you can think of this as ``going'', | |
932 | ``continuing'' or ``quitting'' (in the sense of quitting the GDS | |
933 | display). | |
934 | ||
935 | @item @kbd{@key{SPC}} | |
936 | @findex gds-step-file | |
937 | Tell the program to do a single-step to the next entry or exit of a | |
938 | frame whose code comes from the same source file as the selected stack | |
939 | frame (@code{gds-step-file}). | |
940 | ||
941 | In other words, you can hit @kbd{@key{SPC}} repeatedly to step through | |
942 | the code in a given file, automatically stepping @emph{over} any | |
943 | evaluations or procedure calls that use code from other files (or from | |
944 | no file). | |
945 | ||
946 | If the selected stack frame has no source, the effect of this command is | |
947 | the same as that of @kbd{i}, described next. | |
948 | ||
949 | @item @kbd{i} | |
950 | @findex gds-step-into | |
951 | Tell the debugged program to do a single-step to the next frame entry or | |
952 | exit of any kind (@code{gds-step-into}). @kbd{i} therefore steps | |
953 | through code at the most detailed level possible. | |
954 | ||
955 | @item @kbd{o} | |
956 | @findex gds-step-over | |
957 | Tell the debugged program to continue running until the selected stack | |
958 | frame completes, and then to display its result (@code{gds-step-over}). | |
959 | Note that the program may stop before then if it hits another trap; in | |
960 | this case the trap telling it to stop when the marked frame completes | |
961 | remains in place and so will still fire at the appropriate point. | |
962 | @end table | |
963 | ||
964 | ||
62ae9557 NJ |
965 | @node Associating Buffers with Clients |
966 | @subsection Associating Buffers with Clients | |
967 | ||
968 | The first time that you use one of GDS's evaluation, help or completion | |
969 | commands from a given Scheme mode buffer, GDS will ask which Guile | |
970 | client program you want to use for the operation, or if you want to | |
971 | start up a new ``utility'' client. After that GDS considers the buffer | |
972 | to be ``associated'' with the selected client, and so sends all further | |
973 | requests to that client, but you can override this by explicitly | |
974 | associating the buffer with a different client, or by removing the | |
975 | default association. | |
976 | ||
977 | @table @kbd | |
978 | @item M-x gds-associate-buffer | |
979 | Associate (or re-associate) the current buffer with a particular Guile | |
980 | client program. The available clients are listed, and you can also | |
981 | choose to start up a new ``utility'' client for this buffer to associate | |
982 | with. | |
983 | ||
984 | @item M-x gds-dissociate-buffer | |
985 | Dissociate the current buffer from its client, if any. This means that | |
986 | the next time you use an evaluation, help or completion command, GDS | |
987 | will ask you again which client to send the request to. | |
988 | @end table | |
989 | ||
990 | When a buffer is associated with a client program, the buffer's modeline | |
991 | shows whether the client is currently able to accept instruction from | |
992 | GDS. This is done by adding one of the following suffixes to the | |
993 | ``Scheme'' major mode indicator: | |
994 | ||
995 | @table @asis | |
996 | @item :ready | |
997 | The client program (or one of its threads, if multithreaded) is | |
998 | currently ready to accept instruction from GDS. In other words, if you | |
999 | send it a help or evaluation request, you should see the result pretty | |
1000 | much immediately. | |
1001 | ||
1002 | @item :running | |
1003 | The client program is not currently able to accept instruction from | |
1004 | GDS. This means that it (or all of its threads, if multithreaded) is | |
1005 | busy, or waiting for input other than from GDS. | |
1006 | ||
1007 | @item :debug | |
1008 | The client program (or one of its threads, if multithreaded) is stopped | |
1009 | in ``debugging mode'' with GDS displaying the stack for a trap or | |
1010 | exception. It is waiting for instruction from GDS on what to do next. | |
1011 | @end table | |
1012 | ||
1013 | ||
1014 | @node An Example GDS Session | |
1015 | @subsection An Example GDS Session | |
1016 | ||
1017 | Create a file, @file{testgds.scm} say, for experimenting with GDS and | |
1018 | Scheme code, and type this into it: | |
1019 | ||
1020 | @lisp | |
1021 | (use-modules (ice-9 debugging traps) | |
1022 | (ice-9 gds-client) | |
1023 | (ice-9 debugging example-fns)) | |
1024 | (install-trap (make <procedure-trap> | |
1025 | #:behaviour gds-debug-trap | |
1026 | #:procedure fact1)) | |
1027 | @end lisp | |
1028 | ||
1029 | @noindent | |
1030 | Now select all of this code and type @kbd{C-c C-r} to send the selected | |
1031 | region to Guile for evaluation. GDS will ask you which Guile process to | |
1032 | use; unless you know that you already have another Guile application | |
1033 | running and connected to GDS, choose the ``Start a new Guile'' option, | |
94a2c24a NJ |
1034 | which starts one of the ``utility'' processes described in @ref{GDS |
1035 | Getting Started}. | |
62ae9557 NJ |
1036 | |
1037 | The results of the evaluation pop up in a window like this: | |
1038 | ||
1039 | @lisp | |
1040 | (use-modules (ice-9 debugging traps)\n @dots{} | |
1041 | ||
1042 | ;;; Evaluating subexpression 1 in current module (guile-user) | |
1043 | @result{} no (or unspecified) value | |
1044 | ||
1045 | ;;; Evaluating subexpression 2 in current module (guile-user) | |
1046 | @result{} no (or unspecified) value | |
1047 | ||
1048 | --:** *Guile Evaluation* (Scheme:ready)--All------------ | |
1049 | @end lisp | |
1050 | ||
1051 | @noindent | |
1052 | this tells you that the evaluation was successful but that the return | |
1053 | values were unspecified. Its effect was to load a module of example | |
1054 | functions and set a trap on one of these functions, @code{fact1}, that | |
1055 | calculates the factorial of its argument. | |
1056 | ||
1057 | If you now call @code{fact1}, you can see the trap and GDS's stack | |
1058 | display in action. To do this add | |
1059 | ||
1060 | @lisp | |
1061 | (fact1 4) | |
1062 | @end lisp | |
1063 | ||
1064 | @noindent | |
1065 | to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which | |
24dbb5ed NJ |
1066 | evaluates the expression that the cursor is just after the end of). |
1067 | The result should be that a GDS stack window like the following | |
1068 | appears: | |
62ae9557 NJ |
1069 | |
1070 | @lisp | |
1071 | Calling procedure: | |
1072 | => s [fact1 4] | |
1073 | s [primitive-eval (fact1 4)] | |
1074 | ||
1075 | ||
1076 | --:** PID 28729 (Guile-Debug)--All------------ | |
1077 | @end lisp | |
1078 | ||
24dbb5ed NJ |
1079 | This stack tells you that Guile is about to call the @code{fact1} |
1080 | procedure, with argument 4, and you can step through this call in | |
1081 | detail by pressing @kbd{i} once and then @kbd{@key{SPC}} | |
1082 | (@pxref{Continuing Execution}). | |
62ae9557 NJ |
1083 | |
1084 | (@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}}, | |
1085 | because the aim here is to step through code in the @code{(ice-9 | |
1086 | debugging example-fns)} module, whose source file is | |
1087 | @file{@dots{}/ice-9/debugging/example-fns.scm}, but the initial | |
1088 | @code{(fact1 4)} call comes from the Guile session, whose ``source | |
1089 | file'' Guile presents as @file{standard input}. If the user starts by | |
1090 | pressing @kbd{@key{SPC}} instead of @kbd{i}, the effect is that the | |
1091 | program runs until it hits the first recursive call @code{(fact1 (- n | |
1092 | 1))}, where it stops because of the trap on @code{fact1} firing again. | |
1093 | At this point, the source file @emph{is} | |
1094 | @file{@dots{}/ice-9/debugging/example-fns.scm}, because the recursive | |
1095 | @code{(fact1 (- n 1))} call comes from code in that file, so further | |
1096 | pressing of @kbd{@key{SPC}} successfully single-steps through this | |
1097 | file.) | |
1098 | ||
1099 | ||
46f7666d NJ |
1100 | @c Local Variables: |
1101 | @c TeX-master: "guile.texi" | |
1102 | @c End: |