@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Building, Maintaining, Programs, Top
@chapter Compiling and Testing Programs
@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
@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
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
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
+to match, the files to search, and the base directory for the search.
+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
@subsection Debugger Operation
@cindex fringes, and current execution line in GUD
- When you run a debugger with GUD using the textual interface, the
-debugger uses an Emacs buffer for its ordinary input and output. This
-is called the GUD buffer. Input and output from the program you are
-debugging also use this buffer.
+ Generally 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. Input and output from the program you are debugging also use
+this buffer. We call this @dfn{text command mode}. The GDB Graphical
+Interface can use further buffers (@pxref{GDB Graphical Interface}).
The debugger displays the source files of the program by visiting
them in Emacs buffers. An arrow in the left fringe indicates the
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.
+tooltip simply by pointing at it with the mouse. 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. When debugging a C program using the GDB Graphical Interface, you
+can also display macro definitions associated with an identifier when
+the program is not executing.
GUD tooltips are disabled when you use GDB in text command mode
(@pxref{GDB Graphical Interface}), because displaying an expression's
@vindex gud-gdb-command-name
@findex gdba
You can also run GDB in text command mode, like other debuggers. 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 customized @code{gud-gdb-command-name} in
-that way, you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
+do this, replace the GDB @code{"--annotate=3"} option with
+@code{"--fullname"} either in the minibuffer for the current Emacs
+session, or the custom variable @code{gud-gdb-command-name} for all
+future sessions. You need to use text command mode to debug multiple
+programs within one Emacs session. If you have customized
+@code{gud-gdb-command-name} in this 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.
-* Other GDB User Interface Buffers:: Input/output, locals, registers,
+* Other GDB-UI Buffers:: Input/output, locals, registers,
assembler, threads and memory buffers.
-* GDB commands in the Fringe:: Use the mouse in the fringe/margin to
- control your program.
* 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 |
-| | |
|--------------------------------+--------------------------------+
-| | |
-| Source buffer | I/O buffer for debugged pgm |
-| | |
+| Primary Source buffer | I/O buffer for debugged pgm |
|--------------------------------+--------------------------------+
-| | |
| Stack buffer | Breakpoints buffer |
-| | |
+--------------------------------+--------------------------------+
-@end example
+@end group
+@end smallexample
However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
-buffer does not appear and the source buffer occupies the full width
-of the frame.
+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.
+selecting a stack frame updates it to display the local variables of the
+new frame.
-@node Other GDB User Interface Buffers
+@node Other GDB-UI Buffers
@subsubsection Other Buffers
@table @asis
@item Input/Output Buffer
@vindex gdb-use-separate-io-buffer
If the variable @code{gdb-use-separate-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 whether GUD mode uses this buffer, do @kbd{M-x
-gdb-use-separate-io-buffer}. That takes effect when you next
-restart the program you are debugging.
+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.
The history and replay commands from Shell mode are available here,
-as are the commands to send signals to the program you are debugging.
+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
@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
display format or unit size for these data items.
@end table
-@node GDB commands in the Fringe
-@subsubsection GDB commands in the Fringe
-@cindex GDB commands in the 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.
-
-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-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
-
@node Watch Expressions
@subsubsection Watch Expressions
@cindex Watching expressions in GDB
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.
+ To expand or contract a complex data type, click @kbd{Mouse-2} or
+press @key{SPC} on the tag to the left of the expression. Emacs asks
+for confirmation before expanding the expression if its number of
+immediate children exceeds the value of the variable
+@code{gdb-max-children}.
@kindex D @r{(GDB speedbar)}
@findex gdb-var-delete
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