Node:debug-on-entry, Next:debug-on-quit, Previous:debug, Up:Debugging

17.2 debug-on-entry

GNU Emacs 21 starts the debugger automatically when your function has an error. GNU Emacs version 20 and before did not; it simply presented you with an error message. You had to start the debugger manually.

You can start the debugger manually for all versions of Emacs; the advantage is that the debugger runs even if you do not have a bug in your code. Sometimes your code will be free of bugs!

You can enter the debugger when you call the function by calling debug-on-entry.

Type:

M-x debug-on-entry RET triangle-bugged RET

Now, evaluate the following:

(triangle-bugged 5)

All versions of Emacs will create a *Backtrace* buffer and tell you that it is beginning to evaluate the triangle-bugged function:

---------- Buffer: *Backtrace* ----------
Debugger entered--entering a function:
* triangle-bugged(5)
  eval((triangle-bugged 5))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

In the *Backtrace* buffer, type d. Emacs will evaluate the first expression in triangle-bugged; the buffer will look like this:

---------- Buffer: *Backtrace* ----------
Debugger entered--beginning evaluation of function call form:
* (let ((total 0)) (while (> number 0) (setq total ...)
        (setq number ...)) total)
* triangle-bugged(5)
  eval((triangle-bugged 5))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

Now, type d again, eight times, slowly. Each time you type d, Emacs will evaluate another expression in the function definition.

Eventually, the buffer will look like this:

---------- Buffer: *Backtrace* ----------
Debugger entered--beginning evaluation of function call form:
* (setq number (1= number))
* (while (> number 0) (setq total (+ total number))
        (setq number (1= number)))
* (let ((total 0)) (while (> number 0) (setq total ...)
        (setq number ...)) total)
* triangle-bugged(5)
  eval((triangle-bugged 5))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

Finally, after you type d two more times, Emacs will reach the error, and the top two lines of the *Backtrace* buffer will look like this:

---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function 1=)
* (1= number)
...
---------- Buffer: *Backtrace* ----------

By typing d, you were able to step through the function.

You can quit a *Backtrace* buffer by typing q in it; this quits the trace, but does not cancel debug-on-entry.

To cancel the effect of debug-on-entry, call cancel-debug-on-entry and the name of the function, like this:

M-x cancel-debug-on-entry RET triangle-bugged RET

(If you are reading this in Info, cancel debug-on-entry now.)