GNU Info

(elisp)Instrumenting

---

Next: Edebug Execution Modes Prev: Using Edebug Up: Edebug

---

Enter node , (file) or (file)node

Instrumenting for Edebug
------------------------

   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.

   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: 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',
`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 values of
`edebug-all-defs' and `edebug-all-forms'.

   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.  This is possible
only if Edebug knows where to find the source for that function; for
this reading, after loading Edebug, `eval-region' records the position
of every definition it evaluates, even if not instrumenting it.  See
also the `i' command (Note: 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; see Note:
Instrumenting Macro Calls, for details.

   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 (Note: Instrumenting
Macro Calls) associated with a package you are using, but only when
you use Edebug.

   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-:').

   If Edebug detects a syntax error while instrumenting, it leaves point
at the erroneous code and signals an `invalid-read-syntax' error.

   Note: Edebug Eval, for other evaluation functions available inside
of Edebug.