Info Catalog elisp: Using Edebug elisp: Edebug elisp: Edebug Execution Modes

elisp: Instrumenting

 
 17.2.2 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.
 
    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’,
 ‘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’.  ‘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 (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, 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.
 
    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.
 
    Edebug Eval, for other evaluation functions available inside
 of Edebug.
 

Info Catalog elisp: Using Edebug elisp: Edebug elisp: Edebug Execution Modes