84062
|
1 @comment -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
|
3 @c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
|
100974
|
4 @c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
|
84062
|
5 @c See the file elisp.texi for copying conditions.
|
|
6
|
|
7 @c This file can also be used by an independent Edebug User
|
|
8 @c Manual in which case the Edebug node below should be used
|
|
9 @c with the following links to the Bugs section and to the top level:
|
|
10
|
|
11 @c , Bugs and Todo List, Top, Top
|
|
12
|
|
13 @node Edebug, Syntax Errors, Debugger, Debugging
|
|
14 @section Edebug
|
|
15 @cindex Edebug debugging facility
|
|
16
|
|
17 Edebug is a source-level debugger for Emacs Lisp programs with which
|
|
18 you can:
|
|
19
|
|
20 @itemize @bullet
|
|
21 @item
|
|
22 Step through evaluation, stopping before and after each expression.
|
|
23
|
|
24 @item
|
|
25 Set conditional or unconditional breakpoints.
|
|
26
|
|
27 @item
|
|
28 Stop when a specified condition is true (the global break event).
|
|
29
|
|
30 @item
|
|
31 Trace slow or fast, stopping briefly at each stop point, or
|
|
32 at each breakpoint.
|
|
33
|
|
34 @item
|
|
35 Display expression results and evaluate expressions as if outside of
|
|
36 Edebug.
|
|
37
|
|
38 @item
|
|
39 Automatically re-evaluate a list of expressions and
|
|
40 display their results each time Edebug updates the display.
|
|
41
|
|
42 @item
|
|
43 Output trace info on function enter and exit.
|
|
44
|
|
45 @item
|
|
46 Stop when an error occurs.
|
|
47
|
|
48 @item
|
|
49 Display a backtrace, omitting Edebug's own frames.
|
|
50
|
|
51 @item
|
|
52 Specify argument evaluation for macros and defining forms.
|
|
53
|
|
54 @item
|
|
55 Obtain rudimentary coverage testing and frequency counts.
|
|
56 @end itemize
|
|
57
|
|
58 The first three sections below should tell you enough about Edebug to
|
|
59 enable you to use it.
|
|
60
|
|
61 @menu
|
|
62 * Using Edebug:: Introduction to use of Edebug.
|
|
63 * Instrumenting:: You must instrument your code
|
|
64 in order to debug it with Edebug.
|
|
65 * Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
|
|
66 * Jumping:: Commands to jump to a specified place.
|
|
67 * Misc: Edebug Misc. Miscellaneous commands.
|
|
68 * Breaks:: Setting breakpoints to make the program stop.
|
|
69 * Trapping Errors:: Trapping errors with Edebug.
|
|
70 * Views: Edebug Views. Views inside and outside of Edebug.
|
|
71 * Eval: Edebug Eval. Evaluating expressions within Edebug.
|
|
72 * Eval List:: Expressions whose values are displayed
|
|
73 each time you enter Edebug.
|
|
74 * Printing in Edebug:: Customization of printing.
|
|
75 * Trace Buffer:: How to produce trace output in a buffer.
|
|
76 * Coverage Testing:: How to test evaluation coverage.
|
|
77 * The Outside Context:: Data that Edebug saves and restores.
|
|
78 * Edebug and Macros:: Specifying how to handle macro calls.
|
|
79 * Options: Edebug Options. Option variables for customizing Edebug.
|
|
80 @end menu
|
|
81
|
|
82 @node Using Edebug
|
|
83 @subsection Using Edebug
|
|
84
|
|
85 To debug a Lisp program with Edebug, you must first @dfn{instrument}
|
|
86 the Lisp code that you want to debug. A simple way to do this is to
|
|
87 first move point into the definition of a function or macro and then do
|
|
88 @kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See
|
|
89 @ref{Instrumenting}, for alternative ways to instrument code.
|
|
90
|
|
91 Once a function is instrumented, any call to the function activates
|
|
92 Edebug. Depending on which Edebug execution mode you have selected,
|
|
93 activating Edebug may stop execution and let you step through the
|
|
94 function, or it may update the display and continue execution while
|
|
95 checking for debugging commands. The default execution mode is step,
|
|
96 which stops execution. @xref{Edebug Execution Modes}.
|
|
97
|
|
98 Within Edebug, you normally view an Emacs buffer showing the source of
|
|
99 the Lisp code you are debugging. This is referred to as the @dfn{source
|
|
100 code buffer}, and it is temporarily read-only.
|
|
101
|
|
102 An arrow in the left fringe indicates the line where the function is
|
|
103 executing. Point initially shows where within the line the function is
|
|
104 executing, but this ceases to be true if you move point yourself.
|
|
105
|
|
106 If you instrument the definition of @code{fac} (shown below) and then
|
|
107 execute @code{(fac 3)}, here is what you would normally see. Point is
|
|
108 at the open-parenthesis before @code{if}.
|
|
109
|
|
110 @example
|
|
111 (defun fac (n)
|
|
112 =>@point{}(if (< 0 n)
|
|
113 (* n (fac (1- n)))
|
|
114 1))
|
|
115 @end example
|
|
116
|
|
117 @cindex stop points
|
|
118 The places within a function where Edebug can stop execution are called
|
|
119 @dfn{stop points}. These occur both before and after each subexpression
|
|
120 that is a list, and also after each variable reference.
|
|
121 Here we use periods to show the stop points in the function
|
|
122 @code{fac}:
|
|
123
|
|
124 @example
|
|
125 (defun fac (n)
|
|
126 .(if .(< 0 n.).
|
|
127 .(* n. .(fac .(1- n.).).).
|
|
128 1).)
|
|
129 @end example
|
|
130
|
|
131 The special commands of Edebug are available in the source code buffer
|
|
132 in addition to the commands of Emacs Lisp mode. For example, you can
|
|
133 type the Edebug command @key{SPC} to execute until the next stop point.
|
|
134 If you type @key{SPC} once after entry to @code{fac}, here is the
|
|
135 display you will see:
|
|
136
|
|
137 @example
|
|
138 (defun fac (n)
|
|
139 =>(if @point{}(< 0 n)
|
|
140 (* n (fac (1- n)))
|
|
141 1))
|
|
142 @end example
|
|
143
|
|
144 When Edebug stops execution after an expression, it displays the
|
|
145 expression's value in the echo area.
|
|
146
|
|
147 Other frequently used commands are @kbd{b} to set a breakpoint at a stop
|
|
148 point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
|
|
149 exit Edebug and return to the top-level command loop. Type @kbd{?} to
|
|
150 display a list of all Edebug commands.
|
|
151
|
|
152 @node Instrumenting
|
|
153 @subsection Instrumenting for Edebug
|
|
154
|
|
155 In order to use Edebug to debug Lisp code, you must first
|
|
156 @dfn{instrument} the code. Instrumenting code inserts additional code
|
|
157 into it, to invoke Edebug at the proper places.
|
|
158
|
|
159 @kindex C-M-x
|
|
160 @findex eval-defun (Edebug)
|
|
161 When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
|
|
162 prefix argument on a function definition, it instruments the
|
|
163 definition before evaluating it. (This does not modify the source
|
|
164 code itself.) If the variable @code{edebug-all-defs} is
|
|
165 non-@code{nil}, that inverts the meaning of the prefix argument: in
|
|
166 this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
|
|
167 a prefix argument. The default value of @code{edebug-all-defs} is
|
|
168 @code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value
|
|
169 of the variable @code{edebug-all-defs}.
|
|
170
|
|
171 @findex eval-region @r{(Edebug)}
|
|
172 @findex eval-buffer @r{(Edebug)}
|
|
173 @findex eval-current-buffer @r{(Edebug)}
|
|
174 If @code{edebug-all-defs} is non-@code{nil}, then the commands
|
|
175 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
|
|
176 also instrument any definitions they evaluate. Similarly,
|
|
177 @code{edebug-all-forms} controls whether @code{eval-region} should
|
|
178 instrument @emph{any} form, even non-defining forms. This doesn't apply
|
|
179 to loading or evaluations in the minibuffer. The command @kbd{M-x
|
|
180 edebug-all-forms} toggles this option.
|
|
181
|
|
182 @findex edebug-eval-top-level-form
|
|
183 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
|
|
184 instrument any top-level form regardless of the values of
|
|
185 @code{edebug-all-defs} and @code{edebug-all-forms}.
|
|
186
|
|
187 While Edebug is active, the command @kbd{I}
|
|
188 (@code{edebug-instrument-callee}) instruments the definition of the
|
|
189 function or macro called by the list form after point, if is not already
|
|
190 instrumented. This is possible only if Edebug knows where to find the
|
|
191 source for that function; for this reading, after loading Edebug,
|
|
192 @code{eval-region} records the position of every definition it
|
|
193 evaluates, even if not instrumenting it. See also the @kbd{i} command
|
|
194 (@pxref{Jumping}), which steps into the call after instrumenting the
|
|
195 function.
|
|
196
|
|
197 Edebug knows how to instrument all the standard special forms,
|
|
198 @code{interactive} forms with an expression argument, anonymous lambda
|
|
199 expressions, and other defining forms. However, Edebug cannot determine
|
|
200 on its own what a user-defined macro will do with the arguments of a
|
|
201 macro call, so you must provide that information using Edebug
|
|
202 specifications; see @ref{Edebug and Macros}, for details.
|
|
203
|
|
204 When Edebug is about to instrument code for the first time in a
|
|
205 session, it runs the hook @code{edebug-setup-hook}, then sets it to
|
|
206 @code{nil}. You can use this to load Edebug specifications
|
|
207 associated with a package you are using, but only when you use Edebug.
|
|
208
|
|
209 @findex eval-expression @r{(Edebug)}
|
|
210 To remove instrumentation from a definition, simply re-evaluate its
|
|
211 definition in a way that does not instrument. There are two ways of
|
|
212 evaluating forms that never instrument them: from a file with
|
|
213 @code{load}, and from the minibuffer with @code{eval-expression}
|
|
214 (@kbd{M-:}).
|
|
215
|
|
216 If Edebug detects a syntax error while instrumenting, it leaves point
|
|
217 at the erroneous code and signals an @code{invalid-read-syntax} error.
|
|
218
|
|
219 @xref{Edebug Eval}, for other evaluation functions available
|
|
220 inside of Edebug.
|
|
221
|
|
222 @node Edebug Execution Modes
|
|
223 @subsection Edebug Execution Modes
|
|
224
|
|
225 @cindex Edebug execution modes
|
|
226 Edebug supports several execution modes for running the program you are
|
|
227 debugging. We call these alternatives @dfn{Edebug execution modes}; do
|
|
228 not confuse them with major or minor modes. The current Edebug execution mode
|
|
229 determines how far Edebug continues execution before stopping---whether
|
|
230 it stops at each stop point, or continues to the next breakpoint, for
|
|
231 example---and how much Edebug displays the progress of the evaluation
|
|
232 before it stops.
|
|
233
|
|
234 Normally, you specify the Edebug execution mode by typing a command to
|
|
235 continue the program in a certain mode. Here is a table of these
|
|
236 commands; all except for @kbd{S} resume execution of the program, at
|
|
237 least for a certain distance.
|
|
238
|
|
239 @table @kbd
|
|
240 @item S
|
|
241 Stop: don't execute any more of the program, but wait for more
|
|
242 Edebug commands (@code{edebug-stop}).
|
|
243
|
|
244 @item @key{SPC}
|
|
245 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
|
|
246
|
|
247 @item n
|
|
248 Next: stop at the next stop point encountered after an expression
|
|
249 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
|
|
250 @ref{Jumping}.
|
|
251
|
|
252 @item t
|
|
253 Trace: pause (normally one second) at each Edebug stop point
|
|
254 (@code{edebug-trace-mode}).
|
|
255
|
|
256 @item T
|
|
257 Rapid trace: update the display at each stop point, but don't actually
|
|
258 pause (@code{edebug-Trace-fast-mode}).
|
|
259
|
|
260 @item g
|
|
261 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
|
|
262
|
|
263 @item c
|
|
264 Continue: pause one second at each breakpoint, and then continue
|
|
265 (@code{edebug-continue-mode}).
|
|
266
|
|
267 @item C
|
|
268 Rapid continue: move point to each breakpoint, but don't pause
|
|
269 (@code{edebug-Continue-fast-mode}).
|
|
270
|
|
271 @item G
|
|
272 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
|
|
273 can still stop the program by typing @kbd{S}, or any editing command.
|
|
274 @end table
|
|
275
|
|
276 In general, the execution modes earlier in the above list run the
|
|
277 program more slowly or stop sooner than the modes later in the list.
|
|
278
|
|
279 While executing or tracing, you can interrupt the execution by typing
|
|
280 any Edebug command. Edebug stops the program at the next stop point and
|
|
281 then executes the command you typed. For example, typing @kbd{t} during
|
|
282 execution switches to trace mode at the next stop point. You can use
|
|
283 @kbd{S} to stop execution without doing anything else.
|
|
284
|
|
285 If your function happens to read input, a character you type intending
|
|
286 to interrupt execution may be read by the function instead. You can
|
|
287 avoid such unintended results by paying attention to when your program
|
|
288 wants input.
|
|
289
|
|
290 @cindex keyboard macros (Edebug)
|
|
291 Keyboard macros containing the commands in this section do not
|
|
292 completely work: exiting from Edebug, to resume the program, loses track
|
|
293 of the keyboard macro. This is not easy to fix. Also, defining or
|
|
294 executing a keyboard macro outside of Edebug does not affect commands
|
|
295 inside Edebug. This is usually an advantage. See also the
|
|
296 @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
|
|
297
|
|
298 When you enter a new Edebug level, the initial execution mode comes
|
|
299 from the value of the variable @code{edebug-initial-mode}.
|
|
300 (@xref{Edebug Options}.) By default, this specifies step mode. Note
|
|
301 that you may reenter the same Edebug level several times if, for
|
|
302 example, an instrumented function is called several times from one
|
|
303 command.
|
|
304
|
|
305 @defopt edebug-sit-for-seconds
|
|
306 This option specifies how many seconds to wait between execution steps
|
|
307 in trace mode. The default is 1 second.
|
|
308 @end defopt
|
|
309
|
|
310 @node Jumping
|
|
311 @subsection Jumping
|
|
312
|
|
313 The commands described in this section execute until they reach a
|
|
314 specified location. All except @kbd{i} make a temporary breakpoint to
|
|
315 establish the place to stop, then switch to go mode. Any other
|
|
316 breakpoint reached before the intended stop point will also stop
|
|
317 execution. @xref{Breakpoints}, for the details on breakpoints.
|
|
318
|
|
319 These commands may fail to work as expected in case of nonlocal exit,
|
|
320 as that can bypass the temporary breakpoint where you expected the
|
|
321 program to stop.
|
|
322
|
|
323 @table @kbd
|
|
324 @item h
|
|
325 Proceed to the stop point near where point is (@code{edebug-goto-here}).
|
|
326
|
|
327 @item f
|
|
328 Run the program for one expression
|
|
329 (@code{edebug-forward-sexp}).
|
|
330
|
|
331 @item o
|
|
332 Run the program until the end of the containing sexp.
|
|
333
|
|
334 @item i
|
|
335 Step into the function or macro called by the form after point.
|
|
336 @end table
|
|
337
|
|
338 The @kbd{h} command proceeds to the stop point at or after the current
|
|
339 location of point, using a temporary breakpoint.
|
|
340
|
|
341 The @kbd{f} command runs the program forward over one expression. More
|
|
342 precisely, it sets a temporary breakpoint at the position that
|
|
343 @kbd{C-M-f} would reach, then executes in go mode so that the program
|
|
344 will stop at breakpoints.
|
|
345
|
|
346 With a prefix argument @var{n}, the temporary breakpoint is placed
|
|
347 @var{n} sexps beyond point. If the containing list ends before @var{n}
|
|
348 more elements, then the place to stop is after the containing
|
|
349 expression.
|
|
350
|
|
351 You must check that the position @kbd{C-M-f} finds is a place that the
|
|
352 program will really get to. In @code{cond}, for example, this may not
|
|
353 be true.
|
|
354
|
|
355 For flexibility, the @kbd{f} command does @code{forward-sexp} starting
|
|
356 at point, rather than at the stop point. If you want to execute one
|
|
357 expression @emph{from the current stop point}, first type @kbd{w}, to
|
|
358 move point there, and then type @kbd{f}.
|
|
359
|
|
360 The @kbd{o} command continues ``out of'' an expression. It places a
|
|
361 temporary breakpoint at the end of the sexp containing point. If the
|
|
362 containing sexp is a function definition itself, @kbd{o} continues until
|
|
363 just before the last sexp in the definition. If that is where you are
|
|
364 now, it returns from the function and then stops. In other words, this
|
|
365 command does not exit the currently executing function unless you are
|
|
366 positioned after the last sexp.
|
|
367
|
|
368 The @kbd{i} command steps into the function or macro called by the list
|
|
369 form after point, and stops at its first stop point. Note that the form
|
|
370 need not be the one about to be evaluated. But if the form is a
|
|
371 function call about to be evaluated, remember to use this command before
|
|
372 any of the arguments are evaluated, since otherwise it will be too late.
|
|
373
|
|
374 The @kbd{i} command instruments the function or macro it's supposed to
|
|
375 step into, if it isn't instrumented already. This is convenient, but keep
|
|
376 in mind that the function or macro remains instrumented unless you explicitly
|
|
377 arrange to deinstrument it.
|
|
378
|
|
379 @node Edebug Misc
|
|
380 @subsection Miscellaneous Edebug Commands
|
|
381
|
|
382 Some miscellaneous Edebug commands are described here.
|
|
383
|
|
384 @table @kbd
|
|
385 @item ?
|
|
386 Display the help message for Edebug (@code{edebug-help}).
|
|
387
|
|
388 @item C-]
|
|
389 Abort one level back to the previous command level
|
|
390 (@code{abort-recursive-edit}).
|
|
391
|
|
392 @item q
|
|
393 Return to the top level editor command loop (@code{top-level}). This
|
|
394 exits all recursive editing levels, including all levels of Edebug
|
|
395 activity. However, instrumented code protected with
|
|
396 @code{unwind-protect} or @code{condition-case} forms may resume
|
|
397 debugging.
|
|
398
|
|
399 @item Q
|
|
400 Like @kbd{q}, but don't stop even for protected code
|
|
401 (@code{top-level-nonstop}).
|
|
402
|
|
403 @item r
|
|
404 Redisplay the most recently known expression result in the echo area
|
|
405 (@code{edebug-previous-result}).
|
|
406
|
|
407 @item d
|
|
408 Display a backtrace, excluding Edebug's own functions for clarity
|
|
409 (@code{edebug-backtrace}).
|
|
410
|
|
411 You cannot use debugger commands in the backtrace buffer in Edebug as
|
|
412 you would in the standard debugger.
|
|
413
|
|
414 The backtrace buffer is killed automatically when you continue
|
|
415 execution.
|
|
416 @end table
|
|
417
|
|
418 You can invoke commands from Edebug that activate Edebug again
|
|
419 recursively. Whenever Edebug is active, you can quit to the top level
|
|
420 with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can
|
|
421 display a backtrace of all the pending evaluations with @kbd{d}.
|
|
422
|
|
423 @node Breaks
|
|
424 @subsection Breaks
|
|
425
|
|
426 Edebug's step mode stops execution when the next stop point is reached.
|
|
427 There are three other ways to stop Edebug execution once it has started:
|
|
428 breakpoints, the global break condition, and source breakpoints.
|
|
429
|
|
430 @menu
|
|
431 * Breakpoints:: Breakpoints at stop points.
|
|
432 * Global Break Condition:: Breaking on an event.
|
|
433 * Source Breakpoints:: Embedding breakpoints in source code.
|
|
434 @end menu
|
|
435
|
|
436 @node Breakpoints
|
|
437 @subsubsection Edebug Breakpoints
|
|
438
|
|
439 @cindex breakpoints (Edebug)
|
|
440 While using Edebug, you can specify @dfn{breakpoints} in the program you
|
|
441 are testing: these are places where execution should stop. You can set a
|
|
442 breakpoint at any stop point, as defined in @ref{Using Edebug}. For
|
|
443 setting and unsetting breakpoints, the stop point that is affected is
|
|
444 the first one at or after point in the source code buffer. Here are the
|
|
445 Edebug commands for breakpoints:
|
|
446
|
|
447 @table @kbd
|
|
448 @item b
|
|
449 Set a breakpoint at the stop point at or after point
|
|
450 (@code{edebug-set-breakpoint}). If you use a prefix argument, the
|
|
451 breakpoint is temporary---it turns off the first time it stops the
|
|
452 program.
|
|
453
|
|
454 @item u
|
|
455 Unset the breakpoint (if any) at the stop point at or after
|
|
456 point (@code{edebug-unset-breakpoint}).
|
|
457
|
|
458 @item x @var{condition} @key{RET}
|
|
459 Set a conditional breakpoint which stops the program only if
|
|
460 evaluating @var{condition} produces a non-@code{nil} value
|
|
461 (@code{edebug-set-conditional-breakpoint}). With a prefix argument,
|
|
462 the breakpoint is temporary.
|
|
463
|
|
464 @item B
|
|
465 Move point to the next breakpoint in the current definition
|
|
466 (@code{edebug-next-breakpoint}).
|
|
467 @end table
|
|
468
|
|
469 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
|
|
470 with @kbd{u}. First move point to the Edebug stop point of your choice,
|
|
471 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
|
|
472 Unsetting a breakpoint where none has been set has no effect.
|
|
473
|
|
474 Re-evaluating or reinstrumenting a definition removes all of its
|
|
475 previous breakpoints.
|
|
476
|
|
477 A @dfn{conditional breakpoint} tests a condition each time the program
|
|
478 gets there. Any errors that occur as a result of evaluating the
|
|
479 condition are ignored, as if the result were @code{nil}. To set a
|
|
480 conditional breakpoint, use @kbd{x}, and specify the condition
|
|
481 expression in the minibuffer. Setting a conditional breakpoint at a
|
|
482 stop point that has a previously established conditional breakpoint puts
|
|
483 the previous condition expression in the minibuffer so you can edit it.
|
|
484
|
|
485 You can make a conditional or unconditional breakpoint
|
|
486 @dfn{temporary} by using a prefix argument with the command to set the
|
|
487 breakpoint. When a temporary breakpoint stops the program, it is
|
|
488 automatically unset.
|
|
489
|
|
490 Edebug always stops or pauses at a breakpoint, except when the Edebug
|
|
491 mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
|
|
492
|
|
493 To find out where your breakpoints are, use the @kbd{B} command, which
|
|
494 moves point to the next breakpoint following point, within the same
|
|
495 function, or to the first breakpoint if there are no following
|
|
496 breakpoints. This command does not continue execution---it just moves
|
|
497 point in the buffer.
|
|
498
|
|
499 @node Global Break Condition
|
|
500 @subsubsection Global Break Condition
|
|
501
|
|
502 @cindex stopping on events
|
|
503 @cindex global break condition
|
|
504 A @dfn{global break condition} stops execution when a specified
|
|
505 condition is satisfied, no matter where that may occur. Edebug
|
|
506 evaluates the global break condition at every stop point; if it
|
|
507 evaluates to a non-@code{nil} value, then execution stops or pauses
|
|
508 depending on the execution mode, as if a breakpoint had been hit. If
|
|
509 evaluating the condition gets an error, execution does not stop.
|
|
510
|
|
511 @findex edebug-set-global-break-condition
|
|
512 The condition expression is stored in
|
|
513 @code{edebug-global-break-condition}. You can specify a new expression
|
|
514 using the @kbd{X} command from the source code buffer while Edebug is
|
|
515 active, or using @kbd{C-x X X} from any buffer at any time, as long as
|
|
516 Edebug is loaded (@code{edebug-set-global-break-condition}).
|
|
517
|
|
518 The global break condition is the simplest way to find where in your
|
|
519 code some event occurs, but it makes code run much more slowly. So you
|
|
520 should reset the condition to @code{nil} when not using it.
|
|
521
|
|
522 @node Source Breakpoints
|
|
523 @subsubsection Source Breakpoints
|
|
524
|
|
525 @findex edebug
|
|
526 @cindex source breakpoints
|
|
527 All breakpoints in a definition are forgotten each time you
|
|
528 reinstrument it. If you wish to make a breakpoint that won't be
|
|
529 forgotten, you can write a @dfn{source breakpoint}, which is simply a
|
|
530 call to the function @code{edebug} in your source code. You can, of
|
|
531 course, make such a call conditional. For example, in the @code{fac}
|
|
532 function, you can insert the first line as shown below, to stop when the
|
|
533 argument reaches zero:
|
|
534
|
|
535 @example
|
|
536 (defun fac (n)
|
|
537 (if (= n 0) (edebug))
|
|
538 (if (< 0 n)
|
|
539 (* n (fac (1- n)))
|
|
540 1))
|
|
541 @end example
|
|
542
|
|
543 When the @code{fac} definition is instrumented and the function is
|
|
544 called, the call to @code{edebug} acts as a breakpoint. Depending on
|
|
545 the execution mode, Edebug stops or pauses there.
|
|
546
|
|
547 If no instrumented code is being executed when @code{edebug} is called,
|
|
548 that function calls @code{debug}.
|
|
549 @c This may not be a good idea anymore.
|
|
550
|
|
551 @node Trapping Errors
|
|
552 @subsection Trapping Errors
|
|
553
|
|
554 Emacs normally displays an error message when an error is signaled and
|
|
555 not handled with @code{condition-case}. While Edebug is active and
|
|
556 executing instrumented code, it normally responds to all unhandled
|
|
557 errors. You can customize this with the options @code{edebug-on-error}
|
|
558 and @code{edebug-on-quit}; see @ref{Edebug Options}.
|
|
559
|
|
560 When Edebug responds to an error, it shows the last stop point
|
|
561 encountered before the error. This may be the location of a call to a
|
|
562 function which was not instrumented, and within which the error actually
|
|
563 occurred. For an unbound variable error, the last known stop point
|
|
564 might be quite distant from the offending variable reference. In that
|
|
565 case, you might want to display a full backtrace (@pxref{Edebug Misc}).
|
|
566
|
|
567 @c Edebug should be changed for the following: -- dan
|
|
568 If you change @code{debug-on-error} or @code{debug-on-quit} while
|
|
569 Edebug is active, these changes will be forgotten when Edebug becomes
|
|
570 inactive. Furthermore, during Edebug's recursive edit, these variables
|
|
571 are bound to the values they had outside of Edebug.
|
|
572
|
|
573 @node Edebug Views
|
|
574 @subsection Edebug Views
|
|
575
|
|
576 These Edebug commands let you view aspects of the buffer and window
|
|
577 status as they were before entry to Edebug. The outside window
|
|
578 configuration is the collection of windows and contents that were in
|
|
579 effect outside of Edebug.
|
|
580
|
|
581 @table @kbd
|
|
582 @item v
|
|
583 Switch to viewing the outside window configuration
|
|
584 (@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
|
|
585
|
|
586 @item p
|
|
587 Temporarily display the outside current buffer with point at its
|
|
588 outside position (@code{edebug-bounce-point}), pausing for one second
|
|
589 before returning to Edebug. With a prefix argument @var{n}, pause for
|
|
590 @var{n} seconds instead.
|
|
591
|
|
592 @item w
|
|
593 Move point back to the current stop point in the source code buffer
|
|
594 (@code{edebug-where}).
|
|
595
|
|
596 If you use this command in a different window displaying the same
|
|
597 buffer, that window will be used instead to display the current
|
|
598 definition in the future.
|
|
599
|
|
600 @item W
|
|
601 @c Its function is not simply to forget the saved configuration -- dan
|
|
602 Toggle whether Edebug saves and restores the outside window
|
|
603 configuration (@code{edebug-toggle-save-windows}).
|
|
604
|
|
605 With a prefix argument, @code{W} only toggles saving and restoring of
|
|
606 the selected window. To specify a window that is not displaying the
|
|
607 source code buffer, you must use @kbd{C-x X W} from the global keymap.
|
|
608 @end table
|
|
609
|
|
610 You can view the outside window configuration with @kbd{v} or just
|
|
611 bounce to the point in the current buffer with @kbd{p}, even if
|
|
612 it is not normally displayed.
|
|
613
|
|
614 After moving point, you may wish to jump back to the stop point.
|
|
615 You can do that with @kbd{w} from a source code buffer. You can jump
|
|
616 back to the stop point in the source code buffer from any buffer using
|
|
617 @kbd{C-x X w}.
|
|
618
|
|
619 Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
|
|
620 saved outside window configuration---so that even if you turn saving
|
|
621 back @emph{on}, the current window configuration remains unchanged when
|
|
622 you next exit Edebug (by continuing the program). However, the
|
|
623 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
|
|
624 conflict with the buffers you wish to see unless you have enough windows
|
|
625 open.
|
|
626
|
|
627 @node Edebug Eval
|
|
628 @subsection Evaluation
|
|
629
|
|
630 While within Edebug, you can evaluate expressions ``as if'' Edebug
|
|
631 were not running. Edebug tries to be invisible to the expression's
|
|
632 evaluation and printing. Evaluation of expressions that cause side
|
|
633 effects will work as expected, except for changes to data that Edebug
|
|
634 explicitly saves and restores. @xref{The Outside Context}, for details
|
|
635 on this process.
|
|
636
|
|
637 @table @kbd
|
|
638 @item e @var{exp} @key{RET}
|
|
639 Evaluate expression @var{exp} in the context outside of Edebug
|
|
640 (@code{edebug-eval-expression}). That is, Edebug tries to minimize its
|
|
641 interference with the evaluation.
|
|
642
|
|
643 @item M-: @var{exp} @key{RET}
|
|
644 Evaluate expression @var{exp} in the context of Edebug itself.
|
|
645
|
|
646 @item C-x C-e
|
|
647 Evaluate the expression before point, in the context outside of Edebug
|
|
648 (@code{edebug-eval-last-sexp}).
|
|
649 @end table
|
|
650
|
|
651 @cindex lexical binding (Edebug)
|
|
652 Edebug supports evaluation of expressions containing references to
|
|
653 lexically bound symbols created by the following constructs in
|
|
654 @file{cl.el} (version 2.03 or later): @code{lexical-let},
|
|
655 @code{macrolet}, and @code{symbol-macrolet}.
|
|
656
|
|
657 @node Eval List
|
|
658 @subsection Evaluation List Buffer
|
|
659
|
|
660 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
|
|
661 evaluate expressions interactively. You can also set up the
|
|
662 @dfn{evaluation list} of expressions to be evaluated automatically each
|
|
663 time Edebug updates the display.
|
|
664
|
|
665 @table @kbd
|
|
666 @item E
|
|
667 Switch to the evaluation list buffer @samp{*edebug*}
|
|
668 (@code{edebug-visit-eval-list}).
|
|
669 @end table
|
|
670
|
|
671 In the @samp{*edebug*} buffer you can use the commands of Lisp
|
|
672 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
|
|
673 Manual}) as well as these special commands:
|
|
674
|
|
675 @table @kbd
|
|
676 @item C-j
|
|
677 Evaluate the expression before point, in the outside context, and insert
|
|
678 the value in the buffer (@code{edebug-eval-print-last-sexp}).
|
|
679
|
|
680 @item C-x C-e
|
|
681 Evaluate the expression before point, in the context outside of Edebug
|
|
682 (@code{edebug-eval-last-sexp}).
|
|
683
|
|
684 @item C-c C-u
|
|
685 Build a new evaluation list from the contents of the buffer
|
|
686 (@code{edebug-update-eval-list}).
|
|
687
|
|
688 @item C-c C-d
|
|
689 Delete the evaluation list group that point is in
|
|
690 (@code{edebug-delete-eval-item}).
|
|
691
|
|
692 @item C-c C-w
|
|
693 Switch back to the source code buffer at the current stop point
|
|
694 (@code{edebug-where}).
|
|
695 @end table
|
|
696
|
|
697 You can evaluate expressions in the evaluation list window with
|
|
698 @kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
|
|
699 but they are evaluated in the context outside of Edebug.
|
|
700
|
|
701 The expressions you enter interactively (and their results) are lost
|
|
702 when you continue execution; but you can set up an @dfn{evaluation list}
|
|
703 consisting of expressions to be evaluated each time execution stops.
|
|
704
|
|
705 @cindex evaluation list group
|
|
706 To do this, write one or more @dfn{evaluation list groups} in the
|
|
707 evaluation list buffer. An evaluation list group consists of one or
|
|
708 more Lisp expressions. Groups are separated by comment lines.
|
|
709
|
|
710 The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
|
|
711 evaluation list, scanning the buffer and using the first expression of
|
|
712 each group. (The idea is that the second expression of the group is the
|
|
713 value previously computed and displayed.)
|
|
714
|
|
715 Each entry to Edebug redisplays the evaluation list by inserting each
|
|
716 expression in the buffer, followed by its current value. It also
|
|
717 inserts comment lines so that each expression becomes its own group.
|
|
718 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
|
|
719 the evaluation list is effectively unchanged.
|
|
720
|
|
721 If an error occurs during an evaluation from the evaluation list, the
|
|
722 error message is displayed in a string as if it were the result.
|
|
723 Therefore, expressions that use variables not currently valid do not
|
|
724 interrupt your debugging.
|
|
725
|
|
726 Here is an example of what the evaluation list window looks like after
|
|
727 several expressions have been added to it:
|
|
728
|
|
729 @smallexample
|
|
730 (current-buffer)
|
|
731 #<buffer *scratch*>
|
|
732 ;---------------------------------------------------------------
|
|
733 (selected-window)
|
|
734 #<window 16 on *scratch*>
|
|
735 ;---------------------------------------------------------------
|
|
736 (point)
|
|
737 196
|
|
738 ;---------------------------------------------------------------
|
|
739 bad-var
|
|
740 "Symbol's value as variable is void: bad-var"
|
|
741 ;---------------------------------------------------------------
|
|
742 (recursion-depth)
|
|
743 0
|
|
744 ;---------------------------------------------------------------
|
|
745 this-command
|
|
746 eval-last-sexp
|
|
747 ;---------------------------------------------------------------
|
|
748 @end smallexample
|
|
749
|
|
750 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
|
|
751 delete the text for the group and update the evaluation list with
|
|
752 @kbd{C-c C-u}. To add a new expression to the evaluation list, insert
|
|
753 the expression at a suitable place, insert a new comment line, then type
|
|
754 @kbd{C-c C-u}. You need not insert dashes in the comment line---its
|
|
755 contents don't matter.
|
|
756
|
|
757 After selecting @samp{*edebug*}, you can return to the source code
|
|
758 buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
|
|
759 you continue execution, and recreated next time it is needed.
|
|
760
|
|
761 @node Printing in Edebug
|
|
762 @subsection Printing in Edebug
|
|
763
|
|
764 @cindex printing (Edebug)
|
|
765 @cindex printing circular structures
|
|
766 @pindex cust-print
|
|
767 If an expression in your program produces a value containing circular
|
|
768 list structure, you may get an error when Edebug attempts to print it.
|
|
769
|
|
770 One way to cope with circular structure is to set @code{print-length}
|
|
771 or @code{print-level} to truncate the printing. Edebug does this for
|
|
772 you; it binds @code{print-length} and @code{print-level} to 50 if they
|
|
773 were @code{nil}. (Actually, the variables @code{edebug-print-length}
|
|
774 and @code{edebug-print-level} specify the values to use within Edebug.)
|
|
775 @xref{Output Variables}.
|
|
776
|
|
777 @defopt edebug-print-length
|
|
778 If non-@code{nil}, Edebug binds @code{print-length} to this value while
|
|
779 printing results. The default value is @code{50}.
|
|
780 @end defopt
|
|
781
|
|
782 @defopt edebug-print-level
|
|
783 If non-@code{nil}, Edebug binds @code{print-level} to this value while
|
|
784 printing results. The default value is @code{50}.
|
|
785 @end defopt
|
|
786
|
|
787 You can also print circular structures and structures that share
|
|
788 elements more informatively by binding @code{print-circle}
|
|
789 to a non-@code{nil} value.
|
|
790
|
|
791 Here is an example of code that creates a circular structure:
|
|
792
|
|
793 @example
|
|
794 (setq a '(x y))
|
|
795 (setcar a a)
|
|
796 @end example
|
|
797
|
|
798 @noindent
|
|
799 Custom printing prints this as @samp{Result: #1=(#1# y)}. The
|
|
800 @samp{#1=} notation labels the structure that follows it with the label
|
|
801 @samp{1}, and the @samp{#1#} notation references the previously labeled
|
|
802 structure. This notation is used for any shared elements of lists or
|
|
803 vectors.
|
|
804
|
|
805 @defopt edebug-print-circle
|
|
806 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
|
|
807 printing results. The default value is @code{t}.
|
|
808 @end defopt
|
|
809
|
|
810 Other programs can also use custom printing; see @file{cust-print.el}
|
|
811 for details.
|
|
812
|
|
813 @node Trace Buffer
|
|
814 @subsection Trace Buffer
|
|
815 @cindex trace buffer
|
|
816
|
|
817 Edebug can record an execution trace, storing it in a buffer named
|
|
818 @samp{*edebug-trace*}. This is a log of function calls and returns,
|
|
819 showing the function names and their arguments and values. To enable
|
|
820 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
|
|
821
|
|
822 Making a trace buffer is not the same thing as using trace execution
|
|
823 mode (@pxref{Edebug Execution Modes}).
|
|
824
|
|
825 When trace recording is enabled, each function entry and exit adds
|
|
826 lines to the trace buffer. A function entry record consists of
|
|
827 @samp{::::@{}, followed by the function name and argument values. A
|
|
828 function exit record consists of @samp{::::@}}, followed by the function
|
|
829 name and result of the function.
|
|
830
|
|
831 The number of @samp{:}s in an entry shows its recursion depth. You
|
|
832 can use the braces in the trace buffer to find the matching beginning or
|
|
833 end of function calls.
|
|
834
|
|
835 @findex edebug-print-trace-before
|
|
836 @findex edebug-print-trace-after
|
|
837 You can customize trace recording for function entry and exit by
|
|
838 redefining the functions @code{edebug-print-trace-before} and
|
|
839 @code{edebug-print-trace-after}.
|
|
840
|
|
841 @defmac edebug-tracing string body@dots{}
|
|
842 This macro requests additional trace information around the execution
|
|
843 of the @var{body} forms. The argument @var{string} specifies text
|
|
844 to put in the trace buffer, after the @samp{@{} or @samp{@}}. All
|
|
845 the arguments are evaluated, and @code{edebug-tracing} returns the
|
|
846 value of the last form in @var{body}.
|
|
847 @end defmac
|
|
848
|
|
849 @defun edebug-trace format-string &rest format-args
|
|
850 This function inserts text in the trace buffer. It computes the text
|
|
851 with @code{(apply 'format @var{format-string} @var{format-args})}.
|
|
852 It also appends a newline to separate entries.
|
|
853 @end defun
|
|
854
|
|
855 @code{edebug-tracing} and @code{edebug-trace} insert lines in the
|
|
856 trace buffer whenever they are called, even if Edebug is not active.
|
|
857 Adding text to the trace buffer also scrolls its window to show the last
|
|
858 lines inserted.
|
|
859
|
|
860 @node Coverage Testing
|
|
861 @subsection Coverage Testing
|
|
862
|
|
863 @cindex coverage testing (Edebug)
|
|
864 @cindex frequency counts
|
|
865 @cindex performance analysis
|
|
866 Edebug provides rudimentary coverage testing and display of execution
|
|
867 frequency.
|
|
868
|
|
869 Coverage testing works by comparing the result of each expression with
|
|
870 the previous result; each form in the program is considered ``covered''
|
|
871 if it has returned two different values since you began testing coverage
|
|
872 in the current Emacs session. Thus, to do coverage testing on your
|
|
873 program, execute it under various conditions and note whether it behaves
|
|
874 correctly; Edebug will tell you when you have tried enough different
|
|
875 conditions that each form has returned two different values.
|
|
876
|
|
877 Coverage testing makes execution slower, so it is only done if
|
|
878 @code{edebug-test-coverage} is non-@code{nil}. Frequency counting is
|
|
879 performed for all execution of an instrumented function, even if the
|
|
880 execution mode is Go-nonstop, and regardless of whether coverage testing
|
|
881 is enabled.
|
|
882
|
|
883 @kindex C-x X =
|
|
884 @findex edebug-temp-display-freq-count
|
|
885 Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
|
|
886 the coverage information and the frequency counts for a definition.
|
|
887 Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
|
|
888 information temporarily, only until you type another key.
|
|
889
|
|
890 @deffn Command edebug-display-freq-count
|
|
891 This command displays the frequency count data for each line of the
|
|
892 current definition.
|
|
893
|
|
894 The frequency counts appear as comment lines after each line of code,
|
|
895 and you can undo all insertions with one @code{undo} command. The
|
|
896 counts appear under the @samp{(} before an expression or the @samp{)}
|
|
897 after an expression, or on the last character of a variable. To
|
|
898 simplify the display, a count is not shown if it is equal to the
|
|
899 count of an earlier expression on the same line.
|
|
900
|
|
901 The character @samp{=} following the count for an expression says that
|
|
902 the expression has returned the same value each time it was evaluated.
|
|
903 In other words, it is not yet ``covered'' for coverage testing purposes.
|
|
904
|
|
905 To clear the frequency count and coverage data for a definition,
|
|
906 simply reinstrument it with @code{eval-defun}.
|
|
907 @end deffn
|
|
908
|
|
909 For example, after evaluating @code{(fac 5)} with a source
|
|
910 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
|
|
911 the breakpoint is reached, the frequency data looks like this:
|
|
912
|
|
913 @example
|
|
914 (defun fac (n)
|
|
915 (if (= n 0) (edebug))
|
|
916 ;#6 1 = =5
|
|
917 (if (< 0 n)
|
|
918 ;#5 =
|
|
919 (* n (fac (1- n)))
|
|
920 ;# 5 0
|
|
921 1))
|
|
922 ;# 0
|
|
923 @end example
|
|
924
|
|
925 The comment lines show that @code{fac} was called 6 times. The
|
|
926 first @code{if} statement returned 5 times with the same result each
|
|
927 time; the same is true of the condition on the second @code{if}.
|
|
928 The recursive call of @code{fac} did not return at all.
|
|
929
|
|
930
|
|
931 @node The Outside Context
|
|
932 @subsection The Outside Context
|
|
933
|
|
934 Edebug tries to be transparent to the program you are debugging, but it
|
|
935 does not succeed completely. Edebug also tries to be transparent when
|
|
936 you evaluate expressions with @kbd{e} or with the evaluation list
|
|
937 buffer, by temporarily restoring the outside context. This section
|
|
938 explains precisely what context Edebug restores, and how Edebug fails to
|
|
939 be completely transparent.
|
|
940
|
|
941 @menu
|
|
942 * Checking Whether to Stop:: When Edebug decides what to do.
|
|
943 * Edebug Display Update:: When Edebug updates the display.
|
|
944 * Edebug Recursive Edit:: When Edebug stops execution.
|
|
945 @end menu
|
|
946
|
|
947 @node Checking Whether to Stop
|
|
948 @subsubsection Checking Whether to Stop
|
|
949
|
|
950 Whenever Edebug is entered, it needs to save and restore certain data
|
|
951 before even deciding whether to make trace information or stop the
|
|
952 program.
|
|
953
|
|
954 @itemize @bullet
|
|
955 @item
|
|
956 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
|
|
957 incremented once to reduce Edebug's impact on the stack. You could,
|
|
958 however, still run out of stack space when using Edebug.
|
|
959
|
|
960 @item
|
|
961 The state of keyboard macro execution is saved and restored. While
|
|
962 Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
|
|
963 unless @code{edebug-continue-kbd-macro} is non-@code{nil}.
|
|
964 @end itemize
|
|
965
|
|
966
|
|
967 @node Edebug Display Update
|
|
968 @subsubsection Edebug Display Update
|
|
969
|
|
970 @c This paragraph is not filled, because LaLiberte's conversion script
|
|
971 @c needs an xref to be on just one line.
|
|
972 When Edebug needs to display something (e.g., in trace mode), it saves
|
|
973 the current window configuration from ``outside'' Edebug
|
|
974 (@pxref{Window Configurations}). When you exit Edebug (by continuing
|
|
975 the program), it restores the previous window configuration.
|
|
976
|
|
977 Emacs redisplays only when it pauses. Usually, when you continue
|
|
978 execution, the program re-enters Edebug at a breakpoint or after
|
|
979 stepping, without pausing or reading input in between. In such cases,
|
|
980 Emacs never gets a chance to redisplay the ``outside'' configuration.
|
|
981 Consequently, what you see is the same window configuration as the last
|
|
982 time Edebug was active, with no interruption.
|
|
983
|
|
984 Entry to Edebug for displaying something also saves and restores the
|
|
985 following data (though some of them are deliberately not restored if an
|
|
986 error or quit signal occurs).
|
|
987
|
|
988 @itemize @bullet
|
|
989 @item
|
|
990 @cindex current buffer point and mark (Edebug)
|
|
991 Which buffer is current, and the positions of point and the mark in the
|
|
992 current buffer, are saved and restored.
|
|
993
|
|
994 @item
|
|
995 @cindex window configuration (Edebug)
|
|
996 The outside window configuration is saved and restored if
|
|
997 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}).
|
|
998
|
|
999 The window configuration is not restored on error or quit, but the
|
|
1000 outside selected window @emph{is} reselected even on error or quit in
|
|
1001 case a @code{save-excursion} is active. If the value of
|
|
1002 @code{edebug-save-windows} is a list, only the listed windows are saved
|
|
1003 and restored.
|
|
1004
|
|
1005 The window start and horizontal scrolling of the source code buffer are
|
|
1006 not restored, however, so that the display remains coherent within Edebug.
|
|
1007
|
|
1008 @item
|
|
1009 The value of point in each displayed buffer is saved and restored if
|
|
1010 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
|
|
1011
|
|
1012 @item
|
|
1013 The variables @code{overlay-arrow-position} and
|
|
1014 @code{overlay-arrow-string} are saved and restored. So you can safely
|
|
1015 invoke Edebug from the recursive edit elsewhere in the same buffer.
|
|
1016
|
|
1017 @item
|
|
1018 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
|
|
1019 the cursor shows up in the window.
|
|
1020 @end itemize
|
|
1021
|
|
1022 @node Edebug Recursive Edit
|
|
1023 @subsubsection Edebug Recursive Edit
|
|
1024
|
|
1025 When Edebug is entered and actually reads commands from the user, it
|
|
1026 saves (and later restores) these additional data:
|
|
1027
|
|
1028 @itemize @bullet
|
|
1029 @item
|
|
1030 The current match data. @xref{Match Data}.
|
|
1031
|
|
1032 @item
|
|
1033 The variables @code{last-command}, @code{this-command},
|
|
1034 @code{last-input-event}, @code{last-command-event},
|
|
1035 @code{last-event-frame}, @code{last-nonmenu-event}, and
|
|
1036 @code{track-mouse}. Commands used within Edebug do not affect these
|
|
1037 variables outside of Edebug.
|
|
1038
|
|
1039 Executing commands within Edebug can change the key sequence that
|
|
1040 would be returned by @code{this-command-keys}, and there is no way to
|
|
1041 reset the key sequence from Lisp.
|
|
1042
|
|
1043 Edebug cannot save and restore the value of
|
|
1044 @code{unread-command-events}. Entering Edebug while this variable has a
|
|
1045 nontrivial value can interfere with execution of the program you are
|
|
1046 debugging.
|
|
1047
|
|
1048 @item
|
|
1049 Complex commands executed while in Edebug are added to the variable
|
|
1050 @code{command-history}. In rare cases this can alter execution.
|
|
1051
|
|
1052 @item
|
|
1053 Within Edebug, the recursion depth appears one deeper than the recursion
|
|
1054 depth outside Edebug. This is not true of the automatically updated
|
|
1055 evaluation list window.
|
|
1056
|
|
1057 @item
|
|
1058 @code{standard-output} and @code{standard-input} are bound to @code{nil}
|
|
1059 by the @code{recursive-edit}, but Edebug temporarily restores them during
|
|
1060 evaluations.
|
|
1061
|
|
1062 @item
|
|
1063 The state of keyboard macro definition is saved and restored. While
|
|
1064 Edebug is active, @code{defining-kbd-macro} is bound to
|
|
1065 @code{edebug-continue-kbd-macro}.
|
|
1066 @end itemize
|
|
1067
|
|
1068 @node Edebug and Macros
|
|
1069 @subsection Edebug and Macros
|
|
1070
|
|
1071 To make Edebug properly instrument expressions that call macros, some
|
|
1072 extra care is needed. This subsection explains the details.
|
|
1073
|
|
1074 @menu
|
|
1075 * Instrumenting Macro Calls:: The basic problem.
|
|
1076 * Specification List:: How to specify complex patterns of evaluation.
|
|
1077 * Backtracking:: What Edebug does when matching fails.
|
|
1078 * Specification Examples:: To help understand specifications.
|
|
1079 @end menu
|
|
1080
|
|
1081 @node Instrumenting Macro Calls
|
|
1082 @subsubsection Instrumenting Macro Calls
|
|
1083
|
|
1084 When Edebug instruments an expression that calls a Lisp macro, it needs
|
|
1085 additional information about the macro to do the job properly. This is
|
|
1086 because there is no a-priori way to tell which subexpressions of the
|
|
1087 macro call are forms to be evaluated. (Evaluation may occur explicitly
|
|
1088 in the macro body, or when the resulting expansion is evaluated, or any
|
|
1089 time later.)
|
|
1090
|
|
1091 Therefore, you must define an Edebug specification for each macro
|
|
1092 that Edebug will encounter, to explain the format of calls to that
|
|
1093 macro. To do this, add a @code{debug} declaration to the macro
|
|
1094 definition. Here is a simple example that shows the specification for
|
|
1095 the @code{for} example macro (@pxref{Argument Evaluation}).
|
|
1096
|
|
1097 @smallexample
|
|
1098 (defmacro for (var from init to final do &rest body)
|
|
1099 "Execute a simple \"for\" loop.
|
|
1100 For example, (for i from 1 to 10 do (print i))."
|
|
1101 (declare (debug (symbolp "from" form "to" form "do" &rest form)))
|
|
1102 ...)
|
|
1103 @end smallexample
|
|
1104
|
|
1105 The Edebug specification says which parts of a call to the macro are
|
|
1106 forms to be evaluated. For simple macros, the @var{specification}
|
|
1107 often looks very similar to the formal argument list of the macro
|
|
1108 definition, but specifications are much more general than macro
|
|
1109 arguments. @xref{Defining Macros}, for more explanation of
|
|
1110 the @code{declare} form.
|
|
1111
|
|
1112 You can also define an edebug specification for a macro separately
|
|
1113 from the macro definition with @code{def-edebug-spec}. Adding
|
|
1114 @code{debug} declarations is preferred, and more convenient, for macro
|
|
1115 definitions in Lisp, but @code{def-edebug-spec} makes it possible to
|
|
1116 define Edebug specifications for special forms implemented in C.
|
|
1117
|
|
1118 @deffn Macro def-edebug-spec macro specification
|
|
1119 Specify which expressions of a call to macro @var{macro} are forms to be
|
|
1120 evaluated. @var{specification} should be the edebug specification.
|
|
1121 Neither argument is evaluated.
|
|
1122
|
|
1123 The @var{macro} argument can actually be any symbol, not just a macro
|
|
1124 name.
|
|
1125 @end deffn
|
|
1126
|
|
1127 Here is a table of the possibilities for @var{specification} and how each
|
|
1128 directs processing of arguments.
|
|
1129
|
|
1130 @table @asis
|
|
1131 @item @code{t}
|
|
1132 All arguments are instrumented for evaluation.
|
|
1133
|
|
1134 @item @code{0}
|
|
1135 None of the arguments is instrumented.
|
|
1136
|
|
1137 @item a symbol
|
|
1138 The symbol must have an Edebug specification which is used instead.
|
|
1139 This indirection is repeated until another kind of specification is
|
|
1140 found. This allows you to inherit the specification from another macro.
|
|
1141
|
|
1142 @item a list
|
|
1143 The elements of the list describe the types of the arguments of a
|
|
1144 calling form. The possible elements of a specification list are
|
|
1145 described in the following sections.
|
|
1146 @end table
|
|
1147
|
|
1148 @vindex edebug-eval-macro-args
|
|
1149 If a macro has no Edebug specification, neither through a @code{debug}
|
|
1150 declaration nor through a @code{def-edebug-spec} call, the variable
|
|
1151 @code{edebug-eval-macro-args} comes into play. If it is @code{nil},
|
|
1152 the default, none of the arguments is instrumented for evaluation.
|
|
1153 If it is non-@code{nil}, all arguments are instrumented.
|
|
1154
|
|
1155 @node Specification List
|
|
1156 @subsubsection Specification List
|
|
1157
|
|
1158 @cindex Edebug specification list
|
|
1159 A @dfn{specification list} is required for an Edebug specification if
|
|
1160 some arguments of a macro call are evaluated while others are not. Some
|
|
1161 elements in a specification list match one or more arguments, but others
|
|
1162 modify the processing of all following elements. The latter, called
|
|
1163 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
|
|
1164 as @code{&optional}).
|
|
1165
|
|
1166 A specification list may contain sublists which match arguments that are
|
|
1167 themselves lists, or it may contain vectors used for grouping. Sublists
|
|
1168 and groups thus subdivide the specification list into a hierarchy of
|
|
1169 levels. Specification keywords apply only to the remainder of the
|
|
1170 sublist or group they are contained in.
|
|
1171
|
|
1172 When a specification list involves alternatives or repetition, matching
|
|
1173 it against an actual macro call may require backtracking.
|
|
1174 @xref{Backtracking}, for more details.
|
|
1175
|
|
1176 Edebug specifications provide the power of regular expression matching,
|
|
1177 plus some context-free grammar constructs: the matching of sublists with
|
|
1178 balanced parentheses, recursive processing of forms, and recursion via
|
|
1179 indirect specifications.
|
|
1180
|
|
1181 Here's a table of the possible elements of a specification list, with
|
|
1182 their meanings (see @ref{Specification Examples}, for the referenced
|
|
1183 examples):
|
|
1184
|
|
1185 @table @code
|
|
1186 @item sexp
|
|
1187 A single unevaluated Lisp object, which is not instrumented.
|
|
1188 @c an "expression" is not necessarily intended for evaluation.
|
|
1189
|
|
1190 @item form
|
|
1191 A single evaluated expression, which is instrumented.
|
|
1192
|
|
1193 @item place
|
|
1194 @findex edebug-unwrap
|
|
1195 A place to store a value, as in the Common Lisp @code{setf} construct.
|
|
1196
|
|
1197 @item body
|
|
1198 Short for @code{&rest form}. See @code{&rest} below.
|
|
1199
|
|
1200 @item function-form
|
|
1201 A function form: either a quoted function symbol, a quoted lambda
|
|
1202 expression, or a form (that should evaluate to a function symbol or
|
|
1203 lambda expression). This is useful when an argument that's a lambda
|
|
1204 expression might be quoted with @code{quote} rather than
|
|
1205 @code{function}, since it instruments the body of the lambda expression
|
|
1206 either way.
|
|
1207
|
|
1208 @item lambda-expr
|
|
1209 A lambda expression with no quoting.
|
|
1210
|
|
1211 @item &optional
|
|
1212 @c @kindex &optional @r{(Edebug)}
|
|
1213 All following elements in the specification list are optional; as soon
|
|
1214 as one does not match, Edebug stops matching at this level.
|
|
1215
|
|
1216 To make just a few elements optional followed by non-optional elements,
|
|
1217 use @code{[&optional @var{specs}@dots{}]}. To specify that several
|
|
1218 elements must all match or none, use @code{&optional
|
|
1219 [@var{specs}@dots{}]}. See the @code{defun} example.
|
|
1220
|
|
1221 @item &rest
|
|
1222 @c @kindex &rest @r{(Edebug)}
|
|
1223 All following elements in the specification list are repeated zero or
|
|
1224 more times. In the last repetition, however, it is not a problem if the
|
|
1225 expression runs out before matching all of the elements of the
|
|
1226 specification list.
|
|
1227
|
|
1228 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
|
|
1229 To specify several elements that must all match on every repetition, use
|
|
1230 @code{&rest [@var{specs}@dots{}]}.
|
|
1231
|
|
1232 @item &or
|
|
1233 @c @kindex &or @r{(Edebug)}
|
|
1234 Each of the following elements in the specification list is an
|
|
1235 alternative. One of the alternatives must match, or the @code{&or}
|
|
1236 specification fails.
|
|
1237
|
|
1238 Each list element following @code{&or} is a single alternative. To
|
|
1239 group two or more list elements as a single alternative, enclose them in
|
|
1240 @code{[@dots{}]}.
|
|
1241
|
|
1242 @item ¬
|
|
1243 @c @kindex ¬ @r{(Edebug)}
|
|
1244 Each of the following elements is matched as alternatives as if by using
|
|
1245 @code{&or}, but if any of them match, the specification fails. If none
|
|
1246 of them match, nothing is matched, but the @code{¬} specification
|
|
1247 succeeds.
|
|
1248
|
|
1249 @item &define
|
|
1250 @c @kindex &define @r{(Edebug)}
|
|
1251 Indicates that the specification is for a defining form. The defining
|
|
1252 form itself is not instrumented (that is, Edebug does not stop before and
|
|
1253 after the defining form), but forms inside it typically will be
|
|
1254 instrumented. The @code{&define} keyword should be the first element in
|
|
1255 a list specification.
|
|
1256
|
|
1257 @item nil
|
|
1258 This is successful when there are no more arguments to match at the
|
|
1259 current argument list level; otherwise it fails. See sublist
|
|
1260 specifications and the backquote example.
|
|
1261
|
|
1262 @item gate
|
|
1263 @cindex preventing backtracking
|
|
1264 No argument is matched but backtracking through the gate is disabled
|
|
1265 while matching the remainder of the specifications at this level. This
|
|
1266 is primarily used to generate more specific syntax error messages. See
|
|
1267 @ref{Backtracking}, for more details. Also see the @code{let} example.
|
|
1268
|
|
1269 @item @var{other-symbol}
|
|
1270 @cindex indirect specifications
|
|
1271 Any other symbol in a specification list may be a predicate or an
|
|
1272 indirect specification.
|
|
1273
|
|
1274 If the symbol has an Edebug specification, this @dfn{indirect
|
|
1275 specification} should be either a list specification that is used in
|
|
1276 place of the symbol, or a function that is called to process the
|
|
1277 arguments. The specification may be defined with @code{def-edebug-spec}
|
|
1278 just as for macros. See the @code{defun} example.
|
|
1279
|
|
1280 Otherwise, the symbol should be a predicate. The predicate is called
|
|
1281 with the argument and the specification fails if the predicate returns
|
|
1282 @code{nil}. In either case, that argument is not instrumented.
|
|
1283
|
|
1284 Some suitable predicates include @code{symbolp}, @code{integerp},
|
|
1285 @code{stringp}, @code{vectorp}, and @code{atom}.
|
|
1286
|
|
1287 @item [@var{elements}@dots{}]
|
|
1288 @cindex [@dots{}] (Edebug)
|
|
1289 A vector of elements groups the elements into a single @dfn{group
|
|
1290 specification}. Its meaning has nothing to do with vectors.
|
|
1291
|
|
1292 @item "@var{string}"
|
|
1293 The argument should be a symbol named @var{string}. This specification
|
|
1294 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
|
|
1295 of @var{symbol} is the @var{string}, but the string form is preferred.
|
|
1296
|
|
1297 @item (vector @var{elements}@dots{})
|
|
1298 The argument should be a vector whose elements must match the
|
|
1299 @var{elements} in the specification. See the backquote example.
|
|
1300
|
|
1301 @item (@var{elements}@dots{})
|
|
1302 Any other list is a @dfn{sublist specification} and the argument must be
|
|
1303 a list whose elements match the specification @var{elements}.
|
|
1304
|
|
1305 @cindex dotted lists (Edebug)
|
|
1306 A sublist specification may be a dotted list and the corresponding list
|
|
1307 argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
|
|
1308 dotted list specification may be another sublist specification (via a
|
|
1309 grouping or an indirect specification, e.g., @code{(spec . [(more
|
|
1310 specs@dots{})])}) whose elements match the non-dotted list arguments.
|
|
1311 This is useful in recursive specifications such as in the backquote
|
|
1312 example. Also see the description of a @code{nil} specification
|
|
1313 above for terminating such recursion.
|
|
1314
|
|
1315 Note that a sublist specification written as @code{(specs . nil)}
|
|
1316 is equivalent to @code{(specs)}, and @code{(specs .
|
|
1317 (sublist-elements@dots{}))} is equivalent to @code{(specs
|
|
1318 sublist-elements@dots{})}.
|
|
1319 @end table
|
|
1320
|
|
1321 @c Need to document extensions with &symbol and :symbol
|
|
1322
|
|
1323 Here is a list of additional specifications that may appear only after
|
|
1324 @code{&define}. See the @code{defun} example.
|
|
1325
|
|
1326 @table @code
|
|
1327 @item name
|
|
1328 The argument, a symbol, is the name of the defining form.
|
|
1329
|
|
1330 A defining form is not required to have a name field; and it may have
|
|
1331 multiple name fields.
|
|
1332
|
|
1333 @item :name
|
|
1334 This construct does not actually match an argument. The element
|
|
1335 following @code{:name} should be a symbol; it is used as an additional
|
|
1336 name component for the definition. You can use this to add a unique,
|
|
1337 static component to the name of the definition. It may be used more
|
|
1338 than once.
|
|
1339
|
|
1340 @item arg
|
|
1341 The argument, a symbol, is the name of an argument of the defining form.
|
|
1342 However, lambda-list keywords (symbols starting with @samp{&})
|
|
1343 are not allowed.
|
|
1344
|
|
1345 @item lambda-list
|
|
1346 @cindex lambda-list (Edebug)
|
|
1347 This matches a lambda list---the argument list of a lambda expression.
|
|
1348
|
|
1349 @item def-body
|
|
1350 The argument is the body of code in a definition. This is like
|
|
1351 @code{body}, described above, but a definition body must be instrumented
|
|
1352 with a different Edebug call that looks up information associated with
|
|
1353 the definition. Use @code{def-body} for the highest level list of forms
|
|
1354 within the definition.
|
|
1355
|
|
1356 @item def-form
|
|
1357 The argument is a single, highest-level form in a definition. This is
|
|
1358 like @code{def-body}, except use this to match a single form rather than
|
|
1359 a list of forms. As a special case, @code{def-form} also means that
|
|
1360 tracing information is not output when the form is executed. See the
|
|
1361 @code{interactive} example.
|
|
1362 @end table
|
|
1363
|
|
1364 @node Backtracking
|
|
1365 @subsubsection Backtracking in Specifications
|
|
1366
|
|
1367 @cindex backtracking
|
|
1368 @cindex syntax error (Edebug)
|
|
1369 If a specification fails to match at some point, this does not
|
|
1370 necessarily mean a syntax error will be signaled; instead,
|
|
1371 @dfn{backtracking} will take place until all alternatives have been
|
|
1372 exhausted. Eventually every element of the argument list must be
|
|
1373 matched by some element in the specification, and every required element
|
|
1374 in the specification must match some argument.
|
|
1375
|
|
1376 When a syntax error is detected, it might not be reported until much
|
|
1377 later after higher-level alternatives have been exhausted, and with the
|
|
1378 point positioned further from the real error. But if backtracking is
|
|
1379 disabled when an error occurs, it can be reported immediately. Note
|
|
1380 that backtracking is also reenabled automatically in several situations;
|
|
1381 it is reenabled when a new alternative is established by
|
|
1382 @code{&optional}, @code{&rest}, or @code{&or}, or at the start of
|
|
1383 processing a sublist, group, or indirect specification. The effect of
|
|
1384 enabling or disabling backtracking is limited to the remainder of the
|
|
1385 level currently being processed and lower levels.
|
|
1386
|
|
1387 Backtracking is disabled while matching any of the
|
|
1388 form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
|
|
1389 @code{def-body}). These specifications will match any form so any error
|
|
1390 must be in the form itself rather than at a higher level.
|
|
1391
|
|
1392 Backtracking is also disabled after successfully matching a quoted
|
|
1393 symbol or string specification, since this usually indicates a
|
|
1394 recognized construct. But if you have a set of alternative constructs that
|
|
1395 all begin with the same symbol, you can usually work around this
|
|
1396 constraint by factoring the symbol out of the alternatives, e.g.,
|
|
1397 @code{["foo" &or [first case] [second case] ...]}.
|
|
1398
|
|
1399 Most needs are satisfied by these two ways that backtracking is
|
|
1400 automatically disabled, but occasionally it is useful to explicitly
|
|
1401 disable backtracking by using the @code{gate} specification. This is
|
|
1402 useful when you know that no higher alternatives could apply. See the
|
|
1403 example of the @code{let} specification.
|
|
1404
|
|
1405 @node Specification Examples
|
|
1406 @subsubsection Specification Examples
|
|
1407
|
|
1408 It may be easier to understand Edebug specifications by studying
|
|
1409 the examples provided here.
|
|
1410
|
|
1411 A @code{let} special form has a sequence of bindings and a body. Each
|
|
1412 of the bindings is either a symbol or a sublist with a symbol and
|
|
1413 optional expression. In the specification below, notice the @code{gate}
|
|
1414 inside of the sublist to prevent backtracking once a sublist is found.
|
|
1415
|
|
1416 @example
|
|
1417 (def-edebug-spec let
|
|
1418 ((&rest
|
|
1419 &or symbolp (gate symbolp &optional form))
|
|
1420 body))
|
|
1421 @end example
|
|
1422
|
|
1423 Edebug uses the following specifications for @code{defun} and
|
|
1424 @code{defmacro} and the associated argument list and @code{interactive}
|
|
1425 specifications. It is necessary to handle interactive forms specially
|
|
1426 since an expression argument is actually evaluated outside of the
|
|
1427 function body.
|
|
1428
|
|
1429 @smallexample
|
|
1430 (def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
|
|
1431 (def-edebug-spec defun
|
|
1432 (&define name lambda-list
|
|
1433 [&optional stringp] ; @r{Match the doc string, if present.}
|
|
1434 [&optional ("interactive" interactive)]
|
|
1435 def-body))
|
|
1436
|
|
1437 (def-edebug-spec lambda-list
|
|
1438 (([&rest arg]
|
|
1439 [&optional ["&optional" arg &rest arg]]
|
|
1440 &optional ["&rest" arg]
|
|
1441 )))
|
|
1442
|
|
1443 (def-edebug-spec interactive
|
|
1444 (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
|
|
1445 @end smallexample
|
|
1446
|
|
1447 The specification for backquote below illustrates how to match
|
|
1448 dotted lists and use @code{nil} to terminate recursion. It also
|
|
1449 illustrates how components of a vector may be matched. (The actual
|
|
1450 specification defined by Edebug does not support dotted lists because
|
|
1451 doing so causes very deep recursion that could fail.)
|
|
1452
|
|
1453 @smallexample
|
|
1454 (def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
|
|
1455
|
|
1456 (def-edebug-spec backquote-form
|
|
1457 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
|
|
1458 (backquote-form . [&or nil backquote-form])
|
|
1459 (vector &rest backquote-form)
|
|
1460 sexp))
|
|
1461 @end smallexample
|
|
1462
|
|
1463
|
|
1464 @node Edebug Options
|
|
1465 @subsection Edebug Options
|
|
1466
|
|
1467 These options affect the behavior of Edebug:
|
|
1468
|
|
1469 @defopt edebug-setup-hook
|
|
1470 Functions to call before Edebug is used. Each time it is set to a new
|
|
1471 value, Edebug will call those functions once and then
|
|
1472 @code{edebug-setup-hook} is reset to @code{nil}. You could use this to
|
|
1473 load up Edebug specifications associated with a package you are using
|
|
1474 but only when you also use Edebug.
|
|
1475 @xref{Instrumenting}.
|
|
1476 @end defopt
|
|
1477
|
|
1478 @defopt edebug-all-defs
|
|
1479 If this is non-@code{nil}, normal evaluation of defining forms such as
|
|
1480 @code{defun} and @code{defmacro} instruments them for Edebug. This
|
|
1481 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
|
|
1482 and @code{eval-current-buffer}.
|
|
1483
|
|
1484 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
|
|
1485 option. @xref{Instrumenting}.
|
|
1486 @end defopt
|
|
1487
|
|
1488 @defopt edebug-all-forms
|
|
1489 If this is non-@code{nil}, the commands @code{eval-defun},
|
|
1490 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
|
|
1491 instrument all forms, even those that don't define anything.
|
|
1492 This doesn't apply to loading or evaluations in the minibuffer.
|
|
1493
|
|
1494 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
|
|
1495 option. @xref{Instrumenting}.
|
|
1496 @end defopt
|
|
1497
|
|
1498 @defopt edebug-save-windows
|
|
1499 If this is non-@code{nil}, Edebug saves and restores the window
|
|
1500 configuration. That takes some time, so if your program does not care
|
|
1501 what happens to the window configurations, it is better to set this
|
|
1502 variable to @code{nil}.
|
|
1503
|
|
1504 If the value is a list, only the listed windows are saved and
|
|
1505 restored.
|
|
1506
|
|
1507 You can use the @kbd{W} command in Edebug to change this variable
|
|
1508 interactively. @xref{Edebug Display Update}.
|
|
1509 @end defopt
|
|
1510
|
|
1511 @defopt edebug-save-displayed-buffer-points
|
|
1512 If this is non-@code{nil}, Edebug saves and restores point in all
|
|
1513 displayed buffers.
|
|
1514
|
|
1515 Saving and restoring point in other buffers is necessary if you are
|
|
1516 debugging code that changes the point of a buffer which is displayed in
|
|
1517 a non-selected window. If Edebug or the user then selects the window,
|
|
1518 point in that buffer will move to the window's value of point.
|
|
1519
|
|
1520 Saving and restoring point in all buffers is expensive, since it
|
|
1521 requires selecting each window twice, so enable this only if you need
|
|
1522 it. @xref{Edebug Display Update}.
|
|
1523 @end defopt
|
|
1524
|
|
1525 @defopt edebug-initial-mode
|
|
1526 If this variable is non-@code{nil}, it specifies the initial execution
|
|
1527 mode for Edebug when it is first activated. Possible values are
|
|
1528 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
|
|
1529 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
|
|
1530
|
|
1531 The default value is @code{step}.
|
|
1532 @xref{Edebug Execution Modes}.
|
|
1533 @end defopt
|
|
1534
|
|
1535 @defopt edebug-trace
|
|
1536 If this is non-@code{nil}, trace each function entry and exit.
|
|
1537 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
|
|
1538 function entry or exit per line, indented by the recursion level.
|
|
1539
|
|
1540 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
|
|
1541 @end defopt
|
|
1542
|
|
1543 @defopt edebug-test-coverage
|
|
1544 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
|
|
1545 @xref{Coverage Testing}.
|
|
1546 @end defopt
|
|
1547
|
|
1548 @defopt edebug-continue-kbd-macro
|
|
1549 If non-@code{nil}, continue defining or executing any keyboard macro
|
|
1550 that is executing outside of Edebug. Use this with caution since it is not
|
|
1551 debugged.
|
|
1552 @xref{Edebug Execution Modes}.
|
|
1553 @end defopt
|
|
1554
|
|
1555 @defopt edebug-on-error
|
|
1556 Edebug binds @code{debug-on-error} to this value, if
|
|
1557 @code{debug-on-error} was previously @code{nil}. @xref{Trapping
|
|
1558 Errors}.
|
|
1559 @end defopt
|
|
1560
|
|
1561 @defopt edebug-on-quit
|
|
1562 Edebug binds @code{debug-on-quit} to this value, if
|
|
1563 @code{debug-on-quit} was previously @code{nil}. @xref{Trapping
|
|
1564 Errors}.
|
|
1565 @end defopt
|
|
1566
|
|
1567 If you change the values of @code{edebug-on-error} or
|
|
1568 @code{edebug-on-quit} while Edebug is active, their values won't be used
|
|
1569 until the @emph{next} time Edebug is invoked via a new command.
|
|
1570 @c Not necessarily a deeper command level.
|
|
1571 @c A new command is not precisely true, but that is close enough -- dan
|
|
1572
|
|
1573 @defopt edebug-global-break-condition
|
|
1574 If non-@code{nil}, an expression to test for at every stop point. If
|
|
1575 the result is non-@code{nil}, then break. Errors are ignored.
|
|
1576 @xref{Global Break Condition}.
|
|
1577 @end defopt
|
|
1578
|
|
1579 @ignore
|
|
1580 arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
|
|
1581 @end ignore
|