@menu
* Compilation:: Compiling programs in languages other
than Lisp (C, Pascal, etc.).
-* Grep Searching:: Running grep as if it were a compiler.
* Compilation Mode:: The mode for visiting compiler errors.
* Compilation Shell:: Customizing your shell properly
for use in the compilation buffer.
+* Grep Searching:: Searching with grep.
+* Flymake:: Finding syntax errors on the fly.
* Debuggers:: Running symbolic debuggers for non-Lisp programs.
* Executing Lisp:: Various modes for editing Lisp programs,
with different facilities for running
Variables}).
Starting a compilation displays the buffer @samp{*compilation*} in
-another window but does not select it. The buffer's mode line tells you
-whether compilation is finished, with the word @samp{run} or @samp{exit}
-inside the parentheses. You do not have to keep this buffer visible;
-compilation continues in any case. While a compilation is going on, the
-string @samp{Compiling} appears in the mode lines of all windows. When
-this string disappears, the compilation is finished.
+another window but does not select it. The buffer's mode line tells
+you whether compilation is finished, with the word @samp{run},
+@samp{signal} or @samp{exit} inside the parentheses. You do not have
+to keep this buffer visible; compilation continues in any case. While
+a compilation is going on, the string @samp{Compiling} appears in the
+mode lines of all windows. When this string disappears, the
+compilation is finished.
If you want to watch the compilation transcript as it appears, switch
to the @samp{*compilation*} buffer and move point to the end of the
@findex kill-compilation
When the compiler process terminates, for whatever reason, the mode
-line of the @samp{*compilation*} buffer changes to say @samp{signal}
-instead of @samp{run}. Starting a new compilation also kills any
-running compilation, as only one can exist at any time. However,
-@kbd{M-x compile} asks for confirmation before actually killing a
-compilation that is running. You can also kill the compilation
-process with @kbd{M-x kill-compilation}.
+line of the @samp{*compilation*} buffer changes to say @samp{exit}
+(followed by the exit code, @samp{[0]} for a normal exit), or
+@samp{signal} (if a signal terminated the process), instead of
+@samp{run}. Starting a new compilation also kills any running
+compilation, as only one can exist at any time. However, @kbd{M-x
+compile} asks for confirmation before actually killing a compilation
+that is running. You can also kill the compilation process with
+@kbd{M-x kill-compilation}.
@findex recompile
To rerun the last compilation with the same command, type @kbd{M-x
the form @code{"@var{envvarname}=@var{value}"}. These environment
variable settings override the usual ones.
-@node Grep Searching
-@section Searching with Grep under Emacs
-
-@findex grep
- Just as you can run a compiler from Emacs and then visit the lines
-where there were compilation errors, you can also run @code{grep} and
-then visit the lines on which matches were found. This works by
-treating the matches reported by @code{grep} as if they were ``errors.''
-
- To do this, type @kbd{M-x grep}, then enter a command line that
-specifies how to run @code{grep}. Use the same arguments you would give
-@code{grep} when running it normally: a @code{grep}-style regexp
-(usually in single-quotes to quote the shell's special characters)
-followed by file names, which may use wildcards. The output from
-@code{grep} goes in the @samp{*grep*} buffer. You can find the
-corresponding lines in the original files using @kbd{C-x `} and
-@key{RET}, as with compilation errors.
-
- If you specify a prefix argument for @kbd{M-x grep}, it figures out
-the tag (@pxref{Tags}) around point, and puts that into the default
-@code{grep} command.
-
-@findex grep-find
-@findex find-grep
- The command @kbd{M-x grep-find} (also available as @kbd{M-x
-find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
-initial default for the command---one that runs both @code{find} and
-@code{grep}, so as to search every file in a directory tree. See also
-the @code{find-grep-dired} command, in @ref{Dired and Find}.
-
@node Compilation Mode
@section Compilation Mode
follow output as it comes in.
@table @kbd
-@item C-x `
+@item M-g M-n
+@itemx M-g n
+@itemx C-x `
Visit the locus of the next compiler error message or @code{grep} match.
+@item M-g M-p
+@itemx M-g p
+Visit the locus of the previous compiler error message or @code{grep} match.
@item @key{RET}
Visit the locus of the error message that point is on.
This command is used in the compilation buffer.
@item Mouse-2
Visit the locus of the error message that you click on.
+@item M-n
+Find and highlight the locus of the next error message, without
+selecting the source buffer.
+@item M-p
+Find and highlight the locus of the previous error message, without
+selecting the source buffer.
+@item M-@}
+Move point to the next error for a different file than the current
+one.
+@item M-@{
+Move point to the previous error for a different file than the current
+one.
+@item C-c C-f
+Toggle Next Error Follow minor mode, which makes cursor motion in the
+compilation buffer produce automatic source display.
@end table
+@kindex M-g M-n
+@kindex M-g n
@kindex C-x `
@findex next-error
You can visit the source for any particular error message by moving
click @kbd{Mouse-2} on the error message; you need not switch to the
@samp{*compilation*} buffer first.
+@vindex next-error-highlight
To parse the compiler error messages sequentially, type @kbd{C-x `}
(@code{next-error}). The character following the @kbd{C-x} is the
backquote or ``grave accent,'' not the single-quote. This command is
-available in all buffers, not just in @samp{*compilation*}; it displays
-the next error message at the top of one window and source location of
-the error in another window.
+available in all buffers, not just in @samp{*compilation*}; it
+displays the next error message at the top of one window and source
+location of the error in another window. It also momentarily
+highlights the relevant source line. You can change the behavior of
+this highlighting with the variable @code{next-error-highlight}.
The first time @kbd{C-x `} is used after the start of a compilation,
it moves to the first error's location. Subsequent uses of @kbd{C-x `}
that list. A similar variable @code{grep-regexp-alist} tells Emacs how
to parse output of a @code{grep} command.
+@findex compilation-next-error
+@findex compilation-previous-error
+@findex compilation-next-file
+@findex compilation-previous-file
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
-move up or down to an error message for a different source file.
+scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error})
+and @kbd{M-p} (@code{compilation-previous-error}) to move to the next
+or previous error message. You can also use @kbd{M-@{}
+(@code{compilation-next-file} and @kbd{M-@}}
+(@code{compilation-previous-file}) to move up or down to an error
+message for a different source file.
+
+@cindex Next Error Follow mode
+@findex next-error-follow-minor-mode
+ You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
+this minor mode, ordinary cursor motion in the compilation buffer
+automatically updates the source buffer. For instance, moving the
+cursor to the next error message causes the location of that error to
+be displayed immediately.
The features of Compilation mode are also available in a minor mode
called Compilation Minor mode. This lets you parse error messages in
wait until the command finishes before you can do anything else in
Emacs. @xref{MS-DOS}.
+@node Grep Searching
+@section Searching with Grep under Emacs
+
+@findex grep
+ Just as you can run a compiler from Emacs and then visit the lines
+where there were compilation errors, you can also run @code{grep} and
+then visit the lines on which matches were found. This works by
+treating the matches reported by @code{grep} as if they were ``errors.''
+
+ To do this, type @kbd{M-x grep}, then enter a command line that
+specifies how to run @code{grep}. Use the same arguments you would give
+@code{grep} when running it normally: a @code{grep}-style regexp
+(usually in single-quotes to quote the shell's special characters)
+followed by file names, which may use wildcards. If you specify a
+prefix argument for @kbd{M-x grep}, it figures out the tag
+(@pxref{Tags}) around point, and puts that into the default
+@code{grep} command.
+
+ The output from @code{grep} goes in the @samp{*grep*} buffer. You
+can find the corresponding lines in the original files using @kbd{C-x
+`}, @key{RET}, and so forth, just like compilation errors.
+
+ Some grep programs accept a @samp{--color} option to output special
+markers around matches for the purpose of highlighting. You can make
+use of this feature by setting @code{grep-highlight-matches} to t.
+When displaying a match in the source buffer, the exact match will be
+highlighted, instead of the entire source line.
+
+@findex grep-find
+@findex find-grep
+ The command @kbd{M-x grep-find} (also available as @kbd{M-x
+find-grep}) is similar to @kbd{M-x grep}, but it supplies a different
+initial default for the command---one that runs both @code{find} and
+@code{grep}, so as to search every file in a directory tree. See also
+the @code{find-grep-dired} command, in @ref{Dired and Find}.
+
+@node Flymake
+@section Finding Syntax Errors On The Fly
+@cindex checking syntax
+
+ Flymake mode is a minor mode that performs on-the-fly syntax
+checking for many programming and markup languages, including C, C++,
+Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
+mode, which performs spell checking for ordinary human languages in a
+similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
+runs an appropriate syntax checking tool in the background, using a
+temporary copy of the buffer. It then parses the error and warning
+messages, and highlights the erroneous lines in the buffer. The
+syntax checking tool used depends on the language; for example, for
+C/C++ files this is usually the C compiler. Flymake can also use
+build tools such as @code{make} for checking complicated projects.
+
+ To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move
+to the errors spotted by Flymake mode with @kbd{M-x
+flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
+display any error messages associated with the current line, use
+@kbd{M-x flymake-display-err-menu-for-current-line}.
+
+ For more details about using Flymake, see @ref{Top, Flymake,
+Flymake, flymake, The Flymake Manual}.
+
@node Debuggers
@section Running Debuggers Under Emacs
@cindex debuggers
@cindex SDB
@cindex XDB
@cindex Perldb
+@cindex bashdb
@cindex JDB
@cindex PDB
@c Do you believe in GUD?
The GUD (Grand Unified Debugger) library provides an interface to
-various symbolic debuggers from within Emacs. We recommend the debugger
-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 Perl's debugging
-mode, the Python debugger PDB, and to JDB, the Java Debugger.
-@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference Manual},
-for information on debugging Emacs Lisp programs.
+various symbolic debuggers from within Emacs. We recommend the
+debugger 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 Perl's
+debugging mode, the Python debugger PDB, the bash debugger, and to
+JDB, the Java Debugger. @xref{Debugging,, 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.
* Debugger Operation:: Connection between the debugger and source buffers.
* Commands of GUD:: Key bindings for common commands.
* GUD Customization:: Defining your own commands for GUD.
-* GUD Tooltips:: Showing variable values by pointing with the mouse.
* GDB Graphical Interface:: An enhanced mode that uses GDB features to
implement a graphical debugging environment through
Emacs.
@table @kbd
@item M-x gdb @key{RET} @var{file} @key{RET}
@findex gdb
-Run GDB as a subprocess of Emacs. If the variable
-@code{gud-gdb-command-name} is ``gdb --annotate=3'' (the default
-value) then GDB starts as for @kbd{M-x gdba} below. If you want GDB
-to start as in Emacs 21.3 and earlier then edit the string in the
-minibuffer or set @code{gud-gdb-command-name} to ``gdb --fullname''.
-You need to do this if you want to run multiple debugging sessions
-within one Emacs session. In this case, the 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 gdba @key{RET} @var{file} @key{RET}
-Run GDB as a subprocess of Emacs, providing a graphical interface
-to GDB features through Emacs. @xref{GDB Graphical Interface}.
+Run GDB as a subprocess of Emacs. By default, this operates in
+graphical mode; @xref{GDB Graphical Interface}. Graphical mode
+does not support any other debuggers.
@item M-x dbx @key{RET} @var{file} @key{RET}
@findex dbx
requires a valid tags table to work}. If this happens, generate a valid
tags table in the working directory and try again.
+@item M-x bashdb @key{RET} @var{file} @key{RET}
+@findex bashdb
+Run the bash debugger to debug @var{file}, a shell script.
+
@item M-x perldb @key{RET} @var{file} @key{RET}
@findex perldb
Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
allowed. GUD assumes that the first argument not starting with a
@samp{-} is the executable file name.
- Emacs can only run one debugger process at a time.
-
@node Debugger Operation
@subsection Debugger Operation
commands for your debugger are available, and you can use the Shell mode
history commands to repeat them. @xref{Shell Mode}.
+@cindex tooltips with GUD
+@vindex tooltip-gud-modes
+@vindex tooltip-gud-tips-p
+ The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
+You activate this feature by setting the variable
+@code{tooltip-gud-tips-p} to @code{t}. Then you can display a
+variable's value in a tooltip simply by pointing at it with the mouse.
+In graphical mode, with a C program, you can also display the #define
+directive assiciated with an identifier when program is not executing.
+This operates in the GUD buffer and in source buffers with major modes
+in the list @code{tooltip-gud-modes}.
+
@node Commands of GUD
@subsection Commands of GUD
details.
@end table
-If you started GDB with the command @code{gdba}, you can click
-@kbd{Mouse-1} on a line of the source buffer, in the fringe or display
-margin, to set a breakpoint there. If a breakpoint already exists on
-that line, this action will remove it.
-(@code{gdb-mouse-toggle-breakpoint}).
-
These commands interpret a numeric argument as a repeat count, when
that makes sense.
ignores any numeric argument.
@end table
-@node GUD Tooltips
-@subsection GUD Tooltips
-
-@cindex tooltips with GUD
-The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. If
-GUD support is activated by customizing the @code{tooltip} group,
-variable values can be displayed in tooltips by pointing at them with
-the mouse in the GUD buffer or in source buffers with major modes in the
-customizable list @code{tooltip-gud-modes}.
-
@node GDB Graphical Interface
@subsection GDB Graphical Interface
+ By default, the command @code{gdb} starts GDB using a graphical
+interface where you view and control the program's data using Emacs
+windows. You can still interact with GDB through the GUD buffer, but
+the point of this mode is that you can do it through menus and clicks,
+without needing to know GDB commands. For example, you can click
+@kbd{Mouse-1} on a line of the source buffer, in the fringe or display
+margin, to set a breakpoint there. If a breakpoint already exists on
+that line, this action will remove it
+(@code{gdb-mouse-set-clear-breakpoint}). Where Emacs uses the margin
+to display breakpoints, it is also possible to enable or disable them
+when you click @kbd{Mouse-3} there
+(@code{gdb-mouse-toggle--breakpoint}).
+
+@vindex gud-gdb-command-name
@findex gdba
-The command @code{gdba} starts GDB using a graphical interface where
-you view and control the program's data using Emacs windows. You can
-still interact with GDB through the GUD buffer, but the point of this
-mode is that you can do it through menus and clicks, without needing
-to know GDB commands.
+ You can also run GDB in text command mode, which creates a buffer
+for input and output to GDB. To do this, set
+@code{gud-gdb-command-name} to @code{"gdb --fullname"} or edit the
+startup command in the minibuffer to say that. You need to do use
+text command mode to run multiple debugging sessions within one Emacs
+session. If you have customised @code{gud-gdb-command-name} in that
+way, then you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
@menu
* Layout:: Control the number of displayed buffers.
* Breakpoints Buffer:: A breakpoint control panel.
* Stack Buffer:: Select a frame from the call stack.
* Watch Expressions:: Monitor variable values in the speedbar.
-* Other Buffers:: Input/output, locals, registers and assembler buffers.
+* Other Buffers:: Input/output, locals, registers, assembler, threads
+ and memory buffers.
@end menu
@node Layout
gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
is the relevant buffer type e.g breakpoints.
+When you finish debugging then kill the GUD buffer with @kbd{C-x k},
+which will also kill all the buffers associated with the session.
+However you need not do this if, after editing and re-compiling your
+source code within Emacs, you wish continue debugging. When you
+restart execution, GDB will automatically find your new executable.
+Keeping the GUD buffer has the advantage of keeping the shell history
+as well as GDB's breakpoints. You need to check, however, that the
+breakpoints in the recently edited code are still where you want them.
+
@node Breakpoints Buffer
@subsubsection Breakpoints Buffer
@kindex RET @r{(GDB breakpoints buffer)}
@findex gdb-goto-breakpoint
Display the file in the source buffer at the breakpoint specified at
-the current line (@code{gdb-goto-breakpoint}). Alternatively, click @kbd{Mouse-2} on the breakpoint that you wish to visit.
+the current line (@code{gdb-goto-breakpoint}). Alternatively, click
+@kbd{Mouse-2} on the breakpoint that you wish to visit.
@end table
@node Stack Buffer
of the nested subroutine calls (@dfn{stack frames}) now active in the
program. @xref{Backtrace,,info stack, gdb, The GNU debugger}.
-Move point to any frame in the stack and type @key{RET} to make it
-become the current frame (@code{gdb-frames-select}) and display the
-associated source in the source buffer. Alternatively, click
-@kbd{Mouse-2} to make the selected frame become the current one. If the
-locals buffer is displayed then its contents update to display the
-variables that are local to the new frame.
+The selected frame is displayed in reverse contrast. Move point to
+any frame in the stack and type @key{RET} to select it (@code{gdb-frames-select})
+and display the associated source in the source buffer. Alternatively,
+click @kbd{Mouse-2} to make the selected frame become the current one.
+If the locals buffer is displayed then its contents update to display
+the variables that are local to the new frame.
@node Watch Expressions
@subsubsection Watch Expressions
debugger}).
Arrays and structures display their type only. You must display them
-separately to examine their values. @ref{Watch Expressions}.
+separately to examine their values. @xref{Watch Expressions}.
@item Registers Buffer
The registers buffer displays the values held by the registers
@item Assembler Buffer
The assembler buffer displays the current frame as machine code. An
overlay arrow points to the current instruction and you can set and
-remove breakpoints as with the source buffer. Breakpoints also
-appear in the margin.
+remove breakpoints as with the source buffer. Breakpoint icons also
+appear in the fringe or margin.
@item Threads Buffer
The threads buffer displays a summary of all threads currently in your
-program.(@pxref{Threads,,, gdb, The GNU debugger}). Move point to
+program (@pxref{Threads,,, gdb, The GNU debugger}). Move point to
any thread in the list and type @key{RET} to make it become the
current thread (@code{gdb-threads-select}) and display the associated
source in the source buffer. Alternatively, click @kbd{Mouse-2} to
make the selected thread become the current one.
+@item Memory Buffer
+
+The memory buffer allows the user to examine sections of program
+memory (@pxref{Memory,,, gdb, The GNU debugger}). Click @kbd{Mouse-1}
+on the appropriate part of the header line to change the starting
+address or number of data items that the buffer displays.
+Click @kbd{Mouse-3} on the header line to select the display format
+or unit size for these data items.
+
@end table
@node Executing Lisp
echo area. It is available in all major modes, not just Emacs-Lisp
mode. It does not treat @code{defvar} specially.
+ When the result of an evaluation is an integer, you can type
+@kbd{C-x C-e} a second time to display the value of the integer result
+in additional formats (octal, hexadecimal, and character).
+
If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numeric
argument, it inserts the value into the current buffer at point, rather
than displaying it in the echo area. The argument's value does not