The previous chapter discusses the Emacs commands that are useful for
making changes in programs. This chapter deals with commands that assist
-in the larger process of developing and maintaining programs.
+in the larger process of compiling and testing programs.
@menu
* Compilation:: Compiling programs in languages other
@samp{run}.
@findex kill-compilation
- Starting a new compilation also kills any compilation
+ Starting a new compilation also kills any compilation already
running in @samp{*compilation*}, as the buffer can only handle one
compilation at any time. However, @kbd{M-x compile} asks for
confirmation before actually killing a compilation that is running.
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. It also momentarily
-highlights the relevant source line. You can change the behavior of
-this highlighting with the variable @code{next-error-highlight}.
+location of the error in another window. It also temporarily
+highlights the relevant source line, for a period controlled by the
+variable @code{next-error-highlight}.
The first time @w{@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
subprocesses; to work around this lack, @kbd{M-x compile} runs the
compilation command synchronously on MS-DOS. As a consequence, you must
wait until the command finishes before you can do anything else in
-Emacs. @xref{MS-DOS}.
+Emacs.
+@iftex
+@inforef{MS-DOS,,emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{MS-DOS}.
+@end ifnottex
@node Grep Searching
@section Searching with Grep under Emacs
Just as you can run a compiler from Emacs and then visit the lines
-with 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.''
+with 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.'' The
+buffer of matches uses Grep mode, which is a variant of Compilation
+mode (@pxref{Compilation Mode}).
@table @kbd
@item M-x grep
+@item M-x lgrep
Run @code{grep} asynchronously under Emacs, with matching lines
listed in the buffer named @samp{*grep*}.
@item M-x grep-find
@itemx M-x find-grep
+@itemx M-x rgrep
Run @code{grep} via @code{find}, with user-specified arguments, and
collect output in the buffer named @samp{*grep*}.
@item M-x kill-grep
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 detects the tag
-(@pxref{Tags}) around point, and puts that into the default
-@code{grep} command.
+specify a prefix argument for @kbd{M-x grep}, it finds the tag
+(@pxref{Tags}) in the buffer around point, and puts that into the
+default @code{grep} command.
+
+ Your command need not simply run @code{grep}; you can use any shell
+command that produces output in the same format. For instance, you
+can chain @code{grep} commands, like this:
+
+@example
+grep -nH -e foo *.el | grep bar | grep toto
+@end example
The output from @code{grep} goes in the @samp{*grep*} buffer. You
can find the corresponding lines in the original files using @w{@kbd{C-x
@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}.
+@findex lgrep
+@findex rgrep
+ The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep}
+(recursive grep) are more user-friendly versions of @code{grep} and
+@code{grep-find}, which prompt separately for the regular expression
+to match, the files to search, and the base directory for the search
+(rgrep only). Case sensitivity of the search is controlled by the
+current value of @code{case-fold-search}.
+
+These commands build the shell commands based on the variables
+@code{grep-template} (for @code{lgrep}) and @code{grep-find-template}
+(for @code{rgrep}).
+
+The files to search can use aliases defined in the variable
+@code{grep-files-aliases}.
+
+Subdirectories listed in the variable
+@code{grep-find-ignored-directories} such as those typically used by
+various version control systems, like CVS and arch, are automatically
+skipped by @code{rgrep}.
+
@node Flymake
@section Finding Syntax Errors On The Fly
@cindex checking syntax
@kindex C-x C-a @r{(GUD)}
Here are the other special commands provided by GUD@. The keys
starting with @kbd{C-c} are available only in the GUD interaction
-buffer. The key bindings that start with @kbd{C-x C-a} are available in
-the GUD interaction buffer and also in source files.
+buffer. The key bindings that start with @kbd{C-x C-a} are available
+in the GUD interaction buffer and also in source files. Some of these
+commands are not available to all the supported debuggers.
@table @kbd
@item C-c C-l
@findex gud-stepi
Execute a single machine instruction (@code{gud-stepi}).
+@item C-c C-p
+@kindex C-c C-p @r{(GUD)}
+@itemx C-x C-a C-p
+@findex gud-print
+Evaluate the expression at point (@code{gud-print}). If Emacs
+does not print the exact expression that you want, mark it as a region
+first.
+
@need 3000
@item C-c C-r
@kindex C-c C-r @r{(GUD)}
Set a temporary breakpoint on the current source line, if any
(@code{gud-tbreak}). If you use this command in the GUD interaction
buffer, it applies to the line where the program last stopped.
-@end table
- The above commands are common to all supported debuggers. If you are
-using GDB or (some versions of) DBX, these additional commands are available:
-
-@table @kbd
@item C-c <
@kindex C-c < @r{(GUD)}
@itemx C-x C-a <
@findex gud-down
Select the next inner stack frame (@code{gud-down}). This is
equivalent to the GDB command @samp{down}.
-@end table
-
- If you are using GDB, these additional key bindings are available:
-
-@table @kbd
-@item C-c C-r
-@kindex C-c C-r @r{(GUD)}
-@itemx C-x C-a C-r
-@findex gud-run
-Start execution of the program (@code{gud-run}).
@item C-c C-u
@kindex C-c C-u @r{(GUD)}
that the debugger is checking for, or reaches the line on which the
cursor currently sits.
-@item @key{TAB}
-@kindex TAB @r{(GUD)}
-@findex gud-gdb-complete-command
-With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
-This key is available only in the GUD interaction buffer.
-
@item C-c C-f
@kindex C-c C-f @r{(GUD)}
@itemx C-x C-a C-f
@findex gud-finish
-Run the program until the selected stack frame returns or
+Run the program until the selected stack frame returns or
stops for some other reason (@code{gud-finish}).
+@end table
+
+ If you are using GDB, these additional key bindings are available:
+@table @kbd
@item C-x C-a C-j
@kindex C-x C-a C-j @r{(GUD)}
@findex gud-jump
the previously one, GDB prompts for confirmation since the results may
be bizarre. See the GDB manual entry regarding @code{jump} for
details.
+
+@item @key{TAB}
+@kindex TAB @r{(GUD)}
+@findex gud-gdb-complete-command
+With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
+This key is available only in the GUD interaction buffer.
@end table
These commands interpret a numeric argument as a repeat count, when
The name of the current source file. If the current buffer is the GUD
buffer, then the ``current source file'' is the file that the program
stopped in.
-@c This said, ``the name of the file the program counter was in at the last breakpoint.''
-@c But I suspect it is really the last stop file.
@item %l
The number of the current source line. If the current buffer is the GUD
stopped in.
@item %e
-The text of the C lvalue or function-call expression at or adjacent to point.
+In transient-mark-mode the text in the region, if it is active.
+Otherwise the text of the C lvalue or function-call expression at or
+adjacent to point.
@item %a
The text of the hexadecimal address at or adjacent to point.
If you don't use @samp{%p} in the command string, the command you define
ignores any numeric argument.
+
+@item %d
+The name of the directory of the current source file.
+
+@item %c
+Fully qualified class name derived from the expression surrounding point
+(jdb only).
@end table
@node GDB Graphical Interface
interface, using Emacs windows for display program state information.
In effect, this makes Emacs into an IDE (interactive development
environment). With it, you do not need to use textual GDB commands;
-you can control the debugging session with the mouse.
-
-@c @findex gdb-mouse-set-clear-breakpoint
-@c @findex gdb-mouse-toggle-breakpoint
- For example, you can click @kbd{Mouse-1} in the fringe or display
-margin of a source buffer to set a breakpoint there and, on a
-graphical display, a red bullet will appear on that line. If a
-breakpoint already exists on that line, the same click will remove it.
-You can also enable or disable a breakpoint by clicking @kbd{Mouse-3}
-on the bullet. If you drag the debugger arrow in the fringe with
-@kbd{Mouse-1} (@code{gdb-mouse-until}), execution will continue to the
-line where you release the button, provided it is still in the same
-frame. Alternatively, you can click @kbd{Mouse-2} at some point in
-the fringe of this buffer and execution will advance to there.
+you can control the debugging session with the mouse. For example,
+you can click in the fringe of a source buffer to set a breakpoint
+there, or on a stack frame in the stack buffer to select that frame.
This mode requires telling GDB that its ``screen size'' is
unlimited, so it sets the height and width accordingly. For correct
that way, you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
@menu
-* GDB User Interface Layout:: Control the number of displayed buffers.
+* GDB-UI Layout:: Control the number of displayed buffers.
+* Source Buffers:: Use the mouse in the fringe/margin to
+ control your program.
* Breakpoints Buffer:: A breakpoint control panel.
* Stack Buffer:: Select a frame from the call stack.
-* Watch Expressions:: Monitor variable values in the speedbar.
-* Other GDB User Interface Buffers:: Input/output, locals, registers,
+* Other GDB-UI Buffers:: Input/output, locals, registers,
assembler, threads and memory buffers.
+* Watch Expressions:: Monitor variable values in the speedbar.
@end menu
-@node GDB User Interface Layout
+@node GDB-UI Layout
@subsubsection GDB User Interface Layout
@cindex GDB User Interface layout
If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb}
displays the following frame layout:
-@example
+@smallexample
+@group
+--------------------------------+--------------------------------+
-| | |
-| GUD buffer (I/O of GDB) | Locals buffer |
-| | |
+| GUD buffer (I/O of GDB) | Locals buffer |
|--------------------------------+--------------------------------+
-| | |
-| Source buffer | I/O buffer (of inferior) |
-| | |
+| Primary Source buffer | I/O buffer for debugged pgm |
|--------------------------------+--------------------------------+
-| | |
-| Stack buffer | Breakpoints buffer |
-| | |
+| Stack buffer | Breakpoints buffer |
+--------------------------------+--------------------------------+
-@end example
+@end group
+@end smallexample
- However, if @code{gdb-use-inferior-io-buffer} is @code{nil}, the I/O
-buffer does not appear and the source buffer occupies the full width
-of the frame.
+ However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
+buffer does not appear and the primary source buffer occupies the full
+width of the frame.
@findex gdb-restore-windows
If you change the window layout, for example, while editing and
containing just the GUD buffer and a source file, type @kbd{M-x
gdb-many-windows}.
- You may also specify additional GUD-related buffers to display,
+ You may also specify additional GDB-related buffers to display,
either in the same frame or a different one. Select the buffers you
want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames}
sub-menus. If the menu-bar is unavailable, type @code{M-x
breakpoints in recently edited source files are still in the right
places.
+@node Source Buffers
+@subsubsection Source Buffers
+@cindex GDB commands in Fringe
+
+@c @findex gdb-mouse-set-clear-breakpoint
+@c @findex gdb-mouse-toggle-breakpoint
+Many GDB commands can be entered using keybindings or the tool bar but
+sometimes it is quicker to use the fringe. These commands either
+manipulate breakpoints or control program execution. When there is no
+fringe, you can use the margin but this is only present when the
+source file already has a breakpoint.
+
+You can click @kbd{Mouse-1} in the fringe or display margin of a
+source buffer to set a breakpoint there and, on a graphical display, a
+red bullet will appear on that line. If a breakpoint already exists
+on that line, the same click will remove it. You can also enable or
+disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
+
+A solid arrow in the left fringe of a source buffer indicates the line
+of the innermost frame where the debugged program has stopped. A
+hollow arrow indicates the current execution line of higher level
+frames.
+
+If you drag the arrow in the fringe with @kbd{Mouse-1}
+(@code{gdb-mouse-until}), execution will continue to the line where
+you release the button, provided it is still in the same frame.
+Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
+of this buffer and execution will advance to there. A similar command
+(@code{gdb-mouse-jump}) allows you to jump to a source line without
+executing the intermediate lines by clicking @kbd{C-Mouse-3}. This
+command allows you to go backwards which can be useful for running
+through code that has already executed, in order to examine its
+execution in more detail.
+
+@table @kbd
+@item Mouse-1
+Set or clear a breakpoint.
+
+@item C-Mouse-1
+Enable or disable a breakpoint.
+
+@item Mouse-3
+Continue execution to here.
+
+@item C-Mouse-3
+Jump to here.
+@end table
+
+If the variable @code{gdb-find-source-frame} is non-@code{nil} and
+execution stops in a frame for which there is no source code e.g after
+an interrupt, then Emacs finds and displays the first frame further up
+stack for which there is source. If it is @code{nil} then the source
+buffer continues to display the last frame which maybe more useful,
+for example, when re-setting a breakpoint.
+
@node Breakpoints Buffer
@subsubsection Breakpoints Buffer
- The breakpoints buffer shows the existing breakpoints and
-watchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has
+ The breakpoints buffer shows the existing breakpoints, watchpoints and
+catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has
these special commands, which mostly apply to the @dfn{current
breakpoint}, the breakpoint which point is on.
@findex gdb-toggle-breakpoint
Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}).
On a graphical display, this changes the color of a bullet in the
-margin of the source buffer at the relevant line. This is red when
+margin of a source buffer at the relevant line. This is red when
the breakpoint is enabled and grey when it is disabled. Text-only
terminals correspondingly display a @samp{B} or @samp{b}.
program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
@findex gdb-frames-select
- The selected frame number is displayed in reverse contrast. To
-select a frame in GDB, move point in the stack buffer to that stack
-frame and type @key{RET} (@code{gdb-frames-select}), or click
+An arrow in the fringe points to the selected frame or, if the fringe is
+not present, the number of the selected frame is displayed in reverse
+contrast. To select a frame in GDB, move point in the stack buffer to
+that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
@kbd{Mouse-2} on a stack frame. If the locals buffer is visible,
-selecting a stack frame updates it to display the local variables of
-the new frame.
-
-@node Watch Expressions
-@subsubsection Watch Expressions
-@cindex Watching expressions in GDB
-
-@findex gud-watch
- If you want to see how a variable changes each time your program
-stops, move point into the variable name and click on the watch icon
-in the tool bar (@code{gud-watch}).
+selecting a stack frame updates it to display the local variables of the
+new frame.
- Each watch expression is displayed in the speedbar. Complex data
-types, such as arrays, structures and unions are represented in a tree
-format. Leaves and simple data types show the name of the expression
-and its value, and display the type as a tooltip. Higher levels show
-the name, type and address value for pointers and just the name and
-type otherwise.
-
- To expand or contract a complex data type, click @kbd{Mouse-2}
-on the tag to the left of the expression.
-
-@findex gdb-var-delete
- To delete a complex watch expression, move point to the root
-expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
-
-@kindex RET @r{(GDB speedbar)}
-@findex gdb-edit-value
- To edit a variable with a simple data type, or a simple element of a
-complex data type, move point there in the speedbar and type @key{RET}
-(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to
-edit it. Either way, this reads the new value using the minibuffer.
-
-@vindex gdb-show-changed-values
- If you set the variable @code{gdb-show-changed-values} to
-non-@code{nil} (the default value), Emacs uses
-@code{font-lock-warning-face} to highlight values that have recently
-changed.
-
-@vindex gdb-use-colon-colon-notation
- If the variable @code{gdb-use-colon-colon-notation} is
-non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
-format to display variables in the speedbar. Since this does not work
-for variables defined in compound statements, the default value is
-@code{nil}.
-
-@node Other GDB User Interface Buffers
+@node Other GDB-UI Buffers
@subsubsection Other Buffers
@table @asis
@item Input/Output Buffer
-@vindex gdb-use-inferior-io-buffer
-If the variable @code{gdb-use-inferior-io-buffer} is non-@code{nil},
-the executable program that is being debugged takes its input and
-displays its output here. Otherwise it uses the GUD buffer for that.
-To toggle the use of this buffer, do @kbd{M-x
-gdb-use-inferior-io-buffer}.
+@vindex gdb-use-separate-io-buffer
+If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil},
+the program being debugged takes its input and displays its output
+here. Otherwise it uses the GUD buffer for that. To toggle whether
+GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
+This takes effect when you next restart the program you are debugging.
-Some of the commands from shell mode are available here. @xref{Shell
-Mode}.
+The history and replay commands from Shell mode are available here,
+as are the commands to send signals to the debugged program.
+@xref{Shell Mode}.
@item Locals Buffer
The locals buffer displays the values of local variables of the
current frame for simple data types (@pxref{Frame Info, Frame Info,
-Information on a frame, gdb, The GNU debugger}).
+Information on a frame, gdb, The GNU debugger}). Press @key{RET} or
+click @kbd{Mouse-2} on the value if you want to edit it.
Arrays and structures display their type only. With GDB 6.4 or later,
move point to their name and press @key{RET}, or alternatively click
@kbd{Mouse-2} there, to examine their values. With earlier versions
-of GDB, move point to their type description ([struct/union] or
-[array]). @xref{Watch Expressions}.
+of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
+(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}.
@item Registers Buffer
@findex toggle-gdb-all-registers
The registers buffer displays the values held by the registers
(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or
-click @kbd{Mouse-2} on a register if you want to change its value.
+click @kbd{Mouse-2} on a register if you want to edit its value.
With GDB 6.4 or later, recently changed register values display with
@code{font-lock-warning-face}. With earlier versions of GDB, you can
press @key{SPC} to toggle the display of floating point registers
program (@pxref{Threads, Threads, Debugging programs with multiple
threads, gdb, The GNU debugger}). Move point to any thread in the
list and press @key{RET} to select it (@code{gdb-threads-select}) and
-display the associated source in the source buffer. Alternatively,
-click @kbd{Mouse-2} on a thread to select it. If the locals buffer is
-visible, its contents update to display the variables that are local
-in the new thread.
+display the associated source in the primary source buffer.
+Alternatively, click @kbd{Mouse-2} on a thread to select it. If the
+locals buffer is visible, its contents update to display the variables
+that are local in the new thread.
@item Memory Buffer
The memory buffer lets you examine sections of program memory
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 Watch Expressions
+@subsubsection Watch Expressions
+@cindex Watching expressions in GDB
+
+@findex gud-watch
+@kindex C-x C-a C-w @r{(GUD)}
+ If you want to see how a variable changes each time your program
+stops, move point into the variable name and click on the watch icon
+in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you
+specify a prefix argument, you can enter the variable name in the
+minibuffer.
+
+ Each watch expression is displayed in the speedbar. Complex data
+types, such as arrays, structures and unions are represented in a tree
+format. Leaves and simple data types show the name of the expression
+and its value and, when the speedbar frame is selected, display the
+type as a tooltip. Higher levels show the name, type and address
+value for pointers and just the name and type otherwise. Root expressions
+also display the frame address as a tooltip to help identify the frame
+in which they were defined.
+
+ To expand or contract a complex data type, click @kbd{Mouse-2}
+on the tag to the left of the expression.
+
+@kindex D @r{(GDB speedbar)}
+@findex gdb-var-delete
+ To delete a complex watch expression, move point to the root
+expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}).
+
+@kindex RET @r{(GDB speedbar)}
+@findex gdb-edit-value
+ To edit a variable with a simple data type, or a simple element of a
+complex data type, move point there in the speedbar and type @key{RET}
+(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to
+edit it. Either way, this reads the new value using the minibuffer.
+
+@vindex gdb-show-changed-values
+ If you set the variable @code{gdb-show-changed-values} to
+non-@code{nil} (the default value), Emacs uses
+@code{font-lock-warning-face} to highlight values that have recently
+changed and @code{shadow} face to make variables which have gone out of
+scope less noticeable. When a variable goes out of scope you can't
+edit its value.
+
+@vindex gdb-use-colon-colon-notation
+ If the variable @code{gdb-use-colon-colon-notation} is
+non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}}
+format. This allows the user to display watch expressions which share
+the same variable name. The default value is @code{nil}.
+
+@vindex gdb-speedbar-auto-raise
+To automatically raise the speedbar every time the display of watch
+expressions updates, set @code{gdb-speedbar-auto-raise} to
+non-@code{nil}. This can be useful if you are debugging with a full
+screen Emacs frame.
+
@node Executing Lisp
@section Executing Lisp Expressions
the echo area (@code{eval-defun}).
@item M-x eval-region
Evaluate all the Lisp expressions in the region.
-@item M-x eval-current-buffer
+@item M-x eval-buffer
Evaluate all the Lisp expressions in the buffer.
@end table
definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}).
@findex eval-region
-@findex eval-current-buffer
+@findex eval-buffer
The most general command for evaluating Lisp expressions from a buffer
is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
region as one or more Lisp expressions, evaluating them one by one.
-@kbd{M-x eval-current-buffer} is similar but evaluates the entire
+@kbd{M-x eval-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 ready to test. Later, as you find bugs and
change individual functions, use @kbd{C-M-x} on each function that you
@vindex eval-expression-print-level
@vindex eval-expression-print-length
@vindex eval-expression-debug-on-error
-The customizable variables @code{eval-expression-print-level} and
+ The two customizable variables @code{eval-expression-print-level} and
@code{eval-expression-print-length} control the maximum depth and length
of lists to print in the result of the evaluation commands before
abbreviating them. @code{eval-expression-debug-on-error} controls
is to use Inferior Emacs-Lisp mode, which provides an interface rather
like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
-which uses this mode.
+which uses this mode. For more information see that command's
+documentation.
@node External Lisp
@section Running an External Lisp