@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Debugging
@chapter Debugging Lisp Programs
@item
You can use the ERT package to write regression tests for the program.
-@xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}.
+@xref{Top,the ERT manual,, ert, ERT: Emacs Lisp Regression Testing}.
+
+@item
+You can profile the program to get hints about how to make it more efficient.
@end itemize
Other useful tools for debugging input and output problems are the
type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger
to step through a primitive function.
+@c FIXME: Add @findex for the following commands? --xfq
Here is a list of Debugger mode commands:
@table @kbd
@code{debug-on-entry}. @strong{Warning:} if you redefine such a
function and thus cancel the effect of @code{debug-on-entry}, it may
erroneously show up in this list.
+
+@item v
+Display local variables (@pxref{Local Variables}) of the current stack
+frame. Press @kbd{e} again to hide them.
@end table
@node Invoking the Debugger
If your program is working correctly, but you want to make it run more
quickly or efficiently, the first thing to do is @dfn{profile} your
-code that you know how it is using resources. If you find that one
+code so that you know how it is using resources. If you find that one
particular function is responsible for a significant portion of the
-runtime, you can start by looking for ways to optimize that piece.
+runtime, you can start looking for ways to optimize that piece.
Emacs has built-in support for this. To begin profiling, type
@kbd{M-x profiler-start}. You can choose to profile by processor
When you have finished profiling, type @kbd{M-x profiler-stop} (there
is a small overhead associated with profiling).
-@c FIXME
-@c Basic apperance of the report buffer:
+The profiler report buffer shows, on each line, a function that was
+called, followed by how much resource (processor or memory) it used in
+absolute and percentage times since profiling started. If a given
+line has a @samp{+} symbol at the left-hand side, you can expand that
+line by typing @key{RET}, in order to see the function(s) called by
+the higher-level function. Pressing @key{RET} again will collapse
+back to the original state.
-@c The following commands are available in the report buffer:
+Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function.
+Press @kbd{d} to view a function's documentation.
+You can save a profile to a file using @kbd{C-x C-w}.
+You can compare two profiles using @kbd{=}.
+
+@c FIXME reversed calltree?
@cindex @file{elp.el}
@cindex timing programs
You can check the speed of individual Emacs Lisp forms using the
@file{benchmark} library. See the functions @code{benchmark-run} and
@code{benchmark-run-compiled} in @file{benchmark.el}.
+
+@c Not worth putting in the printed manual.
+@ifnottex
+@cindex --enable-profiling option of configure
+To profile Emacs at the level of its C code, you can build it using the
+@option{--enable-profiling} option of @command{configure}. When Emacs
+exits, it generates a file @file{gmon.out} that you can examine using
+the @command{gprof} utility. This feature is mainly useful for
+debugging Emacs. It actually stops the Lisp-level @kbd{M-x
+profiler-@dots{}} commands described above from working.
+@end ifnottex