@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000 Free Software Foundation, Inc.
+@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Building, Abbrevs, Programs, Top
+@node Building, Maintaining, Programs, Top
@chapter Compiling and Testing Programs
@cindex building programs
@cindex program building
@table @kbd
@item M-x compile
-Run a compiler asynchronously under Emacs, with error messages to
-@samp{*compilation*} buffer.
+Run a compiler asynchronously under Emacs, with error messages going to
+the @samp{*compilation*} buffer.
+@item M-x recompile
+Invoke a compiler with the same command as in the last invocation of
+@kbd{M-x compile}.
@item M-x grep
Run @code{grep} asynchronously under Emacs, with matching lines
listed in the buffer named @samp{*grep*}.
compile} asks for confirmation before actually killing a compilation
that is running.
+@findex recompile
+ To rerun the last compilation with the same command, type @kbd{M-x
+recompile}. This automatically reuses the compilation command from the
+last invocation of @kbd{M-x compile}.
+
@node Grep Searching
@section Searching with Grep under Emacs
@kindex C-x `
@findex next-error
You can visit the source for any particular error message by moving
-point in @samp{*compilation*} to that error message and typing @key{RET}
-(@code{compile-goto-error}). Or click @kbd{Mouse-2} on the error message;
-you need not switch to the @samp{*compilation*} buffer first.
+point in the @samp{*compilation*} buffer to that error message and
+typing @key{RET} (@code{compile-goto-error}). Alternatively, you can
+click @kbd{Mouse-2} on the error message; you need not switch to the
+@samp{*compilation*} buffer first.
To parse the compiler error messages sequentially, type @kbd{C-x `}
(@code{next-error}). The character following the @kbd{C-x} is the
@kbd{C-u C-x `} starts scanning from the beginning of the compilation
buffer. This is one way to process the same set of errors again.
+@vindex compilation-error-regexp-alist
+@vindex grep-regexp-alist
+ To parse messages from the compiler, Compilation mode uses the
+variable @code{compilation-error-regexp-alist} which lists various
+formats of error messages and tells Emacs how to extract the source file
+and the line number from the text of a message. If your compiler isn't
+supported, you can tailor Compilation mode to it by adding elements to
+that list. A similar variable @code{grep-regexp-alist} tells Emacs how
+to parse output of a @code{grep} command.
+
Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
scroll by screenfuls, and @kbd{M-n} and @kbd{M-p} to move to the next or
previous error message. You can also use @kbd{M-@{} and @kbd{M-@}} to
GDB, which is free software, but you can also run DBX, SDB or XDB if you
have them. GUD can also serve as an interface to the Perl's debugging
mode, the Python debugger PDB, and to JDB, the Java Debugger.
+@xref{Debugger,, The Lisp Debugger, elisp, the Emacs Lisp Reference Manual},
+for information on debugging Emacs Lisp programs.
@menu
* Starting GUD:: How to start a debugger subprocess.
@table @kbd
@item M-x gdb @key{RET} @var{file} @key{RET}
@findex gdb
-Run GDB as a subprocess of Emacs. This command creates a buffer for
-input and output to GDB, and switches to it. If a GDB buffer already
-exists, it just switches to that buffer.
+Run GDB as a subprocess of Emacs. This command creates a buffer
+for input and output to GDB, and switches to it. If a GDB buffer
+already exists, it just switches to that buffer.
@item M-x dbx @key{RET} @var{file} @key{RET}
@findex dbx
@node Debugger Operation
@subsection Debugger Operation
+@cindex fringes, and current execution line in GUD
When you run a debugger with GUD, the debugger uses an Emacs buffer
for its ordinary input and output. This is called the GUD buffer. The
debugger displays the source files of the program by visiting them in
Emacs buffers. An arrow (@samp{=>}) in one of these buffers indicates
-the current execution line.@footnote{Under a window system the arrow is
-displayed in the marginal area of the Emacs window.} Moving point in
-this buffer does not move the arrow.
+the current execution line.@footnote{Under a window system, the arrow
+appears in the left fringe of the Emacs window.} Moving point in this
+buffer does not move the arrow.
You can start editing these source files at any time in the buffers
-that were made to display them. The arrow is not part of the file's
+that display them. The arrow is not part of the file's
text; it appears only on the screen. If you do modify a source file,
keep in mind that inserting or deleting lines will throw off the arrow's
positioning; GUD has no way of figuring out which line corresponded
commands are available both in the GUD buffer and globally, but with
different key bindings.
- The breakpoint commands are usually used in source file buffers,
-because that is the way to specify where to set or clear the breakpoint.
-Here's the global command to set a breakpoint:
+ The breakpoint commands are normally used in source file buffers,
+because that is the easiest way to specify where to set or clear the
+breakpoint. Here's the global command to set a breakpoint:
@table @kbd
@item C-x @key{SPC}
@findex gud-finish
Run the program until the selected stack frame returns (or until it
stops for some other reason).
+
+@item C-c C-j
+@kindex C-c C-j @r{(GUD)}
+@itemx C-x C-a C-j
+@findex gud-jump
+Only useful in a source buffer, (@code{gud-jump}) relocates the next
+instruction to the current line at point in a source buffer. If the
+new execution line is in a different function from the previously one,
+you will be prompted for confirmation since the results may be
+bizarre. See the GDB manual entry regarding @cod{jump} for details.
@end table
These commands interpret a numeric argument as a repeat count, when
if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
-@code{jdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
+@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
use these hooks to define custom key bindings for the debugger
interaction buffer. @xref{Hooks}.
This defines a command named @var{function} which sends
@var{cmdstring} to the debugger process, and gives it the documentation
-string @var{docstring}. You can use the command thus defined in any
+string @var{docstring}. You can then use the command @var{function} in any
buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds
the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
@kbd{C-x C-a @var{binding}} generally.
compiled file, since it will load and run faster.
If @code{load-library} finds that @file{@var{lib}.el} is newer than
-@file{@var{lib}.elc} file, it prints a warning, because it's likely that
+@file{@var{lib}.elc} file, it issues a warning, because it's likely that
somebody made changes to the @file{.el} file and forgot to recompile
it.
region as one or more Lisp expressions, evaluating them one by one.
@kbd{M-x eval-current-buffer} is similar but evaluates the entire
buffer. This is a reasonable way to install the contents of a file of
-Lisp code that you are just ready to test. Later, as you find bugs and
+Lisp code that you are ready to test. Later, as you find bugs and
change individual functions, use @kbd{C-M-x} on each function that you
change. This keeps the Lisp world in step with the source file.