X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/36a305a723c63fd345be65c536c52fe9765c14be..3f63a9f7de4f252a0309c2143e6d916d734ffe22:/doc/lispref/debugging.texi diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 2226db942d..a9d0c1c4ed 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -1,6 +1,7 @@ @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 @@ -31,7 +32,10 @@ program. @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 @@ -43,6 +47,7 @@ function (@pxref{Terminal Output}). * 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 @@ -117,12 +122,12 @@ has any of those condition symbols, or if the error message matches 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 @@ -163,6 +168,14 @@ supported values correspond to the signals @code{SIGUSR1} and @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 @@ -314,6 +327,7 @@ is a message describing the reason that the debugger was invoked (such 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 @@ -322,8 +336,12 @@ switch buffers, visit files, or do any other sort of editing. However, 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 @@ -370,6 +388,7 @@ the same function. (To do this, visit the source for the function and 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 @@ -406,7 +425,8 @@ Flag the current frame like @kbd{b}. Then continue execution like 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 @@ -444,6 +464,9 @@ This is a list of functions that are set to break on entry by means of @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 @@ -796,3 +819,63 @@ never return. If it ever does return, you get a run-time error. 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