@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
-recompile}. This automatically reuses the compilation command from the
-last invocation of @kbd{M-x compile}.
+recompile}. This automatically reuses the compilation command from
+the last invocation of @kbd{M-x compile}. It also reuses the
+@samp{*compilation*} buffer and starts the compilation in its default
+directory, which is the directory in which the previous compilation
+was started.
Emacs does not expect a compiler process to launch asynchronous
subprocesses; if it does, and they keep running after the main
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 `}
buffer and finds no more error messages to visit, it fails and signals
an Emacs error.
+When the left fringe is displayed, an arrow points to the
+current message in the compilation buffer. The variable
+@code{compilation-context-lines} controls the number of lines of
+leading context in the window before the current message. If it is
+@code{nil} and the left fringe is displayed, the window doesn't
+scroll. If there is no left fringe, no arrow is displayed and a value
+of @code{nil} means display the message at the top of the window.
+
You don't have to be in the compilation buffer in order to use
@code{next-error}. If one window on the selected frame can be the
target of the @code{next-error} call, it is used. Else, if a buffer
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 gud-tooltip-mode
+@vindex gud-tooltip-echo-area
+ The Tooltip facility (@pxref{Tooltips}) provides support for GUD@.
+You activate this feature by turning on the minor mode
+@code{gud-tooltip-mode}. 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 @code{#define} directive
+associated with an identifier when the program is not executing. This
+operates in the GUD buffer and in source buffers with major modes in
+the list @code{gud-tooltip-modes}. If the variable
+@code{gud-tooltip-echo-area} is non-@code{nil} then the variable's
+value is displayed in the echo area.
+
+With GDB in text command mode (@pxref{GDB Graphical Interface}),
+it is possible that use of GUD tooltips can cause a function to be
+called with harmful side-effects. In this case, Emacs disables
+them.
+
@node Commands of GUD
@subsection Commands of GUD
also provides commands for setting and clearing breakpoints, for
selecting stack frames, and for stepping through the program. These
commands are available both in the GUD buffer and globally, but with
-different key bindings. It also has its own toolbar from which you
+different key bindings. It also has its own tool bar from which you
can invoke the more common commands by clicking on the appropriate
icon. This is particularly useful for repetitive commands like
gud-next and gud-step and allows the user to hide the GUD buffer.
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
If you want to see how a variable changes each time your program stops
then place the cursor over the variable name and click on the watch
-icon in the toolbar (@code{gud-watch}).
+icon in the tool bar (@code{gud-watch}).
Each watch expression is displayed in the speedbar. Complex data
types, such as arrays, structures and unions are represented in a tree
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.
- 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
-matter.
+ 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-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 matter.
+@kbd{C-M-x} with a numeric argument instruments the function
+definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
@findex eval-region
@findex eval-current-buffer
HCoop / bpt / emacs.git / blobdiff