(GDB Graphical Interface): New node (rewritten somewhat by RMS).

2 files changed, 209 insertions, 0 deletions

diff --git a/man/ChangeLog b/man/ChangeLog
index 1f52a603228..9170a4912e0 100644
--- a/man/ChangeLog
+++ b/man/ChangeLog
@@ -1,3 +1,8 @@
+2003-05-28  Nick Roberts  <nick@nick.uklinux.net>
+
+        * building.texi (GDB Graphical Interface): New node.
+        (Rewritten somewhat by RMS.)
+
 2003-05-28  Kai Gro,A_(Bjohann  <kai.grossjohann@gmx.net>
 
         * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for
diff --git a/man/building.texi b/man/building.texi
index 8169b64a1bf..e9dd079ccd9 100644
--- a/man/building.texi
+++ b/man/building.texi
@@ -288,6 +288,9 @@ for information on debugging Emacs Lisp programs.
 * 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
@@ -303,6 +306,10 @@ Run GDB as a subprocess of Emacs.  This 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}.
+
 @item M-x dbx @key{RET} @var{file} @key{RET}
 @findex dbx
 Similar, but run DBX instead of GDB.
@@ -478,6 +485,21 @@ equivalent to the @samp{down} command.
   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
@@ -587,6 +609,188 @@ 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
+
+@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