In order to use Edebug to debug Lisp code, you must first instrument the code. Instrumenting code inserts additional code into it, to invoke Edebug at the proper places.
When you invoke command C-M-x (eval-defun) with a
prefix argument on a function definition, it instruments the
definition before evaluating it. (This does not modify the source
code itself.) If the variable edebug-all-defs is
non-nil, that inverts the meaning of the prefix argument: in
this case, C-M-x instruments the definition unless it has
a prefix argument. The default value of edebug-all-defs is
nil. The command M-x edebug-all-defs toggles the value
of the variable edebug-all-defs.
If edebug-all-defs is non-nil, then the commands
eval-region, and eval-buffer also instrument any
definitions they evaluate. Similarly, edebug-all-forms
controls whether eval-region should instrument any form,
even non-defining forms. This doesn’t apply to loading or evaluations
in the minibuffer. The command M-x edebug-all-forms toggles
this option.
Another command, M-x edebug-eval-top-level-form, is available to
instrument any top-level form regardless of the values of
edebug-all-defs and edebug-all-forms.
edebug-defun is an alias for edebug-eval-top-level-form.
While Edebug is active, the command I
(edebug-instrument-callee) instruments the definition of the
function or macro called by the list form after point, if it is not already
instrumented. This is possible only if Edebug knows where to find the
source for that function; for this reason, after loading Edebug,
eval-region records the position of every definition it
evaluates, even if not instrumenting it. See also the i command
(see Jumping), which steps into the call after instrumenting the
function.
Edebug knows how to instrument all the standard special forms,
interactive forms with an expression argument, anonymous lambda
expressions, and other defining forms. However, Edebug cannot determine
on its own what a user-defined macro will do with the arguments of a
macro call, so you must provide that information using Edebug
specifications; for details, see Edebug and Macros.
When Edebug is about to instrument code for the first time in a
session, it runs the hook edebug-setup-hook, then sets it to
nil. You can use this to load Edebug specifications
associated with a package you are using, but only when you use Edebug.
If Edebug detects a syntax error while instrumenting, it leaves point
at the erroneous code and signals an invalid-read-syntax error.
Example:
error→ Invalid read syntax: "Expected lambda expression"
One potential reason for such a failure to instrument is that some macro definitions are not yet known to Emacs. To work around this, load the file which defines the function you are about to instrument.
To remove instrumentation from a definition, simply re-evaluate its
definition in a way that does not instrument. There are two ways of
evaluating forms that never instrument them: from a file with
load, and from the minibuffer with eval-expression
(M-:).
A different way to remove the instrumentation from a definition is
to use the edebug-remove-instrumentation command. It also
allows removing the instrumentation from everything that has been
instrumented.
See Evaluation, for other evaluation functions available inside of Edebug.