22.4.2 Instrumenting for Edebug

In order to use Edebug to debug Lisp code, you must first instrument the code. Instrumenting a form inserts additional code into it which invokes Edebug at the proper places. Furthermore, if Edebug detects a syntax error while instrumenting, point is left at the erroneous code and an invalid-read-syntax error is signaled.

Once you have loaded Edebug, the command C-M-x (eval-defun) is redefined so that when invoked with a prefix argument on a definition, it instruments the definition before evaluating it. The source code itself is not modified. If the variable edebug-all-defs is non-nil, that inverts the meaning of the prefix argument: then 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, eval-current-buffer, 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 value of edebug-all-defs or edebug-all-forms.

Just before Edebug instruments any code, it calls any functions in the variable edebug-setup-hook and resets its value to nil. You could use this to load up Edebug specifications associated with a package you are using but only when you also use Edebug. For example, my-specs.el may be loaded automatically when you use my-package with Edebug by including the following code in my-package.el.

(add-hook 'edebug-setup-hook
  (function (lambda () (require 'my-specs))))

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 is not already instrumented. If the location of the definition is not known to Edebug, this command cannot be used. After loading Edebug, eval-region records the position of every definition it evaluates, even if not instrumenting it. Also see the command i (Jumping) which steps into the callee.

Edebug knows how to instrument all the standard special forms, an interactive form with an expression argument, anonymous lambda expressions, and other defining forms. Specifications for macros defined by cl.el (version 2.03) are provided in cl-specs.el. Edebug cannot know what a user-defined macro will do with the arguments of a macro call so you must tell it. See Instrumenting Macro Calls for the details.

Note that a couple ways remain to evaluate expressions without instrumenting them. Loading a file via the load subroutine does not instrument expressions for Edebug. Evaluations in the minibuffer via eval-expression (M-ESC) are not instrumented.

To remove instrumentation from a definition, simply reevaluate it with one of the non-instrumenting commands, or reload the file.

See Edebug Eval for other evaluation functions available inside of Edebug.