3 @c This file is intended to be used as a section within the Emacs Lisp
4 @c Reference Manual. It may also be used by an independent Edebug User
5 @c Manual, edebug.tex, in which case the Edebug node below should be used
6 @c with the following links to the Bugs section and to the top level:
8 @c , Bugs and Todo List, Top, Top
10 @node Edebug,, Compilation Errors, Debugging
15 Edebug is a source-level debugger for Emacs Lisp programs with which
20 Step through evaluation, stopping before and after each expression.
23 Set conditional or unconditional breakpoints.
26 Stop when a specified condition is true (the global break event).
29 Trace slow or fast, stopping briefly at each stop point, or
33 Display expression results and evaluate expressions as if outside of
37 Automatically reevaluate a list of expressions and
38 display their results each time Edebug updates the display.
41 Output trace info on function enter and exit.
44 Stop when an error occurs.
47 Display a backtrace, omitting Edebug's own frames.
50 Specify argument evaluation for macros and defining forms.
53 Obtain rudimentary coverage testing and frequency counts.
56 The first three sections below should tell you enough about Edebug to
60 * Using Edebug:: Introduction to use of Edebug.
61 * Instrumenting:: You must instrument your code
62 in order to debug it with Edebug.
63 * Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
64 * Jumping:: Commands to jump to a specified place.
65 * Misc: Edebug Misc. Miscellaneous commands.
66 * Breakpoints:: Setting breakpoints to make the program stop.
67 * Trapping Errors:: trapping errors with Edebug.
68 * Views: Edebug Views. Views inside and outside of Edebug.
69 * Eval: Edebug Eval. Evaluating expressions within Edebug.
70 * Eval List:: Expressions whose values are displayed
71 each time you enter Edebug.
72 * Printing in Edebug:: Customization of printing.
73 * Trace Buffer:: How to produce trace output in a buffer.
74 * Coverage Testing:: How to test evaluation coverage.
75 * The Outside Context:: Data that Edebug saves and restores.
76 * Instrumenting Macro Calls:: Specifying how to handle macro calls.
77 * Options: Edebug Options. Option variables for customizing Edebug.
81 @subsection Using Edebug
83 To debug a Lisp program with Edebug, you must first @dfn{instrument}
84 the Lisp code that you want to debug. A simple way to do this is to
85 first move point into the definition of a function or macro and then do
86 @kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See
87 @ref{Instrumenting}, for alternative ways to instrument code.
89 Once a function is instrumented, any call to the function activates
90 Edebug. Activating Edebug may stop execution and let you step through
91 the function, or it may update the display and continue execution while
92 checking for debugging commands, depending on which Edebug execution
93 mode you have selected. The default execution mode is step, which does
94 stop execution. @xref{Edebug Execution Modes}.
96 Within Edebug, you normally view an Emacs buffer showing the source of
97 the Lisp code you are debugging. This is referred to as the @dfn{source
98 code buffer}. This buffer is temporarily read-only.
100 An arrow at the left margin indicates the line where the function is
101 executing. Point initially shows where within the line the function is
102 executing, but this ceases to be true if you move point yourself.
104 If you instrument the definition of @code{fac} (shown below) and then
105 execute @code{(fac 3)}, here is what you normally see. Point is at the
106 open-parenthesis before @code{if}.
110 =>@point{}(if (< 0 n)
116 The places within a function where Edebug can stop execution are called
117 @dfn{stop points}. These occur both before and after each subexpression
118 that is a list, and also after each variable reference.
119 Here we show with periods the stop points found in the function
125 .(* n. .(fac (1- n.).).).
129 The special commands of Edebug are available in the source code buffer
130 in addition to the commands of Emacs Lisp mode. For example, you can
131 type the Edebug command @key{SPC} to execute until the next stop point.
132 If you type @key{SPC} once after entry to @code{fac}, here is the
133 display you will see:
137 =>(if @point{}(< 0 n)
142 When Edebug stops execution after an expression, it displays the
143 expression's value in the echo area.
145 Other frequently used commands are @kbd{b} to set a breakpoint at a stop
146 point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
147 exit Edebug and return to the top-level command loop. Type @kbd{?} to
148 display a list of all Edebug commands.
151 @subsection Instrumenting for Edebug
153 In order to use Edebug to debug Lisp code, you must first
154 @dfn{instrument} the code. Instrumenting code inserts additional code
155 into it, to invoke Edebug at the proper places.
158 @findex eval-defun (Edebug)
159 Once you have loaded Edebug, the command @kbd{C-M-x}
160 (@code{eval-defun}) is redefined so that when invoked with a prefix
161 argument on a definition, it instruments the definition before
162 evaluating it. (The source code itself is not modified.) If the
163 variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
164 meaning of the prefix argument: then @kbd{C-M-x} instruments the
165 definition @emph{unless} it has a prefix argument. The default value of
166 @code{edebug-all-defs} is @code{nil}. The command @kbd{M-x
167 edebug-all-defs} toggles the value of the variable
168 @code{edebug-all-defs}.
170 @findex edebug-all-forms
171 @findex eval-region (Edebug)
172 @findex eval-current-buffer (Edebug)
173 If @code{edebug-all-defs} is non-@code{nil}, then the commands
174 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
175 also instrument any definitions they evaluate. Similarly,
176 @code{edebug-all-forms} controls whether @code{eval-region} should
177 instrument @emph{any} form, even non-defining forms. This doesn't apply
178 to loading or evaluations in the minibuffer. The command @kbd{M-x
179 edebug-all-forms} toggles this option.
181 @findex edebug-eval-top-level-form
182 Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
183 instrument any top-level form regardless of the value of
184 @code{edebug-all-defs} or @code{edebug-all-forms}.
186 When Edebug is about to instrument code for the first time in a session,
187 it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}.
188 You can use this to load up Edebug specifications associated with a
189 package you are using, but only when you also use Edebug.
191 While Edebug is active, the command @kbd{I}
192 (@code{edebug-instrument-callee}) instruments the definition of the
193 function or macro called by the list form after point, if is not already
194 instrumented. This is possible only if Edebug knows where to find the
195 source for that function; after loading Edebug, @code{eval-region}
196 records the position of every definition it evaluates, even if not
197 instrumenting it. See also the @kbd{i} command (@pxref{Jumping}), which
198 steps into the call after instrumenting the function.
200 @cindex special forms (Edebug)
201 @cindex interactive commands (Edebug)
202 @cindex anonymous lambda expressions (Edebug)
203 @cindex Common Lisp (Edebug)
204 @pindex cl.el (Edebug)
206 Edebug knows how to instrument all the standard special forms, an
207 interactive form with an expression argument, anonymous lambda
208 expressions, and other defining forms. Edebug cannot know what a
209 user-defined macro will do with the arguments of a macro call, so you
210 must tell it; @xref{Instrumenting Macro Calls}, for details.
212 @findex eval-expression (Edebug)
213 To remove instrumentation from a definition, simply reevaluate its
214 definition in a way that does not instrument. There are two ways of
215 evaluating forms that never instrument them: from a file with
216 @code{load}, and from the minibuffer with @code{eval-expression}
219 If Edebug detects a syntax error while instrumenting, it leaves point
220 at the erroneous code and signals an @code{invalid-read-syntax} error.
222 @xref{Edebug Eval}, for other evaluation functions available
225 @node Edebug Execution Modes
226 @subsection Edebug Execution Modes
228 @cindex Edebug execution modes
229 Edebug supports several execution modes for running the program you are
230 debugging. We call these alternatives @dfn{Edebug execution modes}; do
231 not confuse them with major or minor modes. The current Edebug execution mode
232 determines how far Edebug continues execution before stopping---whether
233 it stops at each stop point, or continues to the next breakpoint, for
234 example---and how much Edebug displays the progress of the evaluation
237 Normally, you specify the Edebug execution mode by typing a command to
238 continue the program in a certain mode. Here is a table of these
239 commands. All except for @kbd{S} resume execution of the program, at
240 least for a certain distance.
244 Stop: don't execute any more of the program for now, just wait for more
245 Edebug commands (@code{edebug-stop}).
248 Step: stop at the next stop point encountered (@code{edebug-step-mode}).
251 Next: stop at the next stop point encountered after an expression
252 (@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
256 Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
259 Rapid trace: update the display at each stop point, but don't actually
260 pause (@code{edebug-Trace-fast-mode}).
263 Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
266 Continue: pause one second at each breakpoint, and then continue
267 (@code{edebug-continue-mode}).
270 Rapid continue: move point to each breakpoint, but don't pause
271 (@code{edebug-Continue-fast-mode}).
274 Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
275 can still stop the program by typing @kbd{S}, or any editing command.
278 In general, the execution modes earlier in the above list run the
279 program more slowly or stop sooner than the modes later in the list.
281 While executing or tracing, you can interrupt the execution by typing
282 any Edebug command. Edebug stops the program at the next stop point and
283 then executes the command you typed. For example, typing @kbd{t} during
284 execution switches to trace mode at the next stop point. You can use
285 @kbd{S} to stop execution without doing anything else.
287 If your function happens to read input, a character you type intending
288 to interrupt execution may be read by the function instead. You can
289 avoid such unintended results by paying attention to when your program
292 @cindex keyboard macros (Edebug)
293 Keyboard macros containing the commands in this section do not
294 completely work: exiting from Edebug, to resume the program, loses track
295 of the keyboard macro. This is not easy to fix. Also, defining or
296 executing a keyboard macro outside of Edebug does not affect commands
297 inside Edebug. This is usually an advantage. But see the
298 @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
300 When you enter a new Edebug level, the initial execution mode comes from
301 the value of the variable @code{edebug-initial-mode}. By default, this
302 specifies step mode. Note that you may reenter the same Edebug level
303 several times if, for example, an instrumented function is called
304 several times from one command.
310 The commands described in this section execute until they reach a
311 specified location. All except @kbd{i} make a temporary breakpoint to
312 establish the place to stop, then switch to go mode. Any other
313 breakpoint reached before the intended stop point will also stop
314 execution. @xref{Breakpoints}, for the details on breakpoints.
316 These commands may fail to work as expected in case of nonlocal exit,
317 because a nonlocal exit can bypass the temporary breakpoint where you
318 expected the program to stop.
322 Proceed to the stop point near where point is (@code{edebug-goto-here}).
325 Run the program forward over one expression
326 (@code{edebug-forward-sexp}).
329 Run the program until the end of the containing sexp.
332 Step into the function or macro called by the form after point.
335 The @kbd{h} command proceeds to the stop point near the current location
336 if point, using a temporary breakpoint. See @ref{Breakpoints}, for more
339 The @kbd{f} command runs the program forward over one expression. More
340 precisely, it sets a temporary breakpoint at the position that
341 @kbd{C-M-f} would reach, then executes in go mode so that the program
342 will stop at breakpoints.
344 With a prefix argument @var{n}, the temporary breakpoint is placed
345 @var{n} sexps beyond point. If the containing list ends before @var{n}
346 more elements, then the place to stop is after the containing
349 Be careful that the position @kbd{C-M-f} finds is a place that the
350 program will really get to; this may not be true in a
351 @code{cond}, for example.
353 The @kbd{f} command does @code{forward-sexp} starting at point, rather
354 than at the stop point, for flexibility. If you want to execute one
355 expression @emph{from the current stop point}, type @kbd{w} first, to
356 move point there, and then type @kbd{f}.
358 The @kbd{o} command continues ``out of'' an expression. It places a
359 temporary breakpoint at the end of the sexp containing point. If the
360 containing sexp is a function definition itself, @kbd{o} continues until
361 just before the last sexp in the definition. If that is where you are
362 now, it returns from the function and then stops. In other words, this
363 command does not exit the currently executing function unless you are
364 positioned after the last sexp.
366 The @kbd{i} command steps into the function or macro called by the list
367 form after point, and stops at its first stop point. Note that the form
368 need not be the one about to be evaluated. But if the form is a
369 function call about to be evaluated, remember to use this command before
370 any of the arguments are evaluated, since otherwise it will be too late.
372 The @kbd{i} command instruments the function or macro it's supposed to
373 step into, if it isn't instrumented already. This is convenient, but keep
374 in mind that the function or macro remains instrumented unless you explicitly
375 arrange to deinstrument it.
378 @subsection Miscellaneous Edebug Commands
380 Some miscellaneous Edebug commands are described here.
384 Display the help message for Edebug (@code{edebug-help}).
387 Abort one level back to the previous command level
388 (@code{abort-recursive-edit}).
391 Return to the top level editor command loop (@code{top-level}). This
392 exits all recursive editing levels, including all levels of Edebug
393 activity. However, instrumented code protected with
394 @code{unwind-protect} or @code{condition-case} forms may resume
398 Like @kbd{q} but don't stop even for protected code
399 (@code{top-level-nonstop}).
402 Redisplay the most recently known expression result in the echo area
403 (@code{edebug-previous-result}).
406 Display a backtrace, excluding Edebug's own functions for clarity
407 (@code{edebug-backtrace}).
409 You cannot use debugger commands in the backtrace buffer in Edebug as
410 you would in the standard debugger.
412 The backtrace buffer is killed automatically when you continue
416 From the Edebug recursive edit, you may invoke commands that activate
417 Edebug again recursively. Any time Edebug is active, you can quit to
418 the top level with @kbd{q} or abort one recursive edit level with
419 @kbd{C-]}. You can display a backtrace of all the
420 pending evaluations with @kbd{d}.
423 @subsection Breakpoints
426 Edebug's step mode stops execution at the next stop point reached.
427 There are three other ways to stop Edebug execution once it has started:
428 breakpoints, the global break condition, and source breakpoints.
430 While using Edebug, you can specify @dfn{breakpoints} in the program you
431 are testing: points where execution should stop. You can set a
432 breakpoint at any stop point, as defined in @ref{Using Edebug}. For
433 setting and unsetting breakpoints, the stop point that is affected is
434 the first one at or after point in the source code buffer. Here are the
435 Edebug commands for breakpoints:
439 Set a breakpoint at the stop point at or after point
440 (@code{edebug-set-breakpoint}). If you use a prefix argument, the
441 breakpoint is temporary (it turns off the first time it stops the
445 Unset the breakpoint (if any) at the stop point at or after
446 point (@code{edebug-unset-breakpoint}).
448 @item x @var{condition} @key{RET}
449 Set a conditional breakpoint which stops the program only if
450 @var{condition} evaluates to a non-@code{nil} value
451 (@code{edebug-set-conditional-breakpoint}). With a prefix argument, the
452 breakpoint is temporary.
455 Move point to the next breakpoint in the definition
456 (@code{edebug-next-breakpoint}).
459 While in Edebug, you can set a breakpoint with @kbd{b} and unset one
460 with @kbd{u}. First move point to the Edebug stop point of your choice,
461 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
462 Unsetting a breakpoint where none has been set has no effect.
464 Reevaluating or reinstrumenting a definition forgets all its breakpoints.
466 A @dfn{conditional breakpoint} tests a condition each time the program
467 gets there. Any errors that occur as a result of evaluating the
468 condition are ignored, as if the result were @code{nil}. To set a
469 conditional breakpoint, use @kbd{x}, and specify the condition
470 expression in the minibuffer. Setting a conditional breakpoint at a
471 stop point that has a previously established conditional breakpoint puts
472 the previous condition expression in the minibuffer so you can edit it.
474 You can make a conditional or unconditional breakpoint
475 @dfn{temporary} by using a prefix arg with the command to set the
476 breakpoint. When a temporary breakpoint stops the program, it is
479 Edebug always stops or pauses at a breakpoint except when the Edebug
480 mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
482 To find out where your breakpoints are, use the @kbd{B} command, which
483 moves point to the next breakpoint following point, within the same
484 function, or to the first breakpoint if there are no following
485 breakpoints. This command does not continue execution---it just moves
489 * Global Break Condition:: Breaking on an event.
490 * Source Breakpoints:: Embedding breakpoints in source code.
494 @node Global Break Condition
495 @subsubsection Global Break Condition
497 @cindex stopping on events
498 @cindex global break condition
499 A @dfn{global break condition} stops execution when a specified
500 condition is satisfied, no matter where that may occur. Edebug
501 evaluates the global break condition at every stop point. If it
502 evaluates to a non-@code{nil} value, then execution stops or pauses
503 depending on the execution mode, as if a breakpoint had been hit. If
504 evaluating the condition gets an error, execution does not stop.
506 @findex edebug-set-global-break-condition
507 @vindex edebug-global-break-condition
508 You can set or edit the condition expression, stored in
509 @code{edebug-global-break-condition}, using the @kbd{X} command
510 (@code{edebug-set-global-break-condition}).
512 The global break condition is the simplest way to find where in your
513 code some event occurs, but it makes code run much more slowly. So you
514 should reset the condition to @code{nil} when not using it.
516 @node Source Breakpoints
517 @subsubsection Source Breakpoints
520 @cindex source breakpoints
521 All breakpoints in a definition are forgotten each time you
522 reinstrument it. To make a breakpoint that won't be forgotten, you can
523 write a @dfn{source breakpoint}, which is simply a call to the function
524 @code{edebug} in your source code. You can, of course, make such a call
525 conditional. For example, in the @code{fac} function, insert the first
526 line as shown below to stop when the argument reaches zero:
530 (if (= n 0) (edebug))
536 When the @code{fac} definition is instrumented and the function is
537 called, the call to @code{edebug} acts as a breakpoint. Depending on
538 the execution mode, Edebug stops or pauses there.
540 If no instrumented code is being executed when @code{edebug} is called,
541 that function calls @code{debug}.
542 @c This may not be a good idea anymore.
544 @node Trapping Errors
545 @subsection Trapping Errors
547 Emacs normally displays an error message when an error is signaled and
548 not handled with @code{condition-case}. While Edebug is active, it
549 normally responds to all unhandled errors. You can customize this with
550 the options @code{edebug-on-error} and @code{edebug-on-quit}; see
551 @ref{Edebug Options}.
553 When Edebug responds to an error, it shows the last stop point
554 encountered before the error. This may be the location of a call to a
555 function which was not instrumented, within which the error actually
556 occurred. For an unbound variable error, the last known stop point
557 might be quite distant from the offending variable reference. In that
558 case you might want to display a full backtrace (@pxref{Edebug Misc}).
560 @c Edebug should be changed for the following: -- dan
561 If you change @code{debug-on-error} or @code{debug-on-quit} while
562 Edebug is active, these changes will be forgotten when Edebug becomes
563 inactive. Furthermore, during Edebug's recursive edit, these variables
564 are bound to the values they had outside of Edebug.
567 @subsection Edebug Views
569 These Edebug commands let you view aspects of the buffer and window
570 status that obtained before entry to Edebug. The outside window
571 configuration is the collection of windows and contents that were in
572 effect outside of Edebug.
576 Temporarily view the outside window configuration
577 (@code{edebug-view-outside}).
580 Temporarily display the outside current buffer with point at its outside
581 position (@code{edebug-bounce-point}). With a prefix argument @var{n},
582 pause for @var{n} seconds instead.
585 Move point back to the current stop point (@code{edebug-where}) in the
586 source code buffer. Also, if you use this command in a different window
587 displaying the same buffer, that window will be used instead to display
588 the current definition in the future.
591 @c Its function is not simply to forget the saved configuration -- dan
592 Toggle whether Edebug saves and restores the outside window
593 configuration (@code{edebug-toggle-save-windows}).
595 With a prefix argument, @code{W} only toggles saving and restoring of
596 the selected window. To specify a window that is not displaying the
597 source code buffer, you must use @kbd{C-x X W} from the global keymap.
600 You can view the outside window configuration with @kbd{v} or just
601 bounce to the point in the current buffer with @kbd{p}, even if
602 it is not normally displayed. After moving point, you may wish to jump
603 back to the stop point with @kbd{w} from a source code buffer.
605 Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
606 saved outside window configuration---so that even if you turn saving
607 back @emph{on}, the current window configuration remains unchanged when
608 you next exit Edebug (by continuing the program). However, the
609 automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
610 conflict with the buffers you wish to see unless you have enough windows
614 @subsection Evaluation
616 While within Edebug, you can evaluate expressions ``as if'' Edebug were
617 not running. Edebug tries to be invisible to the expression's
618 evaluation and printing. Evaluation of expressions that cause side
619 effects will work as expected except for things that Edebug explicitly
620 saves and restores. @xref{The Outside Context}, for details on this
624 @item e @var{exp} @key{RET}
625 Evaluate expression @var{exp} in the context outside of Edebug
626 (@code{edebug-eval-expression}). That is, Edebug tries to minimize its
627 interference with the evaluation.
629 @item M-@key{ESC} @var{exp} @key{RET}
630 Evaluate expression @var{exp} in the context of Edebug itself.
633 Evaluate the expression before point, in the context outside of Edebug
634 (@code{edebug-eval-last-sexp}).
637 @cindex lexical binding (Edebug)
638 Edebug supports evaluation of expressions containing references to
639 lexically bound symbols created by the following constructs in
640 @file{cl.el} (version 2.03 or later): @code{lexical-let},
641 @code{macrolet}, and @code{symbol-macrolet}.
645 @subsection Evaluation List Buffer
647 You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
648 evaluate expressions interactively. You can also set up the
649 @dfn{evaluation list} of expressions to be evaluated automatically each
650 time Edebug updates the display.
654 Switch to the evaluation list buffer @samp{*edebug*}
655 (@code{edebug-visit-eval-list}).
658 In the @samp{*edebug*} buffer you can use the commands of Lisp
659 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
660 Manual}) as well as these special commands:
664 Evaluate the expression before point, in the outside context, and insert
665 the value in the buffer (@code{edebug-eval-print-last-sexp}).
668 Evaluate the expression before point, in the context outside of Edebug
669 (@code{edebug-eval-last-sexp}).
672 Build a new evaluation list from the contents of the buffer
673 (@code{edebug-update-eval-list}).
676 Delete the evaluation list group that point is in
677 (@code{edebug-delete-eval-item}).
680 Switch back to the source code buffer at the current stop point
681 (@code{edebug-where}).
684 You can evaluate expressions in the evaluation list window with
685 @kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
686 but they are evaluated in the context outside of Edebug.
688 The expressions you enter interactively (and their results) are lost
689 when you continue execution; but you can set up an @dfn{evaluation list}
690 consisting of expressions to be evaluated each time execution stops.
692 @cindex evaluation list group
693 To do this, write one or more @dfn{evaluation list groups} in the
694 evaluation list buffer. An evaluation list group consists of one or
695 more Lisp expressions. Groups are separated by comment lines.
697 The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
698 evaluation list, scanning the buffer and using the first expression of
699 each group. (The idea is that the second expression of the group is the
700 value previously computed and displayed.)
702 Be careful not to add expressions that execute instrumented code since
703 that would cause an infinite loop.
704 @c There ought to be a way to fix this.
706 Each entry to Edebug redisplays the evaluation list by inserting each
707 expression in the buffer, followed by its current value. It also
708 inserts comment lines so that each expression becomes its own group.
709 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
710 the evaluation list is effectively unchanged.
712 If an error occurs during an evaluation from the evaluation list, the
713 error message is displayed in a string as if it were the result.
714 Therefore, expressions that use variables not currently valid do not
715 interrupt your debugging.
717 Here is an example of what the evaluation list window looks like after
718 several expressions have been added to it:
723 ;---------------------------------------------------------------
725 #<window 16 on *scratch*>
726 ;---------------------------------------------------------------
729 ;---------------------------------------------------------------
731 "Symbol's value as variable is void: bad-var"
732 ;---------------------------------------------------------------
735 ;---------------------------------------------------------------
738 ;---------------------------------------------------------------
741 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
742 delete the text for the group and update the evaluation list with
743 @kbd{C-c C-u}. To add a new expression to the evaluation list, insert
744 the expression at a suitable place, and insert a new comment line. (You
745 need not insert dashes in the comment line---its contents don't matter.)
746 Then type @kbd{C-c C-u}.
748 After selecting @samp{*edebug*}, you can return to the source code
749 buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
750 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 @vindex edebug-print-length
763 @vindex edebug-print-level
764 One way to cope with circular structure is to set @code{print-length}
765 or @code{print-level} to truncate the printing. Edebug does this for
766 you; it binds @code{print-length} and @code{print-level} to 50 if they
767 were @code{nil}. (Actually, the variables @code{edebug-print-length}
768 and @code{edebug-print-level} specify the values to use within Edebug.)
769 @xref{Output Variables}.
771 You can also print circular structures and structures that share
772 elements more informatively by using the @file{cust-print} package.
774 To load @file{cust-print} and activate custom printing only for
775 Edebug, simply use the command @kbd{M-x edebug-install-custom-print}.
776 To restore the standard print functions, use @kbd{M-x
777 edebug-uninstall-custom-print}.
779 Here is an example of code that creates a circular structure:
787 Custom printing prints this as @samp{Result: #1=(#1# y)}. The
788 @samp{#1=} notation labels the structure that follows it with the label
789 @samp{1}, and the @samp{#1#} notation references the previously labelled
790 structure. This notation is used for any shared elements of lists or
793 Other programs can also use custom printing; see @file{cust-print.el}
797 @subsection Trace Buffer
800 Edebug can record an execution trace, storing it in a buffer named
801 @samp{*edebug-trace*}. This is a log of function calls and returns,
802 showing the function names and their arguments and values. To enable
803 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
805 Making a trace buffer is not the same thing as using trace execution
806 mode (@pxref{Edebug Execution Modes}).
808 When trace recording is enabled, each function entry and exit adds
809 lines to the trace buffer. A function entry record looks like
810 @samp{::::@{} followed by the function name and argument values. A
811 function exit record looks like @samp{::::@}} followed by the function
812 name and result of the function.
814 The number of @samp{:}s in an entry shows its recursion depth. You
815 can use the braces in the trace buffer to find the matching beginning or
816 end of function calls.
818 @findex edebug-print-trace-before
819 @findex edebug-print-trace-after
820 You can customize trace recording for function entry and exit by
821 redefining the functions @code{edebug-print-trace-before} and
822 @code{edebug-print-trace-after}.
824 @defmac edebug-tracing string body@dots{}
825 This macro requests additional trace information around the execution
826 of the @var{body} forms. The argument @var{string} specifies text
827 to put in the trace buffer. All the arguments are evaluated.
828 @code{edebug-tracing} returns the value of the last form in @var{body}.
831 @defun edebug-trace format-string &rest format-args
832 This function inserts text in the trace buffer. It computes the text
833 with @code{(apply 'format @var{format-string} @var{format-args})}.
834 It also appends a newline to separate entries.
837 @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace
838 buffer even if Edebug is not active.
840 Adding text to the trace buffer also scrolls its window to show the
843 @node Coverage Testing
844 @subsection Coverage Testing
846 @cindex coverage testing
847 @cindex frequency counts
848 @cindex performance analysis
849 Edebug provides rudimentary coverage testing and display of execution
850 frequency. All execution of an instrumented function accumulates
851 frequency counts, both before and after evaluation of each instrumented
852 expression, even if the execution mode is Go-nonstop. Coverage testing
853 is more expensive, so it is only done if @code{edebug-test-coverage} is
854 non-@code{nil}. The command @kbd{M-x edebug-display-freq-count}
855 displays both the frequency data and the coverage data (if recorded).
857 @deffn Command edebug-display-freq-count
858 This command displays the frequency count data for each line of the
861 The frequency counts appear as comment lines after each line of code, and
862 you can undo all insertions with one @code{undo} command. The counts
863 appear under the @kbd{(} before an expression or the @kbd{)} after
864 an expression, or on the last character of a symbol. Values do not appear if
865 they are equal to the previous count on the same line.
867 The character @samp{=} following the count for an expression says that
868 the expression has returned the same value each time it was evaluated
869 This is the only coverage information that Edebug records.
871 To clear the frequency count and coverage data for a definition,
875 For example, after evaluating @code{(fac 5)} with a source
876 breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
877 the breakpoint is reached, the frequency data looks like this:
881 (if (= n 0) (edebug))
891 The comment lines show that @code{fac} was called 6 times. The
892 first @code{if} statement returned 5 times with the same result each
893 time; the same is true of the condition on the second @code{if}.
894 The recursive call of @code{fac} did not return at all.
897 @node The Outside Context
898 @subsection The Outside Context
900 Edebug tries to be transparent to the program you are debugging, but it
901 does not succeed completely. Edebug also tries to be transparent when
902 you evaluate expressions with @kbd{e} or with the evaluation list
903 buffer, by temporarily restoring the outside context. This section
904 explains precisely what context Edebug restores, and how Edebug fails to
905 be completely transparent.
908 * Checking Whether to Stop:: When Edebug decides what to do.
909 * Edebug Display Update:: When Edebug updates the display.
910 * Edebug Recursive Edit:: When Edebug stops execution.
913 @node Checking Whether to Stop
914 @subsubsection Checking Whether to Stop
916 Whenever Edebug is entered, it needs to save and restore certain data
917 before even deciding whether to make trace information or stop the
922 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
923 incremented one time to reduce Edebug's impact on the stack.
924 You could, however, still run out of stack space when using Edebug.
927 The state of keyboard macro execution is saved and restored. While
928 Edebug is active, @code{executing-macro} is bound to
929 @code{edebug-continue-kbd-macro}.
934 @node Edebug Display Update
935 @subsubsection Edebug Display Update
937 @c This paragraph is not filled, because LaLiberte's conversion script
938 @c needs an xref to be on just one line.
939 When Edebug needs to display something (e.g., in trace mode), it saves
940 the current window configuration from ``outside'' Edebug
941 (@pxref{Window Configurations}). When you exit Edebug (by continuing
942 the program), it restores the previous window configuration.
944 Emacs redisplays only when it pauses. Usually, when you continue
945 execution, the program comes back into Edebug at a breakpoint or after
946 stepping without pausing or reading input in between. In such cases,
947 Emacs never gets a chance to redisplay the ``outside'' configuration.
948 What you see is the same window configuration as the last time Edebug
949 was active, with no interruption.
951 Entry to Edebug for displaying something also saves and restores the
952 following data, but some of these are deliberately not restored if an
953 error or quit signal occurs.
957 @cindex current buffer point and mark (Edebug)
958 Which buffer is current, and the positions of point and the mark in the
959 current buffer, are saved and restored.
962 @cindex window configuration (Edebug)
963 The outside window configuration is saved and restored if
964 @code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Display Update}).
966 The window configuration is not restored on error or quit, but the
967 outside selected window @emph{is} reselected even on error or quit in
968 case a @code{save-excursion} is active. If the value of
969 @code{edebug-save-windows} is a list, only the listed windows are saved
972 The window start and horizontal scrolling of the source code buffer are
973 not restored, however, so that the display remains coherent within Edebug.
976 The value of point in each displayed buffer is saved and restored if
977 @code{edebug-save-displayed-buffer-points} is non-@code{nil}.
980 The variables @code{overlay-arrow-position} and
981 @code{overlay-arrow-string} are saved and restored. So you can safely
982 invoke Edebug from the recursive edit elsewhere in the same buffer.
985 @code{cursor-in-echo-area} is locally bound to @code{nil} so that
986 the cursor shows up in the window.
989 @node Edebug Recursive Edit
990 @subsubsection Edebug Recursive Edit
992 When Edebug is entered and actually reads commands from the user, it
993 saves (and later restores) these additional data:
997 The current match data. @xref{Match Data}.
1000 @code{last-command}, @code{this-command}, @code{last-command-char},
1001 @code{last-input-char}, @code{last-input-event},
1002 @code{last-command-event}, @code{last-event-frame},
1003 @code{last-nonmenu-event}, and @code{track-mouse}. Commands used within
1004 Edebug do not affect these variables outside of Edebug.
1006 The key sequence returned by @code{this-command-keys} is changed by
1007 executing commands within Edebug and there is no way to reset
1008 the key sequence from Lisp.
1010 Edebug cannot save and restore the value of
1011 @code{unread-command-events}. Entering Edebug while this variable has a
1012 nontrivial value can interfere with execution of the program you are
1016 Complex commands executed while in Edebug are added to the variable
1017 @code{command-history}. In rare cases this can alter execution.
1020 Within Edebug, the recursion depth appears one deeper than the recursion
1021 depth outside Edebug. This is not true of the automatically updated
1022 evaluation list window.
1025 @code{standard-output} and @code{standard-input} are bound to @code{nil}
1026 by the @code{recursive-edit}, but Edebug temporarily restores them during
1030 The state of keyboard macro definition is saved and restored. While
1031 Edebug is active, @code{defining-kbd-macro} is bound to
1032 @code{edebug-continue-kbd-macro}.
1035 @node Instrumenting Macro Calls
1036 @subsection Instrumenting Macro Calls
1038 When Edebug instruments an expression that calls a Lisp macro, it needs
1039 additional advice to do the job properly. This is because there is no
1040 way to tell which subexpressions of the macro call are forms to be
1041 evaluated. (Evaluation may occur explicitly in the macro body, or when
1042 the resulting expansion is evaluated, or any time later.) You must
1043 explain the format of calls to each macro to enable Edebug to handle it.
1044 To do this, use @code{def-edebug-spec} to define the format of
1045 calls to a given macro.
1047 @deffn Macro def-edebug-spec macro specification
1048 Specify which expressions of a call to macro @var{macro} are forms to be
1049 evaluated. For simple macros, the @var{specification} often looks very
1050 similar to the formal argument list of the macro definition, but
1051 specifications are much more general than macro arguments.
1053 The @var{macro} argument may actually be any symbol, not just a macro
1057 Here is a simple example that defines the specification for the
1058 @code{for} macro described in the Emacs Lisp Reference Manual, followed
1059 by an alternative, equivalent specification.
1062 (def-edebug-spec for
1063 (symbolp "from" form "to" form "do" &rest form))
1065 (def-edebug-spec for
1066 (symbolp ['from form] ['to form] ['do body]))
1069 Here is a table of the possibilities for @var{specification} and how each
1070 directs processing of arguments.
1075 All arguments are instrumented for evaluation.
1078 None of the arguments is instrumented.
1081 The symbol must have an Edebug specification which is used instead.
1082 This indirection is repeated until another kind of specification is
1083 found. This allows you to inherit the specification for another macro.
1086 The elements of the list describe the types of the arguments of a
1087 calling form. The possible elements of a specification list are
1088 described in the following sections.
1092 * Specification List:: How to specify complex patterns of evaluation.
1093 * Backtracking:: What Edebug does when matching fails.
1094 * Specification Examples:: To help understand specifications.
1098 @node Specification List
1099 @subsubsection Specification List
1101 @cindex Edebug specification list
1102 A @dfn{specification list} is required for an Edebug specification if
1103 some arguments of a macro call are evaluated while others are not. Some
1104 elements in a specification list match one or more arguments, but others
1105 modify the processing of all following elements. The latter, called
1106 @dfn{specification keywords}, are symbols beginning with @samp{&} (such
1107 as @code{&optional}).
1109 A specification list may contain sublists which match arguments that are
1110 themselves lists, or it may contain vectors used for grouping. Sublists
1111 and groups thus subdivide the specification list into a hierarchy of
1112 levels. Specification keywords only apply to the remainder of the
1113 sublist or group they are contained in.
1115 When a specification list involves alternatives or repetition, matching
1116 it against an actual macro call may require backtracking.
1117 @xref{Backtracking}, for more details.
1119 Edebug specifications provide the power of regular expression matching,
1120 plus some context-free grammar constructs: the matching of sublists with
1121 balanced parentheses, recursive processing of forms, and recursion via
1122 indirect specifications.
1124 Here's a table of the possible elements of a specification list, with
1129 A single Lisp object, not unevaluated.
1130 @c "unevaluated expression" is not meaningful, because
1131 @c an expression is a Lisp object intended for evaluation.
1134 A single evaluated expression, which is instrumented.
1137 @findex edebug-unwrap
1138 A place to store a value, as in the Common Lisp @code{setf} construct.
1141 Short for @code{&rest form}. See @code{&rest} below.
1144 A function form: either a quoted function symbol, a quoted lambda
1145 expression, or a form (that should evaluate to a function symbol or
1146 lambda expression). This is useful when an argument that's a lambda
1147 expression might be quoted with @code{quote} rather than
1148 @code{function}, since it instruments the body of the lambda expression
1152 A lambda expression with no quoting.
1155 @kindex &optional @r{(Edebug)}
1156 All following elements in the specification list are optional; as soon
1157 as one does not match, Edebug stops matching at this level.
1159 To make just a few elements optional followed by non-optional elements,
1160 use @code{[&optional @var{specs}@dots{}]}. To specify that several
1161 elements must all match or none, use @code{&optional
1162 [@var{specs}@dots{}]}. See the @code{defun} example below.
1165 @kindex &rest @r{(Edebug)}
1166 All following elements in the specification list are repeated zero or
1167 more times. All the elements need not match in the last repetition,
1170 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
1171 To specify several elements that must all match on every repetition, use
1172 @code{&rest [@var{specs}@dots{}]}.
1175 @kindex &or @r{(Edebug)}
1176 Each of the following elements in the specification list is an
1177 alternative. One of the alternatives must match, or the @code{&or}
1178 specification fails.
1180 Each list element following @code{&or} is a single alternative. To
1181 group two or more list elements as a single alternative, enclose them in
1185 @kindex ¬ @r{(Edebug)}
1186 Each of the following elements is matched as alternatives as if by using
1187 @code{&or}, but if any of them match, the specification fails. If none
1188 of them match, nothing is matched, but the @code{¬} specification
1192 @kindex &define @r{(Edebug)}
1193 Indicates that the specification is for a defining form. The defining
1194 form itself is not instrumented (i.e. Edebug does not stop before and
1195 after the defining form), but forms inside it typically will be
1196 instrumented. The @code{&define} keyword should be the first element in
1197 a list specification.
1200 This is successful when there are no more arguments to match at the
1201 current argument list level; otherwise it fails. See sublist
1202 specifications and the backquote example below.
1205 @cindex preventing backtracking
1206 No argument is matched but backtracking through the gate is disabled
1207 while matching the remainder of the specifications at this level. This
1208 is primarily used to generate more specific syntax error messages. See
1209 @ref{Backtracking}, for more details. Also see the @code{let} example
1212 @item @var{other-symbol}
1213 @cindex indirect specifications
1214 Any other symbol in a specification list may be a predicate or an
1215 indirect specification.
1217 If the symbol has an Edebug specification, this @dfn{indirect
1218 specification} should be either a list specification that is used in
1219 place of the symbol, or a function that is called to process the
1220 arguments. The specification may be defined with @code{def-edebug-spec}
1221 just as for macros. See the @code{defun} example below.
1223 Otherwise, the symbol should be a predicate. The predicate is called
1224 with the argument and the specification fails if the predicate returns
1225 @code{nil}. In either case, that argument is not instrumented.
1227 Some suitable predicates include @code{symbolp}, @code{integerp},
1228 @code{stringp}, @code{vectorp}, and @code{atom}.
1230 @item [@var{elements}@dots{}]
1231 @cindex [@dots{}] (Edebug)
1232 A vector of elements groups the elements into a single @dfn{group
1233 specification}. Its meaning has nothing to do with vectors.
1235 @item "@var{string}"
1236 The argument should be a symbol named @var{string}. This specification
1237 is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
1238 of @var{symbol} is the @var{string}, but the string form is preferred.
1240 @item (vector @var{elements}@dots{})
1241 The argument should be a vector whose elements must match the
1242 @var{elements} in the specification. See the backquote example below.
1244 @item (@var{elements}@dots{})
1245 Any other list is a @dfn{sublist specification} and the argument must be
1246 a list whose elements match the specification @var{elements}.
1248 @cindex dotted lists (Edebug)
1249 A sublist specification may be a dotted list and the corresponding list
1250 argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
1251 dotted list specification may be another sublist specification (via a
1252 grouping or an indirect specification, e.g. @code{(spec . [(more
1253 specs@dots{})])}) whose elements match the non-dotted list arguments.
1254 This is useful in recursive specifications such as in the backquote
1255 example below. Also see the description of a @code{nil} specification
1256 above for terminating such recursion.
1258 Note that a sublist specification written as @code{(specs . nil)}
1259 is equivalent to @code{(specs)}, and @code{(specs .
1260 (sublist-elements@dots{}))} is equivalent to @code{(specs
1261 sublist-elements@dots{})}.
1264 @c Need to document extensions with &symbol and :symbol
1266 Here is a list of additional specifications that may only appear after
1267 @code{&define}. See the @code{defun} example below.
1271 The argument, a symbol, is the name of the defining form.
1273 A defining form is not required to have a name field; and it may have
1274 multiple name fields.
1277 This construct does not actually match an argument. The element
1278 following @code{:name} should be a symbol; it is used as an additional
1279 name component for the definition. You can use this to add a unique,
1280 static component to the name of the definition. It may be used more
1284 The argument, a symbol, is the name of an argument of the defining form.
1285 However, lambda list keywords (symbols starting with @samp{@code{&}})
1289 @cindex lambda-list (Edebug)
1290 This matches a lambda list---the argument list of a lambda expression.
1293 The argument is the body of code in a definition. This is like
1294 @code{body}, described above, but a definition body must be instrumented
1295 with a different Edebug call that looks up information associated with
1296 the definition. Use @code{def-body} for the highest level list of forms
1297 within the definition.
1300 The argument is a single, highest-level form in a definition. This is
1301 like @code{def-body}, except use this to match a single form rather than
1302 a list of forms. As a special case, @code{def-form} also means that
1303 tracing information is not output when the form is executed. See the
1304 @code{interactive} example below.
1308 @subsubsection Backtracking
1310 @cindex backtracking
1311 @cindex syntax error (Edebug)
1312 If a specification fails to match at some point, this does not
1313 necessarily mean a syntax error will be signaled; instead,
1314 @dfn{backtracking} will take place until all alternatives have been
1315 exhausted. Eventually every element of the argument list must be
1316 matched by some element in the specification, and every required element
1317 in the specification must match some argument.
1319 Backtracking is disabled for the remainder of a sublist or group when
1320 certain conditions occur, described below. Backtracking is reenabled
1321 when a new alternative is established by @code{&optional}, @code{&rest},
1322 or @code{&or}. It is also reenabled initially when processing a
1323 sublist or group specification or an indirect specification.
1325 You might want to disable backtracking to commit to some alternative so
1326 that Edebug can provide a more specific syntax error message. Normally,
1327 if no alternative matches, Edebug reports that none matched, but if one
1328 alternative is committed to, Edebug can report how it failed to match.
1330 First, backtracking is disabled while matching any of the form
1331 specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
1332 @code{def-body}). These specifications will match any form so any error
1333 must be in the form itself rather than at a higher level.
1335 Second, backtracking is disabled after successfully matching a quoted
1336 symbol or string specification, since this usually indicates a
1337 recognized construct. If you have a set of alternative constructs that
1338 all begin with the same symbol, you can usually work around this
1339 constraint by factoring the symbol out of the alternatives, e.g.,
1340 @code{["foo" &or [first case] [second case] ...]}.
1342 Third, backtracking may be explicitly disabled by using the
1343 @code{gate} specification. This is useful when you know that
1344 no higher alternatives may apply.
1346 @node Specification Examples
1347 @subsubsection Specification Examples
1349 It may be easier to understand Edebug specifications by studying
1350 the examples provided here.
1352 A @code{let} special form has a sequence of bindings and a body. Each
1353 of the bindings is either a symbol or a sublist with a symbol and
1354 optional value. In the specification below, notice the @code{gate}
1355 inside of the sublist to prevent backtracking once a sublist is found.
1358 (def-edebug-spec let
1360 &or symbolp (gate symbolp &optional form))
1364 Edebug uses the following specifications for @code{defun} and
1365 @code{defmacro} and the associated argument list and @code{interactive}
1366 specifications. It is necessary to handle interactive forms specially
1367 since an expression argument it is actually evaluated outside of the
1371 (def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
1372 (def-edebug-spec defun
1373 (&define name lambda-list
1374 [&optional stringp] ; @r{Match the doc string, if present.}
1375 [&optional ("interactive" interactive)]
1378 (def-edebug-spec lambda-list
1380 [&optional ["&optional" arg &rest arg]]
1381 &optional ["&rest" arg]
1384 (def-edebug-spec interactive
1385 (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
1388 The specification for backquote below illustrates how to match
1389 dotted lists and use @code{nil} to terminate recursion. It also
1390 illustrates how components of a vector may be matched. (The actual
1391 specification defined by Edebug does not support dotted lists because
1392 doing so causes very deep recursion that could fail.)
1395 (def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
1397 (def-edebug-spec backquote-form
1398 (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
1399 (backquote-form . [&or nil backquote-form])
1400 (vector &rest backquote-form)
1405 @node Edebug Options
1406 @subsection Edebug Options
1408 These options affect the behavior of Edebug:
1410 @defopt edebug-setup-hook
1411 Functions to call before Edebug is used. Each time it is set to a new
1412 value, Edebug will call those functions once and then
1413 @code{edebug-setup-hook} is reset to @code{nil}. You could use this to
1414 load up Edebug specifications associated with a package you are using
1415 but only when you also use Edebug.
1416 @xref{Instrumenting}.
1419 @defopt edebug-all-defs
1420 If this is non-@code{nil}, normal evaluation of defining forms such as
1421 @code{defun} and @code{defmacro} instruments them for Edebug. This
1422 applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
1423 and @code{eval-current-buffer}.
1425 Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
1426 option. @xref{Instrumenting}.
1429 @defopt edebug-all-forms
1430 If this is non-@code{nil}, the commands @code{eval-defun},
1431 @code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
1432 instrument all forms, even those that don't define anything.
1433 This doesn't apply to loading or evaluations in the minibuffer.
1435 Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
1436 option. @xref{Instrumenting}.
1439 @defopt edebug-save-windows
1440 If this is non-@code{nil}, Edebug saves and restores the window
1441 configuration. That takes some time, so if your program does not care
1442 what happens to the window configurations, it is better to set this
1443 variable to @code{nil}.
1445 If the value is a list, only the listed windows are saved and
1448 You can use the @kbd{W} command in Edebug to change this variable
1449 interactively. @xref{Edebug Display Update}.
1452 @defopt edebug-save-displayed-buffer-points
1453 If this is non-@code{nil}, Edebug saves and restores point in all
1456 Saving and restoring point in other buffers is necessary if you are
1457 debugging code that changes the point of a buffer which is displayed in
1458 a non-selected window. If Edebug or the user then selects the window,
1459 point in that buffer will move to the window's value of point.
1461 Saving and restoring point in all buffers is expensive, since it
1462 requires selecting each window twice, so enable this only if you need
1463 it. @xref{Edebug Display Update}.
1466 @defopt edebug-initial-mode
1467 If this variable is non-@code{nil}, it specifies the initial execution
1468 mode for Edebug when it is first activated. Possible values are
1469 @code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
1470 @code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
1472 The default value is @code{step}.
1473 @xref{Edebug Execution Modes}.
1476 @defopt edebug-trace
1477 @findex edebug-print-trace-before
1478 @findex edebug-print-trace-after
1479 Non-@code{nil} means display a trace of function entry and exit.
1480 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
1481 function entry or exit per line, indented by the recursion level.
1483 The default value is @code{nil}.
1485 Also see @code{edebug-tracing}, in @xref{Trace Buffer}.
1488 @defopt edebug-test-coverage
1489 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
1490 This is done by comparing the result of each expression
1491 with the previous result. Coverage is considered OK if two different
1492 results are found. So to sufficiently test the coverage of your code,
1493 try to execute it under conditions that evaluate all expressions more
1494 than once, and produce different results for each expression.
1496 Use @kbd{M-x edebug-display-freq-count} to display the frequency count
1497 and coverage information for a definition.
1498 @xref{Coverage Testing}.
1501 @defopt edebug-continue-kbd-macro
1502 If non-@code{nil}, continue defining or executing any keyboard macro
1503 that is executing outside of Edebug. Use this with caution since it is not
1505 @xref{Edebug Execution Modes}.
1508 @defopt edebug-print-length
1509 If non-@code{nil}, bind @code{print-length} to this while printing
1510 results in Edebug. The default value is @code{50}.
1511 @xref{Printing in Edebug}.
1514 @defopt edebug-print-level
1515 If non-@code{nil}, bind @code{print-level} to this while printing
1516 results in Edebug. The default value is @code{50}.
1519 @defopt edebug-print-circle
1520 If non-@code{nil}, bind @code{print-circle} to this while printing
1521 results in Edebug. The default value is @code{nil}.
1524 @defopt edebug-on-error
1525 Edebug binds @code{debug-on-error} to this value, if
1526 @code{debug-on-error} was previously @code{nil}. @xref{Trapping
1530 @defopt edebug-on-quit
1531 Edebug binds @code{debug-on-quit} to this value, if
1532 @code{debug-on-quit} was previously @code{nil}. @xref{Trapping
1536 If you change the values of @code{edebug-on-error} or
1537 @code{edebug-on-quit} while Edebug is active, their values won't be used
1538 until the @emph{next} time Edebug is invoked via a new command.
1539 @c Not necessarily a deeper command level.
1540 @c A new command is not precisely true, but that is close enough -- dan
1542 @defopt edebug-global-break-condition
1543 If non-@code{nil}, an expression to test for at every stop point.
1544 If the result is non-nil, then break. Errors are ignored.
1545 @xref{Global Break Condition}.