@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
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
+* Profiling:: Measuring the resources that your code uses.
@end menu
@node Debugger
any of the regular expressions, then that error does not enter the
debugger.
-The normal value of this variable lists several errors that happen
-often during editing but rarely result from bugs in Lisp programs.
-However, ``rarely'' is not ``never''; if your program fails with an
-error that matches this list, you may try changing this list to debug
-the error. The easiest way is usually to set
-@code{debug-ignored-errors} to @code{nil}.
+The normal value of this variable includes @code{user-error}, as well
+as several errors that happen often during editing but rarely result
+from bugs in Lisp programs. However, ``rarely'' is not ``never''; if
+your program fails with an error that matches this list, you may try
+changing this list to debug the error. The easiest way is usually to
+set @code{debug-ignored-errors} to @code{nil}.
@end defopt
@defopt eval-expression-debug-on-error
@code{inhibit-quit} is set and Emacs is not otherwise responding.
@end defopt
+@cindex message, finding what causes a particular message
+@defvar debug-on-message
+If you set @code{debug-on-message} to a regular expression,
+Emacs will enter the debugger if it displays a matching message in the
+echo area. For example, this can be useful when trying to find the
+cause of a particular message.
+@end defvar
+
To debug an error that happens during loading of the init
file, use the option @samp{--debug-init}. This binds
@code{debug-on-error} to @code{t} while loading the init file, and
as the error message and associated data, if it was invoked due to an
error).
+@vindex debugger-bury-or-kill
The backtrace buffer is read-only and uses a special major mode,
Debugger mode, in which letters are defined as debugger commands. The
usual Emacs editing commands are available; thus, you can switch windows
the debugger is a recursive editing level (@pxref{Recursive Editing})
and it is wise to go back to the backtrace buffer and exit the debugger
(with the @kbd{q} command) when you are finished with it. Exiting
-the debugger gets out of the recursive edit and kills the backtrace
-buffer.
+the debugger gets out of the recursive edit and buries the backtrace
+buffer. (You can customize what the @kbd{q} command does with the
+backtrace buffer by setting the variable @code{debugger-bury-or-kill}.
+For example, set it to @code{kill} if you prefer to kill the buffer
+rather than bury it. Consult the variable's documentation for more
+possibilities.)
When the debugger has been entered, the @code{debug-on-error}
variable is temporarily set according to
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
are set up to do so by @code{debug-on-entry}.
@item e
-Read a Lisp expression in the minibuffer, evaluate it, and print the
+Read a Lisp expression in the minibuffer, evaluate it (with the
+relevant lexical environment, if applicable), and print the
value in the echo area. The debugger alters certain important
variables, and the current buffer, as part of its operation; @kbd{e}
temporarily restores their values from outside the debugger, so you can
@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
+Toggle the display of local variables of the current stack frame.
@end table
@node Invoking the Debugger
Edebug also has a coverage testing feature (@pxref{Coverage
Testing}). These features partly duplicate each other, and it would
be cleaner to combine them.
+
+
+@node Profiling
+@section Profiling
+@cindex profiling
+@cindex measuring resource usage
+@cindex memory usage
+
+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 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 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
+usage, memory usage, or both. After doing some work, type
+@kbd{M-x profiler-report} to display a summary buffer for each
+resource that you chose to profile. The names of the report buffers
+include the times at which the reports were generated, so you can
+generate another report later on without erasing previous results.
+When you have finished profiling, type @kbd{M-x profiler-stop} (there
+is a small overhead associated with profiling).
+
+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.
+
+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
+The @file{elp} library offers an alternative approach. See the file
+@file{elp.el} for instructions.
+
+@cindex @file{benchmark.el}
+@cindex benchmarking
+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
HCoop / bpt / emacs.git / blobdiff