⟦28e01ef7a⟧

TextFile

@setfilename ../info/debugging
@node Debugging, Streams, Byte Compilation, Top
@chapter Debugging

@cindex debugging
  The Lisp Debugger provides you with the ability to suspend evaluation
of a form and do a number of things that help in debugging Lisp code.
While evaluation is suspended (a state that is commonly known as a
@dfn{break}), you may examine the runtime stack, examine the values of
local or global variables and, optionally, change those values.  Since a
break is a recursive edit while in the middle of a function call, it is
possible to do anything, including calling the debugger again.
(@xref{Recursive Editing}, and also, (@pxref{Recursive Edit, , Recursive
Editing Levels, emacs, The GNU Emacs Manual}.)

  The actions of the debugger are well documented in the GNU Emacs
Manual; and they will not be repeated here.  The rest of this section
assumes that you are familiar with that section in the manual.
(@xref{Lisp Debug, , The Emacs-Lisp Debugger, emacs, The GNU Emacs Manual}.)

@cindex quit signal
@cindex error debugging

  The operation of the debugger is quite simple: it performs one basic
operation, which is to enter a break.  The debugger enters such a break
when one or other of the following conditions occur:

@itemize @bullet
@item
when a certain function specified by you is entered or exited;

@item
when a error occurs; or

@item
when a @code{quit} signal is not handled by user code.
@end itemize

@noindent
After entering the break, the debugger displays information about the
status of the stack in a @samp{*Backtrace*} buffer, and waits for you to
type a command.  

  When you cause Emacs to continue evaluation, at a break for function
entry or exit, the debugger will arrange for the called function to
continue to a normal conclusion and return the same value that it would
return when evaluated without the debugger.  It will not produce an
abnormal termination unless you specifically request it.

  Another useful debugging tool is a dribble file.  When a dribble file
is open, Emacs copies all keyboard input characters to that file.  You
can examine it to find out what you did.  @xref{Terminal Input}; also
see the @code{open-termscript} function in @xref{Terminal Output}.

@menu
* Debug Functions::      
@end menu

@node Debug Functions,  , Debugging, Debugging
@section Debug Functions

@defun debug &rest debugger-args
  This function enters the debugger.  It switches buffers to a buffer
named @code{*Backtrace*} (or @code{*Backtrace*<2>} if it is the second
recursive edit, etc.) and prints out information about the stack.  Emacs
then enters a recursive edit, leaving that buffer showing in the
selected window, which is in Debugger Mode.

  One of the commands defined in Debugger mode is @code{continue}, which
causes Emacs to exit the recursive edit, switch back to the previous
buffer, and continue evaluation normally.

  If the first of the @var{debugger-args} passed to @code{debug} is
@code{nil} (or if it is a non-@code{nil} value which is not one of the
following special values), then the rest of the arguments to
@code{debug} are printed at the top of the @samp{*Backtrace*} buffer.  This
mechanism is used to display a message to the user.

  However, if the first argument passed to @code{debug} is one of the
following special values, then it has special significance.  Normally,
these values are passed to @code{debug} only by the internals of Emacs
and the debugger, and not by programmers calling @code{debug}.

  The special values are:

@table @code
@item lambda
@cindex lambda in debug
  When @code{lambda} is passed as the first of the @var{debugger-args},
the debugger displays @samp{Entering:} as a line of text at the top of
the buffer.  This is used to indicate that a function that is being
debugged is being entered.

@item debug
  When @code{debug} is passed as the first of the @var{debugger-args},
the debugger displays @samp{Entering:} as a line of text at the top of
the buffer, just as when @code{lambda} is passed as the first of the
@var{debugger-args}.  This is used to indicate that a function that is
being debugged is being entered.

  In addition, use of @code{debug} causes the debugger to mark the
function that called @code{debug} so that it will also break on exit.

@item error
@cindex error in debug
  When @code{error} is passed as the argument, the debugger indicates
that it is being entered because an error or @code{quit} was
signaled and not handled.  If an error was signaled, presumably the
variable @code{debug-on-error} is non-@code{nil}.  If @code{quit} was
signaled, then presumably the variable @code{debug-on-quit} is
non-@code{nil}.

  When entering, the debugger displays @samp{Signaling:} followed by the
error signaled and any arguments to @code{signal}.

  For example,

@example
(let ((debug-on-error t))
     (/ 1 0))

---------- Buffer: *Backtrace* ----------
Signaling: (arith-error)
  /(1 0)
...
@end example

@item t
  When @code{t} is passed as the argument, the debuggerwill indicate
that Emacs is beginning the evaluation of a function call.  The debugger
displays @samp{Beginning evaluation of function call form:} as the top
line in the buffer.

@item exit
  When @code{exit} is passed as the argument, it means that a a function
that was being debugged is returning a value.  The debugger displays
@samp{Return value:} on the top line of the buffer, followed by the
returned value.@refill

@item nil
  Use @code{nil} as the first of the @var{debugger-args} when you want
to enter the debugger directly.  The rest of the @var{debugger-args} are
printed on the top line of the buffer.  You can use this feature to
display messages---for example, to remind yourself the conditions under
which @code{debug} is called.
@end table
@end defun

@defvar debugger
  The value of this variable is the function to call in order to invoke
the debugger.  Its value must be a function (or, more typically, the name of
a function) of any number of arguments.  Presumably this function will
enter some kind of debugger.

  The first argument that Lisp hands to the function indicates how it
was called.  The convention for arguments is detailed in the description
of @code{debug}.
@end defvar

@deffn Command backtrace
@cindex runtime stack
@cindex call stack
  This function prints a trace of Lisp function calls currently active.
This is the function used by @code{debug} to fill up the @code{*Backtrace*}
buffer.  It is written in C, as it must have access to the stack
in order to determine which function calls are active.
The return value is always @code{nil}.

  In the following example, @code{backtrace} is called explicitly in a
Lisp expression.  When the expression is evaluated, the backtrace is
printed to @code{standard-output}: in this case, to the buffer
@samp{backtrace-output}.  Each line of the backtrace represents one
function call.  If the arguments of the function call are all known,
they are displayed; if they are being computed, that fact is displayed.
The arguments of special forms are elided.

@example
(with-output-to-temp-buffer "backtrace-output"
  (let ((var 1))
    (save-excursion
      (setq var (eval '(progn
                         (1+ var)
                         (list 'testing (backtrace))
                         ))))))

     @result{} nil
----------- Buffer: backtrace-output ------------
  backtrace()
  (list ...computing arguments...)
  (progn ...)
  eval((progn (1+ var) (list (quote testing) (backtrace))))
  (setq ...)
  (save-excursion ...)
  (let ...)
  (with-output-to-temp-buffer ...)
  eval-region(1973 2142 #<buffer *scratch*>)
  byte-code("...  for eval-print-last-sexp ...")
  eval-print-last-sexp(nil)
* call-interactively(eval-print-last-sexp)
----------- Buffer: backtrace-output ------------
@end example
@end deffn

@deffn Command debug-on-entry function-name
@cindex function call debugging
  This function requests @var{function-name} to invoke the debugger each time
it is called.  It works by inserting the form @code{(debug 'debug)} into
the function definition as the first form.

  Any function defined as Lisp code may be debugged, regardless of
whether it is interpreted code or compiled code.  Even functions which
are commands may be debugged.  They will enter the debugger when called
inside of a function, or when called interactively.  Primitive functions
(i.e., those written in C) may not be debugged.

  When @code{debug-on-entry} is called interactively, Emacs prompts you
for @var{function-name} in the minibuffer.

  @code{debug-on-entry} returns @var{function-name}.  If
@code{debug-on-entry} is called more than once on the same function, the
second call does nothing.

@example
(defun fact (n)
  (if (zerop n) 1
      (* n (fact (1- n)))))
     @result{} fact
(debug-on-entry 'fact)
     @result{} fact
(fact 3)
     @result{} 6

---------- Buffer: *Backtrace* ----------
Entering:
* fact(3)
  eval-region(4870 4878 t)
  byte-code("...")
  eval-last-sexp(nil)
  (let ...)
  eval-insert-last-sexp(nil)
* call-interactively(eval-insert-last-sexp)
---------- Buffer: *Backtrace* ----------

(symbol-function 'fact)
     @result{} (lambda (n)
     (debug (quote debug))
     (if (zerop n) 1 (* n (fact (1- n)))))
@end example
@end deffn

@deffn Command cancel-debug-on-entry function-name
  This function undoes the effect of @code{debug-on-entry} on
@var{function-name}.

  When @code{cancel-debug-on-entry} is called interactively, Emacs
prompts you for @var{function-name} in the minibuffer.

  If @code{cancel-debug-on-entry} is called more than once on the same
function, the second call does nothing.  @code{cancel-debug-on-entry}
returns @var{function-name}.
@end deffn

@defopt debug-on-error
@cindex error debugging
  This variable determines whether the debugger is called when a error
is signaled and not handled.  If the @code{debug-on-error} variable is
non-@code{nil}, then the debugger is called on every such error.  (Note
that @code{quit} is not an error.).  If the @code{debug-on-error}
variable is @code{nil}, then the debugger is not called.  
@end defopt

@defopt debug-on-quit
@vindex quit
@cindex quit signal
  This variable determines whether the debugger is called when
@code{quit} is signaled and not handled.  If the @code{debug-on-quit}
variable it is non-@code{nil} then the debugger is called on every
@code{quit} signal.  If the @code{debug-on-quit} variable is @code{nil},
then the debugger is not called.  (@code{quit} is the signal that
@kbd{C-g} causes.)  
@end defopt

@defopt stack-trace-on-error
@cindex stack trace
  This obsolete variable determines whether Lisp shall automatically display a
backtrace buffer after every error that is not handled.  A quit signal
counts as an error for this variable.  If it is non-@code{nil} then a
backtrace is shown in a pop-up buffer named @code{*Backtrace*} on every
error.  If it is @code{nil}, then a backtrace is not shown.

  When a backtrace is shown, that buffer is not selected.  If either
@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
a backtrace is shown in one buffer, and the debugger is popped up in
another buffer with its own backtrace.
@end defopt

@defvar debug-on-next-call
@cindex eval, related to debugging
@cindex apply, related to debugging
@cindex funcall, related to debugging
  This variable determines whether the debugger is called before the
next @code{eval}, @code{apply} or @code{funcall}.  It is automatically
reset to @code{nil} when the debugger is entered.  

The @kbd{d} command in the debuffer works by setting this variable.

@end defvar

@defun backtrace-debug level flag
  This function sets the debug-on-exit flag of the eval frame
@var{level} levels down to @var{flag}, causing the debugger to be entered
when that frame exits, assuming @var{flag} is non-@code{nil}.

  The @code{debug-on-exit} flag is an entry in the stack frame of a
function call.  This flag is examined on every exit from a function.

  Normally this function is only called by the debugger.
@end defun

@ignore

@node Debugger Mode Commands,  , Debug Functions, Debugging
@c section Debugger Mode Commands

@cindex Debugger mode
  The commands defined in Debugger mode are:

@table @key
@item b
debugger-frame
@item c
debugger-continue
@item r
debugger-return-value
@item u
debugger-frame-clear
@item d
debugger-step-through
@item h
describe-mode
@item q
top-level
@item e
debugger-eval-expression
@item SPC
next-line
@end table

@deffn Command debugger-frame
  This function marks the stack frame for the function entry which the
point is on.  Each stack frame corresponds to a function call and is
represented as one line in the backtrace.  When the function in question
returns a value, the debugger will be called.
@end deffn

@deffn Command debugger-continue
  This function exits the debugger and continues the computation from
the point which it was broken at.
@end deffn

@deffn Command debugger-return-value
  This function exits the debugger, returning a value which is prompted
for in the Minibuffer.  This is only useful when the value returned from
the debugger will be used, such as in a debug on exit from a frame.
@end deffn

@deffn Command debugger-frame-clear
  This function unmarks the stack frame for the function entry which the
point is on.  When the function in question returns a value, the
debugger will not be called.
@end deffn

@deffn Command debugger-step-through
  This function exits the debugger, but it sets
@code{debug-on-next-call} to @code{t}, so that the very next call to
@code{eval}, @code{apply}, or @code{funcall} will break.  As soon as the
debugger is re-entered, @code{debug-on-next-call} will be reset to
@code{nil}.

Repeatedly calling this function has the effect of stepping through
subexpressions of the current expression.
@end deffn

@deffn Command debugger-eval-expression
  This function reads an S-Expression in the Minibuffer and evaluates
it, printing the result in the Echo Area.  It is little more than a
call to @code{eval-expression}.
@end deffn

@end ignore
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦28e01ef7a⟧ TextFile

Derivation

TextFile
