Using the Graphical Interface to GDB

The GNU Source-Level Debugger

Edition 4.13.3, for GDB version 4.17.gnat.3.13p -1

May 19, 1999

by Albert K. Lee
based on original by Stanley T. Shebs


Table of Contents


@input texiplus

Copyright (C) 1994, 1995, 1998, 1999 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Starting GDBTk

GDBTk will, by default, run using its graphical interface. When running on a UNIX system, the following requirements must be met, or else the debugger will revert to a command line interface:

The Windows NT/95/98 version of GDBTk will default to a graphical interface. To force the debugger to run in command line mode, invoke it with the -nw option.

Getting Acquainted

Menus

All of the main GDBTk windows have in common a File menu, an Options menu, and a Window menu. Of these, the File and Window menus will always contain the same entries.

File Menu

The standard file menu provides operations that affect the overall state of GDB.

Windows Menu

The windows menu allows access to all the windows available in GDB. If the window exists already, selecting the item will cause the window to be put in front. If it does not exist, then it will be created.

Options Menu

All the primary windows have an Options menu, but each menu's contents are highly specific to its window's type. For instance, a source window will have an options menu item to control the display of line numbers, but a register window will instead have an option to choose the radix in which to display register contents. You can find the full descriptions of available options with the description of each GDBTk window below.

Windows

Command Window

The command window provides access to the standard GDB command interpreter. In nearly all cases, commands typed into this window will behave exactly the same as a non-windowing GDB.

Note that not all changes to GDB will be reflected in this window. For instance, if you were to type a step command, then click on the `step' menu item in the source window, then go back to the command window to type another step command, the command buffer will only show two steps, when you have actually done three.

Source Window

The source window displays a single file of source code. The display updates itself automatically whenever GDB's current internal source location pointer changes.

The color of the line numbers along the left side of the source display is indicative of whether a breakpoint may be set at a line. Line numbers that are highlighted in green are those on which breakpoints may be set. Clicking the left mouse button within the green area will place a breakpoint on the line, while turning the entire line red to indicate the breakpoint's existence. Clicking the line number again will unset the breakpoint.

To create a special breakpoint (for instance, one that breaks only in a specific task, or a temporary or hardware breakpoint), or to create multiple breakpoints on the same line, hold down the right mouse button while the mouse cursor is over the line at which you wish to set the breakpoint. A pop-up menu should appear; choose "set breakpoint," which will cause a breakpoint creation dialog to appear. If multiple breakpoints exist on a line and the corresponding line number is clicked to remove a breakpoint, a dialog will appear that allows the user to choose which breakpoints to delete.

Launching an editor on the file is accomplished by holding down the right mouse button with the mouse cursor in the source display. Choose the "Invoke Editor" option off the pop-up menu. If the EDITOR environment variable is set, then that editor will be started; otherwise GDBTk will default to starting emacs.

Along the bottom of the window are debugger control buttons, which mostly correspond to gdb commands of the same name.

While the source window is active, keyboard shortcuts for Next, Step, Cont, Finish, Up, Down, and Bottom are available--simply hit the first letter of the command you wish to execute, to invoke that command.

The display of line numbers along the left margin of the source display can be toggled on or off via the `Line Numbers' entry under the `Options' menu. It is also possible to search a displayed source file for a string of text using the `Search for Text' facility, also under the `Options' menu.

It is possible to load and temporarily display a source file other than that pointed to by GDBTk's current source pointer. Under the `Options' menu, select the `Select Source File' item. A `File Selection' dialog should appear. The search for a source file may be restricted in a number of ways.

By default, all source files used to create the executable are shown in the two file lists. The contents of the first list change based on the `Include runtime library' toggle, which specifies whether we take the GNAT runtime library into consideration, and on the `Directory' setting. Note that the directories shown in the `Directory' pop-up list do not necessarily match that of the current directory hierarchy; the listed directories are simply those that were compiled into the executable as debugging information.

The contents of the second file list in the `File Selection' dialog are a subset of the first list, and is modulated by two entry boxes located below the file lists. To restrict the number of files in the `Pruned List', enter a UNIX-style wildcard expression; only those files matching this expression will be displayed. Or, use the `Search for Subprogram' entry to search all source files for a specific subprogram.

When you have found the file you would like to display, either click on the filename (either in the first or second list) then click `Ok', or double-click on the filename. If GDBTk has trouble displaying a given source file, the command-line directory command can be used to add to (or clear) GDBTk's source file search path. Each entry in this search path is prepended to the filename being searched for, in an attempt to find the actual location of that file.

Stacks Window

The Call Stack Window shows a backtrace of the currently running program. Clicking on any item in the list will select its stack frame as the current one. The source display will update to show the source line associated with the currently selected frame. This does not affect the context under which the step or next commands operate, but does affect the finish command.

Register Window

The contents of this window are similar to the output from info registers. The entries in the Options menu allow the user to specify the radix that the data is displayed in, and, via the `Config' item, to select which registers are displayed. Registers that have changed since the last evaluation of the register contents are highlighted in red.

Expressions Window

This is a variable display window with a slight resemblance to that provided by the Data Display Debugger (DDD). This window may be activated either by double-clicking on a highlighted phrase in the source window (which will import that phrase as a new expression), or by calling it up via the Window menu.

There are two buttons along the bottom of the window called `New Expression' and `Refresh'. Pressing `New Expression' allows the user to manually enter an expression to be displayed. `Refresh' will refresh all variables that are on the canvas, regardless of how `Auto Update' is toggled for each expression.

Holding the right mouse button down on the title bar of any data table will cause a menu with extra functions will appear, with the following options:

Similarly, holding the right button down on an entry within the table (if the expression was, for instance, a record type) will pop up another menu, this time with the options:

It is possible to rearrange the tables by using the first mouse button on the titlebars to drag the tables around the canvas. Application of coarsely gridded anchoring can be toggled via the Options menu.

Auto Command Window

Every time GDBTk returns from executing debugee code (such as after a Next command, or when a breakpoint is hit), if the Auto Command window is active, the command entered into it will execute once with the results of that command displayed in the data area of the window.

Breakpoints Window

The Breakpoints Database Window allows you to manipulate any breakpoints that are set in the debuggee. The display area on the left side of the window contains information about a specific breakpoint. This information includes the following:

The right side of the window contains a button row with an associated scrollbar which may be used to choose a breakpoint from whatever is available. Below that, four buttons labelled "Create", "Modify", "Delete", and "Close" are available.

Pressing the Create button will bring up a breakpoint creation dialog where you may specify parameters for creating a new breakpoint. Modify allows you to modify certain properties of the currently displayed breakpoint. Delete will delete the currently displayed breakpoint, and Close will close the Breakpoint window.

Tasking Window

Information regarding currently active Ada tasks can be found in this window.

Displayed information includes an indication of which task is active, the GDB task number, the task number of the task's parent, its priority, its name, and its current state. On supported platforms, clicking on a line in this window will switch the debugger's context (source display, call stack, etc.) to that line's associated task.

Automatic update of the contents of this window may be toggled via the Options menu, and is off by default. The Update button is present only when autoupdate is not active.

Memory Window

A 512-byte section of memory can be displayed in octal, decimal, hexadecimal, or character representations through this window. To choose an adjacent 512-byte block of memory, press the Next and Prev buttons. To enter a new address to observe, press the New button, or use the facility provided by data tables displayed in the Expressions window.


This document was generated on 16 May 2000 using the texi2html translator version 1.51.