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