22.4.1 Using Edebug

To debug a SXEmacs Lisp program with Edebug, you must first instrument the Lisp code that you want to debug. If you want to just try it now, load edebug.el, move point into a definition and do C-u C-M-x (eval-defun with a prefix argument). See Instrumenting for alternative ways to instrument code.

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 Edebug Execution Modes.

Within Edebug, you normally view an SXEmacs buffer showing the source of the Lisp function you are debugging. This is referred to as the source code buffer—but note that it is not always the same buffer depending on which function is currently being executed.

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 you can move point yourself.

If you instrument the definition of fac (shown below) 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 the source code buffer is selected, the special commands of Edebug are available in it, in addition to the commands of SXEmacs Lisp mode. The buffer is temporarily made read-only, however. 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 display you will see:

(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.

Other frequently used commands are b to set a breakpoint at a stop point, g to execute until a breakpoint is reached, and q to exit to the top-level command loop. Type ? to display a list of all Edebug commands.