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