From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Nick Roberts Newsgroups: gmane.emacs.devel Subject: Texinfo doc for GDB-UI Date: Mon, 23 Dec 2002 21:54:28 +0000 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <15879.34324.916528.669630@nick.uklinux.net> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-Trace: main.gmane.org 1040680922 26879 80.91.224.249 (23 Dec 2002 22:02:02 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Mon, 23 Dec 2002 22:02:02 +0000 (UTC) Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 18Qae6-0006zE-00 for ; Mon, 23 Dec 2002 23:01:58 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 18QahL-0000tZ-00 for ; Mon, 23 Dec 2002 23:05:19 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18QaeL-0008BO-01 for emacs-devel@quimby.gnus.org; Mon, 23 Dec 2002 17:02:13 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 18Qadm-0007MI-00 for emacs-devel@gnu.org; Mon, 23 Dec 2002 17:01:38 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 18QabU-0005hQ-00 for emacs-devel@gnu.org; Mon, 23 Dec 2002 16:59:20 -0500 Original-Received: from bts-0436.dialup.zetnet.co.uk ([194.247.49.180] helo=nick.uklinux.net) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18QaZF-0004QJ-00 for emacs-devel@gnu.org; Mon, 23 Dec 2002 16:56:57 -0500 Original-Received: by nick.uklinux.net (Postfix, from userid 501) id B13D976037; Mon, 23 Dec 2002 21:54:29 +0000 (GMT) Original-To: emacs-devel@gnu.org X-Mailer: VM 6.97 under Emacs 21.3.50.2 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Emacs development discussions. List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:10330 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:10330 Here is my attempt at writing something for gdb-ui.el for the emacs manual. I've not spent much time on it as it will probably change again. I just want to do enough so that it explains the mode and doesn't harm the `emacs brand name'. It probably also shows a lack of knowledge of texinfo. This file (building.texi) could also say something about bashdb. Any comments ? Nick *** building.texi.~1.26.~ Tue Oct 29 18:18:41 2002 --- building.texi Fri Dec 20 01:10:35 2002 *************** *** 288,293 **** --- 288,294 ---- * 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-UI:: Graphical user interface for GDB. @end menu @node Starting GUD *************** *** 303,308 **** --- 304,315 ---- 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} + @findex gdba + Run GDB as a subprocess of Emacs. This command generates a more extensive + user interface than the command gdb. These extra features are described in + @xref{GDB-UI}. + @item M-x dbx @key{RET} @var{file} @key{RET} @findex dbx Similar, but run DBX instead of GDB. *************** *** 438,443 **** --- 445,459 ---- will run until it hits a breakpoint, terminates, or gets a signal that the debugger is checking for (@code{gud-cont}). + @item C-c C-u + @kindex C-c C-u @r{(GUD)} + @itemx C-x C-a C-u + @findex gud-until + Continue execution up 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 that the cursor is on + (@code{gud-goto}). + @need 1000 @item C-c C-d @kindex C-c C-d @r{(GUD)} *************** *** 586,591 **** --- 602,797 ---- 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-UI + @subsection GDB-UI + + GDB-UI is invoked with the command @code{gdba}. As well as having the usual + features of GUD, it does the following : + + @itemize @bullet + + @item + Finds the source file where execution begins and displays it in a buffer. + + @item + Displays a bullet point icon in the margin on the line at which a + breakpoint is placed. This is red when the breakpoint is enabled and + grey when it is disabled. + + @item + Separates the IO of the executable from that of GDB and puts it in a + different buffer. + + @item + Auto-displays data in separate frames and formats arrays and structures. + It isalso possible to dive into structures.. + @end itemize + + It is generally best to stay in GDB while editing and re-compiling a + program. This can be done within emacs and this is generally easier + with just one or two windows. So, after re-compilation, the window + layout for the debugging session can be restored with + @code{gdb-restore-windows}. Once you have ensured the breakpoints are + correct, clicking on the run icon will restart the program. + + When you have finished debugging a particular program then don't just + kill the GUD buffer because this will leave a lot of other buffers + lying around. Instead use @code{gdb-quit} which will kill these + buffers and reset things like the toolbar and margin in the source + buffers. + + In addition to the GUD buffer and the source buffer, extra buffers may + be displayed : + + @menu + * Layout:: Control the number of buffers that are displayed. + * Breakpoints Buffer:: A breakpoint control panel. + * Stack Buffer:: Select a frame from the frame stack. + * Input/Output Buffer:: Input and output of the executable. + * Locals Buffer:: Display the local variables of the current frame. + * Registers Buffer:: Display the register values. + * Assembler Buffer:: Display the machine code. + * Display Buffer:: Control the displayed expressions. + * Data Display:: Display and update expressions in their own frame. + @end menu + + @node Layout + @subsubsection Layout + The extra buffers may either be displayed in the same frame + (@code{gdb-display-*-*}) or a different frame (@code{gdb-frame-*-*}) + where *-* needs to be replaced by the relevant buffer name. + + If @code{gdb-many-windows} is nil (the default value) then GDB starts with + just two windows : the GUD and the source buffer. If it is t the + following layout will appear (keybindings given in relevant buffer) : + + @verb{+--------------------------------------------------------------------- + GDB Toolbar + --------------------------------------------------------------------- + GUD buffer (I/O of GDB) | Locals buffer + | + | + | + --------------------------------------------------------------------- + Source buffer | Input/Output (of debuggee) buffer + | (comint-mode) + | + | + | + | + | + | + --------------------------------------------------------------------- + Stack buffer | Breakpoints buffer +} + `Mouse-2' gdb-frames-mouse-select | @key{SPC} gdb-toggle-bp-this-line + | `g' gdb-goto-bp-this-line + | `d' gdb-delete-bp-this-line + --------------------------------------------------------------------- + + @node Breakpoints Buffer + @subsubsection Breakpoints Buffer + + This buffer allows control of the breakpoints which have been set + previously and uses the output from the GDB command @xref{Set Breaks,, + info breakpoints, Gdb, The GNU debugger}. There are three commands + available : + + @table @kbd + @item @key{SPC} + Enable/disable the breakpoint on the current line + (@code{gdb-toggle-bp-this-line}). On a graphical display, a bullet + point icon is displayed in the margin of the source buffer at the + relevant line. This changes to red when the breakpoint is enabled and + grey when it is disabled. Text-only terminals will correspondingly + display a `B' or `b'. + + @item @kbd{g} + Display the file in the source buffer that contains the breakpoint + described on the current line (@code{gdb-goto-bp-this-line}). + + @item @kbd{d} + Delete the breakpoint on the current line + (@code{gdb-delete-bp-this-line}). + @end table + + @node Stack Buffer + @subsubsection Stack Buffer + + This buffer displays a frame stack and uses the output from the GDB command + @xref{Backtrace,,info stack, Gdb, The GNU debugger}. + + A frame stack is a list of nested subroutine calls which shows the + context of the current frame. + + (@code{gdb-frames-mouse-select}) on @kbd{Mouse-2} makes the selected + frame become the current one and displays the associated source in the + source buffer. + + @node Input/Output Buffer + @subsubsection Input/Output Buffer + + The executable program takes its input and displays its output here. Some + of the commands from shell mode are available here. @xref{Shell Mode}. + + @node Locals Buffer + @subsubsection Locals Buffer + + This buffer displays the values of local variables of the current + frame and uses the output from the GDB command @xref{Frame Info,, + info locals, Gdb, The GNU debugger}. + + Arrays and structures only have their type displayed. To + examine the values of these types the place the cursor over the + variable name and click on the display icon in the toolbar. + + @node Registers Buffer + @subsubsection Registers Buffer + + This buffer displays the values values held by the registers and uses + the output from the GDB command @xref{Registers,,info registers, Gdb, + The GNU debugger}. + + @node Assembler Buffer + @subsubsection Assembler Buffer + + This buffer displays the current frame as machine code. An overlay + arrow points to the current instruction and breakpoints can be set and + removed as with the source buffer. Breakpoint icons are also displayed. + + @node Display Buffer + @subsubsection Display Buffer + + This buffer controls the list of expressions set up to display + automatically and uses the output from the GDB command @xref{Auto + Display,,info display, Gdb, The GNU debugger}. As with the + breakpoints the displayed may be enabled/disabled or deleted. + + @table @kbd + @item @key{SPC} + Enable/disable the display on the current line + (@code{gdb-toggle-disp-this-line}). + + @item @kbd{d} + Delete the display on the current line (@code{gdb-delete-disp-this-line}). + @end table + + @node Data Display + @subsubsection Data Display + Displayed expressions appear in separate frames. Arrays are formatted + in an easy to read fashion and may be displayed as a slice. To do this, + at the top of the display window, click 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. + + One dimensional arrays can be visualised using the graph program from + plotutils if this is installed by typing @kbd{v} (@code{gdb-array-visualise}). + + Pointers in structures may be followed by in a tree-like fashion + clicking on them with the middle mouse button (@code{gdb-dive}). + + To delete the displayed expression and the window type + @kbd{q} (@code{gdb-delete-display}). @node Executing Lisp @section Executing Lisp Expressions