# HG changeset patch # User Richard M. Stallman # Date 1054122155 0 # Node ID 35bdcc98e5b18fa9c861cd3828959177b24c813a # Parent fd8bbce6c51faf14306c3f24e41435abe587efe1 (GDB Graphical Interface): New node (rewritten somewhat by RMS). diff -r fd8bbce6c51f -r 35bdcc98e5b1 man/building.texi --- a/man/building.texi Wed May 28 11:42:21 2003 +0000 +++ b/man/building.texi Wed May 28 11:42:35 2003 +0000 @@ -288,6 +288,9 @@ * 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 @@ 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 @@ 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 @@ 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