Commit | Line | Data |
---|---|---|
1a228575 NJ |
1 | |
2 | * Installation | |
3 | ||
4 | ** How do I install guile-debugging? | |
5 | ||
6 | After unpacking the .tar.gz file, run the usual sequence of commands: | |
7 | ||
8 | $ ./configure | |
9 | $ make | |
10 | $ sudo make install | |
11 | ||
12 | Then you need to make sure that the directory where guile-debugging's | |
13 | Scheme files were installed is included in your Guile's load path. | |
14 | (The sequence above will usually install guile-debugging under | |
15 | /usr/local, and /usr/local is not in Guile's load path by default, | |
16 | unless Guile itself was installed under /usr/local.) You can discover | |
17 | your Guile's default load path by typing | |
18 | ||
19 | $ guile -q -c '(begin (write %load-path) (newline))' | |
20 | ||
21 | There are two ways to add guile-debugging's installation directory to | |
22 | Guile's load path, if it isn't already there. | |
23 | ||
24 | 1. Edit or create the `init.scm' file, which Guile reads on startup, | |
25 | so that it includes a line like this: | |
26 | ||
27 | (set! %load-path (cons "/usr/local/share/guile" %load-path)) | |
28 | ||
29 | but with "/usr/local" replaced by the prefix that you installed | |
30 | guile-debugging under, if not /usr/local. | |
31 | ||
32 | The init.scm file must be installed (if it does not already exist | |
33 | there) in one of the directories in Guile's default load-path. | |
34 | ||
35 | 2. Add this line to your .emacs file: | |
36 | ||
37 | (setq gds-scheme-directory "/usr/local/share/guile") | |
38 | ||
39 | before the `require' or `load' line that loads GDS, but with | |
40 | "/usr/local" replaced by the prefix that you installed | |
41 | guile-debugging under, if not /usr/local. | |
42 | ||
43 | Finally, if you want guile-debugging's GDS interface to be loaded | |
44 | automatically whenever you run Emacs, add this line to your .emacs: | |
45 | ||
46 | (require 'gds) | |
47 | ||
48 | * Troubleshooting | |
49 | ||
50 | ** "error in process filter" when starting Emacs (or loading GDS) | |
51 | ||
52 | This is caused by an internal error in GDS's Scheme code, for which a | |
53 | backtrace will have appeared in the gds-debug buffer, so please switch | |
54 | to the gds-debug buffer and see what it says there. | |
55 | ||
56 | The most common cause is a load path problem: Guile cannot find GDS's | |
57 | Scheme code because it is not in the known load path. In this case | |
58 | you should see the error message "no code for module" somewhere in the | |
59 | backtrace. If you see this, please try the remedies described in `How | |
60 | do I install guile-debugging?' above, then restart Emacs and see if | |
61 | the problem has been cured. | |
62 | ||
63 | If you don't see "no code for module", or if the described remedies | |
64 | don't fix the problem, please send the contents of the gds-debug | |
65 | buffer to me at <neil@ossau.uklinux.net>, so I can debug the problem. | |
66 | ||
67 | If you don't see a backtrace at all in the gds-debug buffer, try the | |
68 | next item ... | |
69 | ||
70 | ** "error in process filter" at some other time | |
71 | ||
72 | This is caused by an internal error somewhere in GDS's Emacs Lisp | |
73 | code. If possible, please | |
74 | ||
75 | - switch on the `debug-on-error' option (M-x set-variable RET | |
76 | debug-on-error RET t RET) | |
77 | ||
78 | - do whatever you were doing so that the same error happens again | |
79 | ||
80 | - send the Emacs Lisp stack trace which pops up to me at | |
81 | <neil@ossau.uklinux.net>. | |
82 | ||
83 | If that doesn't work, please just mail me with as much detail as | |
84 | possible of what you were doing when the error occurred. | |
85 | ||
86 | * GDS Features | |
87 | ||
88 | ** How do I inspect variable values? | |
89 | ||
90 | Type `e' followed by the name of the variable, then <RET>. This | |
91 | works whenever GDS is displaying a stack for an error at at a | |
92 | breakpoint. (You can actually `e' to evaluate any expression in the | |
93 | local environment of the selected stack frame; inspecting variables is | |
94 | the special case of this where the expression is only a variable name.) | |
95 | ||
96 | If GDS is displaying the associated source code in the window above or | |
97 | below the stack, you can see the values of any variables in the | |
98 | highlighted code just by hovering your mouse over them. | |
99 | ||
100 | ** How do I change a variable's value? | |
101 | ||
102 | Type `e' and then `(set! VARNAME NEWVAL)', where VARNAME is the name | |
103 | of the variable you want to set and NEWVAL is an expression which | |
104 | Guile can evaluate to get the new value. This works whenever GDS is | |
105 | displaying a stack for an error at at a breakpoint. The setting will | |
106 | take effect in the local environment of the selected stack frame. | |
107 | ||
108 | ** How do I change the expression that Guile is about to evaluate? | |
109 | ||
110 | Type `t' followed by the expression that you want Guile to evaluate | |
111 | instead, then <RET>. | |
112 | ||
113 | Then type one of the commands that tells Guile to continue execution. | |
114 | ||
115 | (Tweaking expressions, as described here, is only supported by the | |
116 | latest CVS version of Guile. The GDS stack display tells you when | |
117 | tweaking is possible by adding "(tweakable)" to the first line of the | |
118 | stack window.) | |
119 | ||
120 | ** How do I return a value from the current stack frame different to what the evaluator has calculated? | |
121 | ||
122 | You have to be at the normal exit of the relevant frame first, so if | |
123 | GDS is not already showing you the normally calculated return value, | |
124 | type `o' to finish the evaluation of the selected frame. | |
125 | ||
126 | Then type `t' followed by the value you want to return, and <RET>. | |
127 | The value that you type can be any expression, but note that it will | |
128 | not be evaluated before being returned; for example if you type `(+ 2 | |
129 | 3)', the return value will be a three-element list, not 5. | |
130 | ||
131 | Finally type one of the commands that tells Guile to continue | |
132 | execution. | |
133 | ||
134 | (Tweaking return values, as described here, is only supported by the | |
135 | latest CVS version of Guile. The GDS stack display tells you when | |
136 | tweaking is possible by adding "(tweakable)" to the first line of the | |
137 | stack window.) | |
138 | ||
139 | ** How do I step over a line of code? | |
140 | ||
141 | Scheme isn't organized by lines, so it doesn't really make sense to | |
142 | think of stepping over lines. Instead please see the next entry on | |
143 | stepping over expressions. | |
144 | ||
145 | ** How do I step over an expression? | |
146 | ||
147 | It depends what you mean by "step over". If you mean that you want | |
148 | Guile to evaluate that expression normally, but then show you its | |
149 | return value, type `o', which does exactly that. | |
150 | ||
151 | If you mean that you want to skip the evaluation of that expression | |
152 | (for example because it has side effects that you don't want to | |
153 | happen), use `t' to change the expression to something else which | |
154 | Guile will evaluate instead. | |
155 | ||
156 | There has to be a substitute expression so Guile can calculate a value | |
157 | to return to the calling frame. If you know at a particular point | |
158 | that the return value is not important, you can type `t #f <RET>' or | |
159 | `t 0 <RET>'. | |
160 | ||
161 | See `How do I change the expression that Guile is about to evaluate?' | |
162 | above for more on using `t'. | |
163 | ||
164 | ** How do I move up and down the call stack? | |
165 | ||
166 | Type `u' to move up and `d' to move down. "Up" in GDS means to a more | |
167 | "inner" frame, and "down" means to a more "outer" frame. | |
168 | ||
169 | ** How do I run until the next breakpoint? | |
170 | ||
171 | Type `g' (for "go"). | |
172 | ||
173 | ** How do I run until the end of the selected stack frame? | |
174 | ||
175 | Type `o'. | |
176 | ||
177 | ** How do I set a breakpoint? | |
178 | ||
179 | First identify the code that you want to set the breakpoint in, and | |
180 | what kind of breakpoint you want. To set a breakpoint on entry to a | |
181 | top level procedure, move the cursor to anywhere in the procedure | |
182 | definition, and make sure that the region/mark is inactive. To set a | |
183 | breakpoint on a particular expression (or sequence of expressions) set | |
184 | point and mark so that the region covers the opening parentheses of | |
185 | all the target expressions. | |
186 | ||
187 | Then type ... | |
188 | ||
189 | `C-c C-b d' for a `debug' breakpoint, which means that GDS will | |
190 | display the stack when the breakpoint is hit | |
191 | ||
192 | `C-c C-b t' for a `trace' breakpoint, which means that the start and | |
193 | end of the relevant procedure or expression(s) will be traced to the | |
194 | *GDS Trace* buffer | |
195 | ||
196 | `C-c C-b T' for a `trace-subtree' breakpoint, which means that every | |
197 | evaluation step involved in the evaluation of the relevant procedure | |
198 | or expression(s) will be traced to the *GDS Trace* buffer. | |
199 | ||
200 | You can also type `C-x <SPC>', which does the same as one of the | |
201 | above, depending on the value of `gds-default-breakpoint-type'. | |
202 | ||
203 | ** How do I clear a breakpoint? | |
204 | ||
205 | Select a region containing the breakpoints that you want to clear, and | |
206 | type `C-c C-b <DEL>'. | |
207 | ||
208 | ** How do I trace calls to a particular procedure or evaluations of a particular expression? | |
209 | ||
210 | In GDS this means setting a breakpoint whose type is `trace' or | |
211 | `trace-subtree'. See `How do I set a breakpoint?' above. | |
212 | ||
213 | * Development | |
214 | ||
215 | ** How can I follow or contribute to guile-debugging's development? | |
216 | ||
217 | guile-debugging is hosted at http://gna.org, so please see the project | |
218 | page there. Feel free to raise bugs, tasks containing patches or | |
219 | feature requests, and so on. You can also write directly to me by | |
220 | email: <neil@ossau.uklinux.net>. | |
221 | ||
222 | ||
223 | Local Variables: | |
224 | mode: outline | |
225 | End: |