When Edebug instruments an expression that calls a Lisp macro, it needs additional information about the macro to do the job properly. This is because there is no a-priori way to tell which subexpressions of the macro call are forms to be evaluated. (Evaluation may occur explicitly in the macro body, or when the resulting expansion is evaluated, or any time later.)
Therefore, you must define an Edebug specification for each macro
that Edebug will encounter, to explain the format of calls to that
macro. To do this, add a debug
declaration to the macro
definition. Here is a simple example that shows the specification for
the for
example macro (see Evaluating Macro Arguments Repeatedly).
(defmacro for (var from init to final do &rest body) "Execute a simple \"for\" loop. For example, (for i from 1 to 10 do (print i))." (declare (debug (symbolp "from" form "to" form "do" &rest form))) ...)
The Edebug specification says which parts of a call to the macro are
forms to be evaluated. For simple macros, the specification
often looks very similar to the formal argument list of the macro
definition, but specifications are much more general than macro
arguments. See Defining Macros, for more explanation of
the declare
form.
Take care to ensure that the specifications are known to Edebug when
you instrument code. If you are instrumenting a function which uses a
macro defined in another file, you may first need to either evaluate
the require
forms in the file containing your function, or
explicitly load the file containing the macro. If the definition of a
macro is wrapped by eval-when-compile
, you may need to evaluate
it.
You can also define an edebug specification for a macro separately
from the macro definition with def-edebug-spec
. Adding
debug
declarations is preferred, and more convenient, for macro
definitions in Lisp, but def-edebug-spec
makes it possible to
define Edebug specifications for special forms implemented in C.
Specify which expressions of a call to macro macro are forms to be evaluated. specification should be the Edebug specification. Neither argument is evaluated.
The macro argument can actually be any symbol, not just a macro name.
Here is a table of the possibilities for specification and how each directs processing of arguments.
t
All arguments are instrumented for evaluation.
This is short for (body)
.
The symbol must have an Edebug specification, which is used instead. This indirection is repeated until another kind of specification is found. This allows you to inherit the specification from another macro.
The elements of the list describe the types of the arguments of a calling form. The possible elements of a specification list are described in the following sections.
If a macro has no Edebug specification, neither through a debug
declaration nor through a def-edebug-spec
call, the variable
edebug-eval-macro-args
comes into play.
This controls the way Edebug treats macro arguments with no explicit
Edebug specification. If it is nil
(the default), none of the
arguments is instrumented for evaluation. Otherwise, all arguments
are instrumented.