@comment -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1992-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1992-1994, 1998-1999, 2001-2013 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c This file can also be used by an independent Edebug User
@c , Bugs and Todo List, Top, Top
-@node Edebug, Syntax Errors, Debugger, Debugging
+@node Edebug
@section Edebug
@cindex Edebug debugging facility
@node Instrumenting
@subsection Instrumenting for Edebug
+@cindex instrumenting for Edebug
In order to use Edebug to debug Lisp code, you must first
@dfn{instrument} the code. Instrumenting code inserts additional code
edebug-all-forms} toggles this option.
@findex edebug-eval-top-level-form
+@findex edebug-defun
Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
instrument any top-level form regardless of the values of
@code{edebug-all-defs} and @code{edebug-all-forms}.
+@code{edebug-defun} is an alias for @code{edebug-eval-top-level-form}.
While Edebug is active, the command @kbd{I}
(@code{edebug-instrument-callee}) instruments the definition of the
saved outside window configuration---so that even if you turn saving
back @emph{on}, the current window configuration remains unchanged when
you next exit Edebug (by continuing the program). However, the
-automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
+automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may
conflict with the buffers you wish to see unless you have enough windows
open.
@node Eval List
@subsection Evaluation List Buffer
- You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+ You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to
evaluate expressions interactively. You can also set up the
@dfn{evaluation list} of expressions to be evaluated automatically each
time Edebug updates the display.
@table @kbd
@item E
-Switch to the evaluation list buffer @samp{*edebug*}
+Switch to the evaluation list buffer @file{*edebug*}
(@code{edebug-visit-eval-list}).
@end table
- In the @samp{*edebug*} buffer you can use the commands of Lisp
+ In the @file{*edebug*} buffer you can use the commands of Lisp
Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
Manual}) as well as these special commands:
@end table
You can evaluate expressions in the evaluation list window with
-@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+@kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*};
but they are evaluated in the context outside of Edebug.
The expressions you enter interactively (and their results) are lost
@kbd{C-c C-u}. You need not insert dashes in the comment line---its
contents don't matter.
-After selecting @samp{*edebug*}, you can return to the source code
-buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
+After selecting @file{*edebug*}, you can return to the source code
+buffer with @kbd{C-c C-w}. The @file{*edebug*} buffer is killed when
you continue execution, and recreated next time it is needed.
@node Printing in Edebug
@cindex trace buffer
Edebug can record an execution trace, storing it in a buffer named
-@samp{*edebug-trace*}. This is a log of function calls and returns,
+@file{*edebug-trace*}. This is a log of function calls and returns,
showing the function names and their arguments and values. To enable
trace recording, set @code{edebug-trace} to a non-@code{nil} value.
@c needs an xref to be on just one line.
When Edebug needs to display something (e.g., in trace mode), it saves
the current window configuration from ``outside'' Edebug
-(@pxref{Window Configurations}). When you exit Edebug (by continuing
-the program), it restores the previous window configuration.
+(@pxref{Window Configurations}). When you exit Edebug, it restores
+the previous window configuration.
Emacs redisplays only when it pauses. Usually, when you continue
execution, the program re-enters Edebug at a breakpoint or after
@item
The variables @code{last-command}, @code{this-command},
-@code{last-input-event}, @code{last-command-event},
+@code{last-command-event}, @code{last-input-event},
@code{last-event-frame}, @code{last-nonmenu-event}, and
-@code{track-mouse}. Commands used within Edebug do not affect these
-variables outside of Edebug.
+@code{track-mouse}. Commands in Edebug do not affect these variables
+outside of Edebug.
Executing commands within Edebug can change the key sequence that
would be returned by @code{this-command-keys}, and there is no way to
arguments. @xref{Defining Macros}, for more explanation of
the @code{declare} form.
+@c See, e.g., http://debbugs.gnu.org/10577
+@c FIXME Maybe there should be an Edebug option to get it to
+@c automatically load the entire source file containing the function
+@c being instrumented. That would avoid this.
+ Take care to ensure that the specifications are known to Edebug when
+you instrument code. If you are instrumenting a function from a file
+that uses @code{eval-when-compile} to require another file containing
+macro definitions, you may need to explicitly load that file.
+
You can also define an edebug specification for a macro separately
from the macro definition with @code{def-edebug-spec}. Adding
@code{debug} declarations is preferred, and more convenient, for macro
A single evaluated expression, which is instrumented.
@item place
-@c I can't see that this index entry is useful without any explanation.
-@c @findex edebug-unwrap
-A place to store a value, as in the Common Lisp @code{setf} construct.
+A generalized variable. @xref{Generalized Variables}.
@item body
Short for @code{&rest form}. See @code{&rest} below.
of them match, nothing is matched, but the @code{¬} specification
succeeds.
+@c FIXME &key?
+
@item &define
@c @kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form. The defining
optional expression. In the specification below, notice the @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.
-@c FIXME? The actual definition in edebug.el does not have a gate.
+@ignore
+@c FIXME? The actual definition in edebug.el looks like this (and always
+@c has AFAICS). In fact, nothing in edebug.el uses gate. So maybe
+@c this is just an example for illustration?
+(def-edebug-spec let
+ ((&rest
+ &or (symbolp &optional form) symbolp)
+ body))
+@end ignore
@example
(def-edebug-spec let
((&rest
@defopt edebug-trace
If this is non-@code{nil}, trace each function entry and exit.
-Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
+Tracing output is displayed in a buffer named @file{*edebug-trace*}, one
function entry or exit per line, indented by the recursion level.
Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
@xref{Edebug Execution Modes}.
@end defopt
-@c FIXME edebug-unwrap-results
+@defopt edebug-unwrap-results
+If non-@code{nil}, Edebug tries to remove any of its own
+instrumentation when showing the results of expressions. This is
+relevant when debugging macros where the results of expressions are
+themselves instrumented expressions. As a very artificial example,
+suppose that the example function @code{fac} has been instrumented,
+and consider a macro of the form:
+
+@c FIXME find a less silly example.
+@smallexample
+(defmacro test () "Edebug example."
+ (if (symbol-function 'fac)
+ @dots{}))
+@end smallexample
+
+If you instrument the @code{test} macro and step through it, then by
+default the result of the @code{symbol-function} call has numerous
+@code{edebug-after} and @code{edebug-before} forms, which can make it
+difficult to see the ``actual'' result. If
+@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove
+these forms from the result.
+@end defopt
@defopt edebug-on-error
Edebug binds @code{debug-on-error} to this value, if
HCoop / bpt / emacs.git / blobdiff