* Compilation Mode:: The mode for visiting compiler errors.
* Compilation Shell:: Customizing your shell properly
for use in the compilation buffer.
-* Debuggers:: Running symbolic debuggers for non-Lisp programs.
-* Executing Lisp:: Various modes for editing Lisp programs,
+* Debuggers:: Running symbolic debuggers for non-Lisp programs.
+* Executing Lisp:: Various modes for editing Lisp programs,
with different facilities for running
- the Lisp programs.
+ the Lisp programs.
* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
-* External Lisp:: Communicating through Emacs with a separate Lisp.
+* External Lisp:: Communicating through Emacs with a separate Lisp.
@end menu
@node Compilation
directory.
@vindex compile-command
- When the shell command line is read, the minibuffer appears containing
-a default command line, which is the command you used the last time you
-did @kbd{M-x compile}. If you type just @key{RET}, the same command
-line is used again. For the first @kbd{M-x compile}, the default is
-@samp{make -k}. The default compilation command comes from the variable
+ When the shell command line is read, the minibuffer appears
+containing a default command line, which is the command you used the
+last time you did @kbd{M-x compile}. If you type just @key{RET}, the
+same command line is used again. For the first @kbd{M-x compile}, the
+default is @samp{make -k}, which is correct most of the time for
+nontrivial programs. (@xref{Top,, Make, make, GNU Make Manual}.)
+The default compilation command comes from the variable
@code{compile-command}; if the appropriate compilation command for a
file is something other than @samp{make -k}, it can be useful for the
file to specify a local value for @code{compile-command} (@pxref{File
recompile}. This automatically reuses the compilation command from the
last invocation of @kbd{M-x compile}.
+ Emacs does not expect a compiler to launch asynchronous
+subprocesses; if it does, and they keep running after the main
+compiler process has terminated, their output may not arrive in Emacs.
+
@node Grep Searching
@section Searching with Grep under Emacs
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},
+@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference Manual},
for information on debugging Emacs Lisp programs.
@menu
* 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.
@end menu
@node Starting GUD
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}.
+
@item M-x dbx @key{RET} @var{file} @key{RET}
@findex dbx
Similar, but run DBX instead of GDB.
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)}
+@itemx C-x C-a C-u
+@findex gud-until
+Continue execution to the current line. The program will run until
+it hits a breakpoint, terminates, gets a signal that the debugger is
+checking for, or reaches the line on which the cursor currently sits
+(@code{gud-until}).
+
@item @key{TAB}
@kindex TAB @r{(GUD)}
@findex gud-gdb-complete-command
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
+@item C-x C-a C-j
+@kindex C-x C-a C-j @r{(GUD)}
@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 @code{jump} for details.
+Only useful in a source buffer, (@code{gud-jump}) transfers the
+program's execution point to the current line. In other words, the
+next line that the program executes will be the one where you gave the
+command. If the new execution line is in a different function from
+the previously one, GDB prompts for confirmation since the results may
+be bizarre. See the GDB manual entry regarding @code{jump} for
+details.
@end table
These commands interpret a numeric argument as a repeat count, when
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
+
+@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.
+
+@menu
+* Breakpoints Buffer:: A breakpoint control panel.
+* Stack Buffer:: Select a frame from the call stack.
+* Data Display:: Display and update expressions in their own buffer.
+* Display Buffer:: Control the displayed expressions.
+* Other Buffers:: Input/output, locals, registers and assembler buffers.
+* Layout:: Control the number of displayed buffers.
+@end menu
+
+@node Breakpoints Buffer
+@subsubsection Breakpoints Buffer
+
+The breakpoints buffer shows the existing breakpoints and watchpoints
+(@pxref{Breakpoints,,, gdb, The GNU debugger}). It has three special
+commands:
+
+@table @kbd
+@item @key{SPC}
+@kindex SPC @r{(GDB breakpoints buffer)}
+@findex gdb-toggle-breakpoint
+Enable/disable the breakpoint at the current line
+(@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 the breakpoint is enabled and grey
+when it is disabled. Text-only terminals correspondingly display
+a @samp{B} or @samp{b}.
+
+@item @kbd{d}
+@kindex d @r{(GDB breakpoints buffer)}
+@findex gdb-delete-breakpoint
+Delete the breakpoint at the current line (@code{gdb-delete-breakpoint}).
+
+@item @key{RET}
+@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.
+@end table
+
+@node Stack Buffer
+@subsubsection Stack Buffer
+
+The stack buffer displays a @dfn{call stack}, with one line for each
+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.
+
+@node Data Display
+@subsubsection Data Display
+@cindex displaying expressions in GDB
+
+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 display
+icon in the toolbar (@code{gud-display}).
+
+Each displayed expression has its own frame on a graphical display and
+its own buffer on a text-only terminal. Arrays and structures have
+their own display formats. To display an array as a slice, at the top
+of the display window, click @kbd{Mouse-2} on the array index that you
+want to restrict and you will be prompted in the mini-buffer for a
+start and a stop value. Click @kbd{Mouse-2} on a pointer to
+dereference it in the same frame/buffer. Click @kbd{S-Mouse-2} there
+to do the same thing but in a new frame/buffer. There are two special
+commands for these buffers:
+
+@table @kbd
+@item @kbd{v}
+@kindex v @r{(GDB data buffer)}
+@findex gdb-array-visualise
+Visualise an array using the graph program from plotutils if this is
+installed. This only works for one dimensional arrays
+(@code{gdb-array-visualise}).
+
+@item @kbd{q}
+@kindex q @r{(GDB data buffer)}
+@findex gdb-delete-expression
+Delete the displayed expression and the associated frame
+(@code{gdb-delete-expression}).
+@end table
+
+@node Display Buffer
+@subsubsection Display Buffer
+
+The display buffer shows the list of displayed expressions
+(@pxref{Auto Display,,, gdb, The GNU debugger}). As with the
+breakpoints, you can enable/disable or delete the displayed
+expressions:
+
+@table @kbd
+@item @key{SPC}
+@kindex SPC @r{(GDB display buffer)}
+@findex gdb-toggle-display
+Enable/disable the display at the current line
+(@code{gdb-toggle-display}).
+
+@item @kbd{d}
+@kindex d @r{(GDB display buffer)}
+@findex gdb-delete-display
+Delete the display at the current line (@code{gdb-delete-display}).
+@end table
+
+@node Other Buffers
+@subsubsection Other Buffers
+
+@table @asis
+@item Input/Output Buffer
+The executable program that is being debugged takes its input and
+displays its output here. Some of the commands from shell mode are
+available here. @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,,, gdb, The GNU
+debugger}).
+
+Arrays and structures display their type only. You must display them
+separately to examine their values. @ref{Data Display}.
+
+@item Registers Buffer
+The registers buffer displays the values held by the registers
+(@pxref{Registers,,, gdb, The GNU debugger}).
+
+@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.
+@end table
+
+@node Layout
+@subsubsection Layout
+@cindex GDB User Interface layout
+You may choose to display the additional buffers described previously
+either in the same frame or a different one. Select GDB-windows or
+GDB-Frames from the menu-bar under the heading GUD. If the menu-bar
+is unavailable, type @code{M-x
+gdb-display-@var{buffertype}-buffer} or @code{M-x
+gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
+is the relevant buffer type e.g breakpoints.
+
+@findex gdb-many-windows
+@vindex gdb-many-windows
+If @code{gdb-many-windows} is @code{nil} (the default value), then GDB starts
+with just two windows: the GUD and the source buffer. If it is @code{t}, then
+six windows with the following layout will appear:
+
+@multitable @columnfractions .5 .5
+@item GUD buffer (I/O of GDB)
+@tab Locals buffer
+@item
+@tab
+@item Source buffer
+@tab Input/Output (of debuggee) buffer
+@item
+@tab
+@item Stack buffer
+@tab Breakpoints buffer
+@end multitable
+
+To toggle this layout, do @kbd{M-x gdb-many-windows}.
+
+@findex gdb-restore-windows
+If you change the window layout, for example, while editing and
+re-compiling your program, then you can restore it with
+@code{gdb-restore-windows}.
+
@node Executing Lisp
@section Executing Lisp Expressions