Small doc updates re initial-buffer-choice

[bpt/emacs.git] / doc / lispref / debugging.texi

diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 2226db9..a9d0c1c 100644 (file)
--- 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 -*-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
 @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.
 
 @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
 @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.
 * 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
 @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.
 
 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
 @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
 
 @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
   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).
 
 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 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 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
 
   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.
 
 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
   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
 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
 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.
 @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
 @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.
   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