@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Read and Print, Advising Functions, Top
* Debugger:: How the Emacs Lisp debugger is implemented.
* 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.
* Compilation Errors:: How to find errors that show up in byte compilation.
@end menu
@example
(add-hook 'after-init-hook
- '(lambda () (setq debug-on-error t)))
+ (lambda () (setq debug-on-error t)))
@end example
@node Infinite Loops
up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
@code{debug-on-entry} always returns @var{function-name}.
-@strong{Note:} if you redefine a function after using
-@code{debug-on-entry} on it, the code to enter the debugger is discarded
-by the redefinition. In effect, redefining the function cancels
-the break-on-entry feature for that function.
+@strong{Warning:} if you redefine a function after using
+@code{debug-on-entry} on it, the code to enter the debugger is
+discarded by the redefinition. In effect, redefining the function
+cancels the break-on-entry feature for that function.
@example
@group
considered the @dfn{current frame}. Some of the debugger commands
operate on the current frame.
+ If a function name is underlined, that means the debugger knows
+where its source code is located. You can click @kbd{Mouse-2} on that
+name, or move to it and type @key{RET}, to visit the source code.
+
The debugger itself must be run byte-compiled, since it makes
assumptions about how many stack frames are used for the debugger
itself. These assumptions are false if the debugger is running
@subsection Debugger Commands
@cindex debugger command list
- Inside the debugger (in Debugger mode), these special commands are
-available in addition to the usual cursor motion commands. (Keep in
-mind that all the usual facilities of Emacs, such as switching windows
-or buffers, are still available.)
-
- The most important use of debugger commands is for stepping through
-code, so that you can see how control flows. The debugger can step
-through the control structures of an interpreted function, but cannot do
-so in a byte-compiled function. If you would like to step through a
-byte-compiled function, replace it with an interpreted definition of the
-same function. (To do this, visit the source for the function and type
-@kbd{C-M-x} on its definition.)
+ The debugger buffer (in Debugger mode) provides special commands in
+addition to the usual Emacs commands. The most important use of
+debugger commands is for stepping through code, so that you can see
+how control flows. The debugger can step through the control
+structures of an interpreted function, but cannot do so in a
+byte-compiled function. If you would like to step through a
+byte-compiled function, replace it with an interpreted definition of
+the same function. (To do this, visit the source for the function and
+type @kbd{C-M-x} on its definition.)
Here is a list of Debugger mode commands:
(1+ var)
(list 'testing (backtrace))))))))
- @result{} nil
+ @result{} (testing nil)
@end group
@group
and you have put back those parentheses, @kbd{C-M-q} should not change
anything.
+@node Test Coverage
+@section Test Coverage
+@cindex coverage testing
+
+@findex testcover-start
+@findex testcover-mark-all
+@findex testcover-next-mark
+ You can do coverage testing for a file of Lisp code by first using
+the command @kbd{M-x testcover-start @key{RET} @var{file} @key{RET}}
+to instrument it. Then test your code by calling it one or more
+times. Then use the command @kbd{M-x testcover-mark-all} to display
+``splotches'' on the code to show where coverage is insufficient. The
+command @kbd{M-x testcover-next-mark} will move point forward to the
+next spot that has a splotch.
+
+ Normally, a red splotch indicates the form was never completely
+evaluated; a brown splotch means it always evaluated to the same value
+(meaning there has been little testing of what is done with the
+result). However, the red splotch is skipped for forms that can't
+possibly complete their evaluation, such as @code{error}. The brown
+splotch is skipped for forms that are expected to always evaluate to
+the same value, such as @code{(setq x 14)}.
+
+ For difficult cases, you can add do-nothing macros to your code to
+give advice to the test coverage tool.
+
+@defmac 1value form
+Evaluate @var{form} and return its value, but inform coverage testing
+that @var{form}'s value should always be the same.
+@end defmac
+
+@defmac noreturn form
+Evaluate @var{form}, informing coverage testing that @var{form} should
+never return. If it ever does return, you get a run-time error.
+@end defmac
+
@node Compilation Errors
@section Debugging Problems in Compilation
successfully, then point is located at the end of the form. In this
case, this technique can't localize the error precisely, but can still
show you which function to check.
+
+@ignore
+ arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7
+@end ignore