emacs/gds-faq.txt

   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: