To debug a Emacs Lisp program with Edebug, you must first instrument the Lisp functions that you want to debug. See section Instrumenting for Edebug.
Once a function is instrumented, any call to the function activates
Edebug. Activating Edebug may stop execution and let you step through
the function, or it may update the display and continue execution while
checking for debugging commands, depending on the selected Edebug
execution mode. The initial execution mode is step, by default,
which does stop execution. See section Edebug Execution Modes.
Within Edebug, you normally view an Emacs buffer showing the source of the Lisp function you are debugging. We call this the Edebug buffer---but note that it is not always the same buffer, and it is not reserved for Edebug use.
An arrow at the left margin indicates the line where the function is executing. Point initially shows where within the line the function is executing, but this ceases to be true if you move point yourself.
If you instrument the definition of fac (shown below) for Edebug and
then execute (fac 3), here is what you normally see. Point is at
the open-parenthesis before if.
(defun fac (n)
=>-!-(if (< 0 n)
(* n (fac (1- n)))
1))
The places within a function where Edebug can stop execution are called
stop points. These occur both before and after each subexpression
that is a list, and also after each variable reference.
Here we show with periods the stop points found in the function
fac:
(defun fac (n)
.(if .(< 0 n.).
.(* n. .(fac (1- n.).).).
1).)
While a buffer is the Edebug buffer, the special commands of Edebug are available in it, instead of many usual editing commands. Type ? to display a list of Edebug commands. In particular, you can exit just the innermost Edebug activation level with C-], and you can return all the way to top level with q.
For example, you can type the Edebug command SPC to execute until
the next stop point. If you type SPC once after entry to
fac, here is the state that you get:
(defun fac (n)
=>(if -!-(< 0 n)
(* n (fac (1- n)))
1))
When Edebug stops execution after an expression, it displays the expression's value in the echo area. Use the r command to display the value again later.
If no instrumented code is currently being executed, debug is run
normally. But while Edebug is active, it catches all errors (if
debug-on-error is non-nil) and quits (if
debug-on-quit is non-nil). When this happens, Edebug
displays the last stop point that it knows about. This may be the
location of a call to a function which was not instrumented, within
which the error actually occurred. Note that you can also get a full
backtrace inside of Edebug (see section Miscellaneous).