2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1992, 1993, 1994, 1998, 1999 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
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
8 @c with the following links to the Bugs section and to the top level:
10 @c , Bugs and Todo List, Top, Top
12 @node Edebug, Syntax Errors, Debugger, Debugging
17 Edebug is a source-level debugger for Emacs Lisp programs with which
22 Step through evaluation, stopping before and after each expression.
25 Set conditional or unconditional breakpoints.
28 Stop when a specified condition is true (the global break event).
31 Trace slow or fast, stopping briefly at each stop point, or
35 Display expression results and evaluate expressions as if outside of
39 Automatically re-evaluate a list of expressions and
40 display their results each time Edebug updates the display.
43 Output trace info on function enter and exit.
46 Stop when an error occurs.
49 Display a backtrace, omitting Edebug's own frames.
52 Specify argument evaluation for macros and defining forms.
55 Obtain rudimentary coverage testing and frequency counts.
58 The first three sections below should tell you enough about Edebug to
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.
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 * Instrumenting Macro Calls:: Specifying how to handle macro calls.
79 * Options: Edebug Options. Option variables for customizing Edebug.
83 @subsection Using Edebug
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.
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}.
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.
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.
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}.
112 =>@point{}(if (< 0 n)
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
127 .(* n. .(fac (1- n.).).).
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:
139 =>(if @point{}(< 0 n)
144 When Edebug stops execution after an expression, it displays the
145 expression's value in the echo area.
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.
153 @subsection Instrumenting for Edebug
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.
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
166 meaning of the prefix argument: in this case, @kbd{C-M-x} instruments the
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}.
172 @findex eval-region @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.
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}.
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
197 @cindex special forms (Edebug)
198 @cindex interactive commands (Edebug)
199 @cindex anonymous lambda expressions (Edebug)
200 @cindex Common Lisp (Edebug)
201 @pindex cl.el @r{(Edebug)}
203 Edebug knows how to instrument all the standard special forms,
204 @code{interactive} forms with an expression argument, anonymous lambda
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.
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
212 @code{nil}. You can use this to load Edebug specifications
213 (@pxref{Instrumenting Macro Calls}) associated with a package you are
214 using, but only when you use Edebug.
216 @findex eval-expression @r{(Edebug)}
217 To remove instrumentation from a definition, simply re-evaluate its
218 definition in a way that does not instrument. There are two ways of
219 evaluating forms that never instrument them: from a file with
220 @code{load}, and from the minibuffer with @code{eval-expression}
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.
226 @xref{Edebug Eval}, for other evaluation functions available
229 @node Edebug Execution Modes
230 @subsection Edebug Execution Modes
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
235 not confuse them with major or minor modes. The current Edebug execution mode
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
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
243 commands; all except for @kbd{S} resume execution of the program, at
244 least for a certain distance.
248 Stop: don't execute any more of the program, but wait for more
249 Edebug commands (@code{edebug-stop}).
252 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
255 Next: stop at the next stop point encountered after an expression
256 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
260 Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
263 Rapid trace: update the display at each stop point, but don't actually
264 pause (@code{edebug-Trace-fast-mode}).
267 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
270 Continue: pause one second at each breakpoint, and then continue
271 (@code{edebug-continue-mode}).
274 Rapid continue: move point to each breakpoint, but don't pause
275 (@code{edebug-Continue-fast-mode}).
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.
282 In general, the execution modes earlier in the above list run the
283 program more slowly or stop sooner than the modes later in the list.
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
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.
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
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
301 inside Edebug. This is usually an advantage. See also the
302 @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
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.
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.
320 These commands may fail to work as expected in case of nonlocal exit,
321 as that can bypass the temporary breakpoint where you expected the
326 Proceed to the stop point near where point is (@code{edebug-goto-here}).
329 Run the program forward over one expression
330 (@code{edebug-forward-sexp}).
333 Run the program until the end of the containing sexp.
336 Step into the function or macro called by the form after point.
339 The @kbd{h} command proceeds to the stop point near the current location
340 of point, using a temporary breakpoint. See @ref{Breakpoints}, for more
341 information about breakpoints.
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.
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
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
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
360 move point there, and then type @kbd{f}.
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
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
367 command does not exit the currently executing function unless you are
368 positioned after the last sexp.
370 The @kbd{i} command steps into the function or macro called by the list
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.
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.
382 @subsection Miscellaneous Edebug Commands
384 Some miscellaneous Edebug commands are described here.
388 Display the help message for Edebug (@code{edebug-help}).
391 Abort one level back to the previous command level
392 (@code{abort-recursive-edit}).
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
402 Like @kbd{q}, but don't stop even for protected code
403 (@code{top-level-nonstop}).
406 Redisplay the most recently known expression result in the echo area
407 (@code{edebug-previous-result}).
410 Display a backtrace, excluding Edebug's own functions for clarity
411 (@code{edebug-backtrace}).
413 You cannot use debugger commands in the backtrace buffer in Edebug as
414 you would in the standard debugger.
416 The backtrace buffer is killed automatically when you continue
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}.
426 @subsection Breakpoints
429 Edebug's step mode stops execution when the next stop point is reached.
430 There are three other ways to stop Edebug execution once it has started:
431 breakpoints, the global break condition, and source breakpoints.
433 While using Edebug, you can specify @dfn{breakpoints} in the program you
434 are testing: these are places where execution should stop. You can set a
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:
442 Set a breakpoint at the stop point at or after point
443 (@code{edebug-set-breakpoint}). If you use a prefix argument, the
444 breakpoint is temporary---it turns off the first time it stops the
448 Unset the breakpoint (if any) at the stop point at or after
449 point (@code{edebug-unset-breakpoint}).
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.
458 Move point to the next breakpoint in the current definition
459 (@code{edebug-next-breakpoint}).
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.
467 Re-evaluating or reinstrumenting a definition removes all of its
468 previous breakpoints.
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.
478 You can make a conditional or unconditional breakpoint
479 @dfn{temporary} by using a prefix argument with the command to set the
480 breakpoint. When a temporary breakpoint stops the program, it is
483 Edebug always stops or pauses at a breakpoint, except when the Edebug
484 mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
486 To find out where your breakpoints are, use the @kbd{B} command, which
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
493 * Global Break Condition:: Breaking on an event.
494 * Source Breakpoints:: Embedding breakpoints in source code.
498 @node Global Break Condition
499 @subsubsection Global Break Condition
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
505 evaluates the global break condition at every stop point; if it
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.
510 @findex edebug-set-global-break-condition
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}).
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.
519 @node Source Breakpoints
520 @subsubsection Source Breakpoints
523 @cindex source breakpoints
524 All breakpoints in a definition are forgotten each time you
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:
534 (if (= n 0) (edebug))
540 When the @code{fac} definition is instrumented and the function is
541 called, the call to @code{edebug} acts as a breakpoint. Depending on
542 the execution mode, Edebug stops or pauses there.
544 If no instrumented code is being executed when @code{edebug} is called,
545 that function calls @code{debug}.
546 @c This may not be a good idea anymore.
548 @node Trapping Errors
549 @subsection Trapping Errors
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}.
557 When Edebug responds to an error, it shows the last stop point
558 encountered before the error. This may be the location of a call to a
559 function which was not instrumented, and within which the error actually
560 occurred. For an unbound variable error, the last known stop point
561 might be quite distant from the offending variable reference. In that
562 case, you might want to display a full backtrace (@pxref{Edebug Misc}).
564 @c Edebug should be changed for the following: -- dan
565 If you change @code{debug-on-error} or @code{debug-on-quit} while
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.
571 @subsection Edebug Views
573 These Edebug commands let you view aspects of the buffer and window
574 status as they were before entry to Edebug. The outside window
575 configuration is the collection of windows and contents that were in
576 effect outside of Edebug.
580 Temporarily view the outside window configuration
581 (@code{edebug-view-outside}).
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.
589 Move point back to the current stop point in the source code buffer
590 (@code{edebug-where}).
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.
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}).
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.
606 You can view the outside window configuration with @kbd{v} or just
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.
611 Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
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
620 @subsection Evaluation
622 While within Edebug, you can evaluate expressions ``as if'' Edebug
623 were not running. Edebug tries to be invisible to the expression's
624 evaluation and printing. Evaluation of expressions that cause side
625 effects will work as expected, except for changes to data that Edebug
626 explicitly saves and restores. @xref{The Outside Context}, for details
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.
635 @item M-: @var{exp} @key{RET}
636 Evaluate expression @var{exp} in the context of Edebug itself.
639 Evaluate the expression before point, in the context outside of Edebug
640 (@code{edebug-eval-last-sexp}).
643 @cindex lexical binding (Edebug)
644 Edebug supports evaluation of expressions containing references to
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}.
650 @subsection Evaluation List Buffer
652 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
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.
659 Switch to the evaluation list buffer @samp{*edebug*}
660 (@code{edebug-visit-eval-list}).
663 In the @samp{*edebug*} buffer you can use the commands of Lisp
664 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
665 Manual}) as well as these special commands:
669 Evaluate the expression before point, in the outside context, and insert
670 the value in the buffer (@code{edebug-eval-print-last-sexp}).
673 Evaluate the expression before point, in the context outside of Edebug
674 (@code{edebug-eval-last-sexp}).
677 Build a new evaluation list from the contents of the buffer
678 (@code{edebug-update-eval-list}).
681 Delete the evaluation list group that point is in
682 (@code{edebug-delete-eval-item}).
685 Switch back to the source code buffer at the current stop point
686 (@code{edebug-where}).
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*};
691 but they are evaluated in the context outside of Edebug.
693 The expressions you enter interactively (and their results) are lost
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.
697 @cindex evaluation list group
698 To do this, write one or more @dfn{evaluation list groups} in the
699 evaluation list buffer. An evaluation list group consists of one or
700 more Lisp expressions. Groups are separated by comment lines.
702 The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
703 evaluation list, scanning the buffer and using the first expression of
704 each group. (The idea is that the second expression of the group is the
705 value previously computed and displayed.)
707 Each entry to Edebug redisplays the evaluation list by inserting each
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.
713 If an error occurs during an evaluation from the evaluation list, the
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.
718 Here is an example of what the evaluation list window looks like after
719 several expressions have been added to it:
724 ;---------------------------------------------------------------
726 #<window 16 on *scratch*>
727 ;---------------------------------------------------------------
730 ;---------------------------------------------------------------
732 "Symbol's value as variable is void: bad-var"
733 ;---------------------------------------------------------------
736 ;---------------------------------------------------------------
739 ;---------------------------------------------------------------
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
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.
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.
753 @node Printing in Edebug
754 @subsection Printing in Edebug
756 @cindex printing (Edebug)
757 @cindex printing circular structures
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.
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}.
769 @defopt edebug-print-length
770 If non-@code{nil}, Edebug binds @code{print-length} to this value while
771 printing results. The default value is @code{50}.
774 @defopt edebug-print-level
775 If non-@code{nil}, Edebug binds @code{print-level} to this value while
776 printing results. The default value is @code{50}.
779 You can also print circular structures and structures that share
780 elements more informatively by binding @code{print-circle}
781 to a non-@code{nil} value.
783 Here is an example of code that creates a circular structure:
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
793 @samp{1}, and the @samp{#1#} notation references the previously labeled
794 structure. This notation is used for any shared elements of lists or
797 @defopt edebug-print-circle
798 If non-@code{nil}, Edebug binds @code{print-circle} to this value while
799 printing results. The default value is @code{nil}.
802 Other programs can also use custom printing; see @file{cust-print.el}
806 @subsection Trace Buffer
809 Edebug can record an execution trace, storing it in a buffer named
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.
814 Making a trace buffer is not the same thing as using trace execution
815 mode (@pxref{Edebug Execution Modes}).
817 When trace recording is enabled, each function entry and exit adds
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
821 name and result of the function.
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.
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}.
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
836 to put in the trace buffer. All the arguments are evaluated, and
837 @code{edebug-tracing} returns the value of the last form in @var{body}.
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})}.
843 It also appends a newline to separate entries.
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
851 @node Coverage Testing
852 @subsection Coverage Testing
854 @cindex coverage testing
855 @cindex frequency counts
856 @cindex performance analysis
857 Edebug provides rudimentary coverage testing and display of execution
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.
868 Coverage testing makes execution slower, so it is only done if
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
874 Use @kbd{M-x edebug-display-freq-count} to display both the
875 coverage information and the frequency counts for a definition.
877 @deffn Command edebug-display-freq-count
878 This command displays the frequency count data for each line of the
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{)}
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.
888 The character @samp{=} following the count for an expression says that
889 the expression has returned the same value each time it was evaluated.
890 In other words, it is not yet ``covered'' for coverage testing purposes.
892 To clear the frequency count and coverage data for a definition,
893 simply reinstrument it with @code{eval-defun}.
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:
902 (if (= n 0) (edebug))
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
914 time; the same is true of the condition on the second @code{if}.
915 The recursive call of @code{fac} did not return at all.
918 @node The Outside Context
919 @subsection The Outside Context
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.
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.
934 @node Checking Whether to Stop
935 @subsubsection Checking Whether to Stop
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
943 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
944 incremented once to reduce Edebug's impact on the stack. You could,
945 however, still run out of stack space when using Edebug.
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}.
955 @node Edebug Display Update
956 @subsubsection Edebug Display Update
958 @c This paragraph is not filled, because LaLiberte's conversion script
959 @c needs an xref to be on just one line.
960 When Edebug needs to display something (e.g., in trace mode), it saves
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.
965 Emacs redisplays only when it pauses. Usually, when you continue
966 execution, the program re-enters Edebug at a breakpoint or after
967 stepping, without pausing or reading input in between. In such cases,
968 Emacs never gets a chance to redisplay the ``outside'' configuration.
969 Consequently, what you see is the same window configuration as the last
970 time Edebug was active, with no interruption.
972 Entry to Edebug for displaying something also saves and restores the
973 following data (though some of them are deliberately not restored if an
974 error or quit signal occurs).
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.
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}).
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
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.
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}.
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.
1006 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
1007 the cursor shows up in the window.
1010 @node Edebug Recursive Edit
1011 @subsubsection Edebug Recursive Edit
1013 When Edebug is entered and actually reads commands from the user, it
1014 saves (and later restores) these additional data:
1018 The current match data. @xref{Match Data}.
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.
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.
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
1037 Complex commands executed while in Edebug are added to the variable
1038 @code{command-history}. In rare cases this can alter execution.
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.
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
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}.
1056 @node Instrumenting Macro Calls
1057 @subsection Instrumenting Macro Calls
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
1066 Therefore, you must define an Edebug specification for each macro
1067 that Edebug will encounter, to explain the format of calls to that
1068 macro. To do this, add an @code{edebug} declaration to the macro
1069 definition. Here is a simple example that shows the specification for
1070 the @code{for} example macro (@pxref{Argument Evaluation}).
1073 (defmacro for (var from init to final do &rest body)
1074 "Execute a simple \"for\" loop.
1075 For example, (for i from 1 to 10 do (print i))."
1076 (declare (edebug symbolp "from" form "to" form "do" &rest form))
1080 @defspec declare (edebug @var{specification})
1081 Specify which expressions of a call to the macro in which the
1082 declaration appears are forms to be evaluated. For simple macros, the
1083 @var{specification} often looks very similar to the formal argument list
1084 of the macro definition, but specifications are much more general than
1088 You can also define an edebug specification for a macro separately
1089 from the macro definition with @code{def-edebug-spec}. Adding
1090 @code{edebug} declarations is preferred, and more convenient, for
1091 macro definitions in Lisp, but @code{def-edebug-spec} makes it
1092 possible to define Edebug specifications for special forms implemented
1095 @deffn Macro def-edebug-spec macro specification
1096 Specify which expressions of a call to macro @var{macro} are forms to be
1097 evaluated. @var{specification} should be the edebug specification.
1098 It is not evaluated.
1100 The @var{macro} argument can actually be any symbol, not just a macro
1104 Here is a table of the possibilities for @var{specification} and how each
1105 directs processing of arguments.
1109 All arguments are instrumented for evaluation.
1112 None of the arguments is instrumented.
1115 The symbol must have an Edebug specification which is used instead.
1116 This indirection is repeated until another kind of specification is
1117 found. This allows you to inherit the specification from another macro.
1120 The elements of the list describe the types of the arguments of a
1121 calling form. The possible elements of a specification list are
1122 described in the following sections.
1126 * Specification List:: How to specify complex patterns of evaluation.
1127 * Backtracking:: What Edebug does when matching fails.
1128 * Specification Examples:: To help understand specifications.
1132 @node Specification List
1133 @subsubsection Specification List
1135 @cindex Edebug specification list
1136 A @dfn{specification list} is required for an Edebug specification if
1137 some arguments of a macro call are evaluated while others are not. Some
1138 elements in a specification list match one or more arguments, but others
1139 modify the processing of all following elements. The latter, called
1140 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
1141 as @code{&optional}).
1143 A specification list may contain sublists which match arguments that are
1144 themselves lists, or it may contain vectors used for grouping. Sublists
1145 and groups thus subdivide the specification list into a hierarchy of
1146 levels. Specification keywords apply only to the remainder of the
1147 sublist or group they are contained in.
1149 When a specification list involves alternatives or repetition, matching
1150 it against an actual macro call may require backtracking.
1151 @xref{Backtracking}, for more details.
1153 Edebug specifications provide the power of regular expression matching,
1154 plus some context-free grammar constructs: the matching of sublists with
1155 balanced parentheses, recursive processing of forms, and recursion via
1156 indirect specifications.
1158 Here's a table of the possible elements of a specification list, with
1163 A single unevaluated Lisp object, which is not instrumented.
1164 @c an "expression" is not necessarily intended for evaluation.
1167 A single evaluated expression, which is instrumented.
1170 @findex edebug-unwrap
1171 A place to store a value, as in the Common Lisp @code{setf} construct.
1174 Short for @code{&rest form}. See @code{&rest} below.
1177 A function form: either a quoted function symbol, a quoted lambda
1178 expression, or a form (that should evaluate to a function symbol or
1179 lambda expression). This is useful when an argument that's a lambda
1180 expression might be quoted with @code{quote} rather than
1181 @code{function}, since it instruments the body of the lambda expression
1185 A lambda expression with no quoting.
1188 @kindex &optional @r{(Edebug)}
1189 All following elements in the specification list are optional; as soon
1190 as one does not match, Edebug stops matching at this level.
1192 To make just a few elements optional followed by non-optional elements,
1193 use @code{[&optional @var{specs}@dots{}]}. To specify that several
1194 elements must all match or none, use @code{&optional
1195 [@var{specs}@dots{}]}. See the @code{defun} example below.
1198 @kindex &rest @r{(Edebug)}
1199 All following elements in the specification list are repeated zero or
1200 more times. In the last repetition, however, it is not a problem if the
1201 expression runs out before matching all of the elements of the
1204 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
1205 To specify several elements that must all match on every repetition, use
1206 @code{&rest [@var{specs}@dots{}]}.
1209 @kindex &or @r{(Edebug)}
1210 Each of the following elements in the specification list is an
1211 alternative. One of the alternatives must match, or the @code{&or}
1212 specification fails.
1214 Each list element following @code{&or} is a single alternative. To
1215 group two or more list elements as a single alternative, enclose them in
1219 @kindex ¬ @r{(Edebug)}
1220 Each of the following elements is matched as alternatives as if by using
1221 @code{&or}, but if any of them match, the specification fails. If none
1222 of them match, nothing is matched, but the @code{¬} specification
1226 @kindex &define @r{(Edebug)}
1227 Indicates that the specification is for a defining form. The defining
1228 form itself is not instrumented (that is, Edebug does not stop before and
1229 after the defining form), but forms inside it typically will be
1230 instrumented. The @code{&define} keyword should be the first element in
1231 a list specification.
1234 This is successful when there are no more arguments to match at the
1235 current argument list level; otherwise it fails. See sublist
1236 specifications and the backquote example below.
1239 @cindex preventing backtracking
1240 No argument is matched but backtracking through the gate is disabled
1241 while matching the remainder of the specifications at this level. This
1242 is primarily used to generate more specific syntax error messages. See
1243 @ref{Backtracking}, for more details. Also see the @code{let} example
1246 @item @var{other-symbol}
1247 @cindex indirect specifications
1248 Any other symbol in a specification list may be a predicate or an
1249 indirect specification.
1251 If the symbol has an Edebug specification, this @dfn{indirect
1252 specification} should be either a list specification that is used in
1253 place of the symbol, or a function that is called to process the
1254 arguments. The specification may be defined with @code{def-edebug-spec}
1255 just as for macros. See the @code{defun} example below.
1257 Otherwise, the symbol should be a predicate. The predicate is called
1258 with the argument and the specification fails if the predicate returns
1259 @code{nil}. In either case, that argument is not instrumented.
1261 Some suitable predicates include @code{symbolp}, @code{integerp},
1262 @code{stringp}, @code{vectorp}, and @code{atom}.
1264 @item [@var{elements}@dots{}]
1265 @cindex [@dots{}] (Edebug)
1266 A vector of elements groups the elements into a single @dfn{group
1267 specification}. Its meaning has nothing to do with vectors.
1269 @item "@var{string}"
1270 The argument should be a symbol named @var{string}. This specification
1271 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
1272 of @var{symbol} is the @var{string}, but the string form is preferred.
1274 @item (vector @var{elements}@dots{})
1275 The argument should be a vector whose elements must match the
1276 @var{elements} in the specification. See the backquote example below.
1278 @item (@var{elements}@dots{})
1279 Any other list is a @dfn{sublist specification} and the argument must be
1280 a list whose elements match the specification @var{elements}.
1282 @cindex dotted lists (Edebug)
1283 A sublist specification may be a dotted list and the corresponding list
1284 argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
1285 dotted list specification may be another sublist specification (via a
1286 grouping or an indirect specification, e.g., @code{(spec . [(more
1287 specs@dots{})])}) whose elements match the non-dotted list arguments.
1288 This is useful in recursive specifications such as in the backquote
1289 example below. Also see the description of a @code{nil} specification
1290 above for terminating such recursion.
1292 Note that a sublist specification written as @code{(specs . nil)}
1293 is equivalent to @code{(specs)}, and @code{(specs .
1294 (sublist-elements@dots{}))} is equivalent to @code{(specs
1295 sublist-elements@dots{})}.
1298 @c Need to document extensions with &symbol and :symbol
1300 Here is a list of additional specifications that may appear only after
1301 @code{&define}. See the @code{defun} example below.
1305 The argument, a symbol, is the name of the defining form.
1307 A defining form is not required to have a name field; and it may have
1308 multiple name fields.
1311 This construct does not actually match an argument. The element
1312 following @code{:name} should be a symbol; it is used as an additional
1313 name component for the definition. You can use this to add a unique,
1314 static component to the name of the definition. It may be used more
1318 The argument, a symbol, is the name of an argument of the defining form.
1319 However, lambda-list keywords (symbols starting with @samp{&})
1323 @cindex lambda-list (Edebug)
1324 This matches a lambda list---the argument list of a lambda expression.
1327 The argument is the body of code in a definition. This is like
1328 @code{body}, described above, but a definition body must be instrumented
1329 with a different Edebug call that looks up information associated with
1330 the definition. Use @code{def-body} for the highest level list of forms
1331 within the definition.
1334 The argument is a single, highest-level form in a definition. This is
1335 like @code{def-body}, except use this to match a single form rather than
1336 a list of forms. As a special case, @code{def-form} also means that
1337 tracing information is not output when the form is executed. See the
1338 @code{interactive} example below.
1342 @subsubsection Backtracking in Specifications
1344 @cindex backtracking
1345 @cindex syntax error (Edebug)
1346 If a specification fails to match at some point, this does not
1347 necessarily mean a syntax error will be signaled; instead,
1348 @dfn{backtracking} will take place until all alternatives have been
1349 exhausted. Eventually every element of the argument list must be
1350 matched by some element in the specification, and every required element
1351 in the specification must match some argument.
1353 When a syntax error is detected, it might not be reported until much
1354 later after higher-level alternatives have been exhausted, and with the
1355 point positioned further from the real error. But if backtracking is
1356 disabled when an error occurs, it can be reported immediately. Note
1357 that backtracking is also reenabled automatically in several situations;
1358 it is reenabled when a new alternative is established by
1359 @code{&optional}, @code{&rest}, or @code{&or}, or at the start of
1360 processing a sublist, group, or indirect specification. The effect of
1361 enabling or disabling backtracking is limited to the remainder of the
1362 level currently being processed and lower levels.
1364 Backtracking is disabled while matching any of the
1365 form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
1366 @code{def-body}). These specifications will match any form so any error
1367 must be in the form itself rather than at a higher level.
1369 Backtracking is also disabled after successfully matching a quoted
1370 symbol or string specification, since this usually indicates a
1371 recognized construct. But if you have a set of alternative constructs that
1372 all begin with the same symbol, you can usually work around this
1373 constraint by factoring the symbol out of the alternatives, e.g.,
1374 @code{["foo" &or [first case] [second case] ...]}.
1376 Most needs are satisfied by these two ways that bactracking is
1377 automatically disabled, but occasionally it is useful to explicitly
1378 disable backtracking by using the @code{gate} specification. This is
1379 useful when you know that no higher alternatives could apply. See the
1380 example of the @code{let} specification.
1382 @node Specification Examples
1383 @subsubsection Specification Examples
1385 It may be easier to understand Edebug specifications by studying
1386 the examples provided here.
1388 A @code{let} special form has a sequence of bindings and a body. Each
1389 of the bindings is either a symbol or a sublist with a symbol and
1390 optional expression. In the specification below, notice the @code{gate}
1391 inside of the sublist to prevent backtracking once a sublist is found.
1394 (def-edebug-spec let
1396 &or symbolp (gate symbolp &optional form))
1400 Edebug uses the following specifications for @code{defun} and
1401 @code{defmacro} and the associated argument list and @code{interactive}
1402 specifications. It is necessary to handle interactive forms specially
1403 since an expression argument it is actually evaluated outside of the
1407 (def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
1408 (def-edebug-spec defun
1409 (&define name lambda-list
1410 [&optional stringp] ; @r{Match the doc string, if present.}
1411 [&optional ("interactive" interactive)]
1414 (def-edebug-spec lambda-list
1416 [&optional ["&optional" arg &rest arg]]
1417 &optional ["&rest" arg]
1420 (def-edebug-spec interactive
1421 (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
1424 The specification for backquote below illustrates how to match
1425 dotted lists and use @code{nil} to terminate recursion. It also
1426 illustrates how components of a vector may be matched. (The actual
1427 specification defined by Edebug does not support dotted lists because
1428 doing so causes very deep recursion that could fail.)
1431 (def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
1433 (def-edebug-spec backquote-form
1434 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
1435 (backquote-form . [&or nil backquote-form])
1436 (vector &rest backquote-form)
1441 @node Edebug Options
1442 @subsection Edebug Options
1444 These options affect the behavior of Edebug:
1446 @defopt edebug-setup-hook
1447 Functions to call before Edebug is used. Each time it is set to a new
1448 value, Edebug will call those functions once and then
1449 @code{edebug-setup-hook} is reset to @code{nil}. You could use this to
1450 load up Edebug specifications associated with a package you are using
1451 but only when you also use Edebug.
1452 @xref{Instrumenting}.
1455 @defopt edebug-all-defs
1456 If this is non-@code{nil}, normal evaluation of defining forms such as
1457 @code{defun} and @code{defmacro} instruments them for Edebug. This
1458 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
1459 and @code{eval-current-buffer}.
1461 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
1462 option. @xref{Instrumenting}.
1465 @defopt edebug-all-forms
1466 If this is non-@code{nil}, the commands @code{eval-defun},
1467 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
1468 instrument all forms, even those that don't define anything.
1469 This doesn't apply to loading or evaluations in the minibuffer.
1471 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
1472 option. @xref{Instrumenting}.
1475 @defopt edebug-save-windows
1476 If this is non-@code{nil}, Edebug saves and restores the window
1477 configuration. That takes some time, so if your program does not care
1478 what happens to the window configurations, it is better to set this
1479 variable to @code{nil}.
1481 If the value is a list, only the listed windows are saved and
1484 You can use the @kbd{W} command in Edebug to change this variable
1485 interactively. @xref{Edebug Display Update}.
1488 @defopt edebug-save-displayed-buffer-points
1489 If this is non-@code{nil}, Edebug saves and restores point in all
1492 Saving and restoring point in other buffers is necessary if you are
1493 debugging code that changes the point of a buffer which is displayed in
1494 a non-selected window. If Edebug or the user then selects the window,
1495 point in that buffer will move to the window's value of point.
1497 Saving and restoring point in all buffers is expensive, since it
1498 requires selecting each window twice, so enable this only if you need
1499 it. @xref{Edebug Display Update}.
1502 @defopt edebug-initial-mode
1503 If this variable is non-@code{nil}, it specifies the initial execution
1504 mode for Edebug when it is first activated. Possible values are
1505 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
1506 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
1508 The default value is @code{step}.
1509 @xref{Edebug Execution Modes}.
1512 @defopt edebug-trace
1513 Non-@code{nil} means display a trace of function entry and exit.
1514 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
1515 function entry or exit per line, indented by the recursion level.
1517 The default value is @code{nil}.
1519 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
1522 @defopt edebug-test-coverage
1523 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
1524 @xref{Coverage Testing}.
1527 @defopt edebug-continue-kbd-macro
1528 If non-@code{nil}, continue defining or executing any keyboard macro
1529 that is executing outside of Edebug. Use this with caution since it is not
1531 @xref{Edebug Execution Modes}.
1534 @defopt edebug-on-error
1535 Edebug binds @code{debug-on-error} to this value, if
1536 @code{debug-on-error} was previously @code{nil}. @xref{Trapping
1540 @defopt edebug-on-quit
1541 Edebug binds @code{debug-on-quit} to this value, if
1542 @code{debug-on-quit} was previously @code{nil}. @xref{Trapping
1546 If you change the values of @code{edebug-on-error} or
1547 @code{edebug-on-quit} while Edebug is active, their values won't be used
1548 until the @emph{next} time Edebug is invoked via a new command.
1549 @c Not necessarily a deeper command level.
1550 @c A new command is not precisely true, but that is close enough -- dan
1552 @defopt edebug-global-break-condition
1553 If non-@code{nil}, an expression to test for at every stop point.
1554 If the result is non-nil, then break. Errors are ignored.
1555 @xref{Global Break Condition}.