═══ 1. Title page ═══ Using the Graphical Interface to The GNU Source-Level Debugger () Edition 4.13.3, for version May 19 by Albert K. Lee based on original by Stanley T. Shebs 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. ═══ 2. Top node: "Using GDBTk, the Graphical Interface to " ═══ ═══ 3. 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:  Your terminal must be running an X server.  The DISPLAY environment variable must be set correctly.  The -nw (``no-window'') option was not specified on the GDBTk command line. 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. ═══ 4. Getting Acquainted ═══ ═══ 4.1. 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. ═══ 4.1.1. File Menu ═══ The standard file menu provides operations that affect the overall state of GDB.  File: Lets you set the combined executable and symbol file that GDB will use. (Like the command `file'.)  Target: Brings up a dialog that you can use to connect GDB to a target program. The dialog is described in more depth later. (Like `target'.)  Edit: Starts up an editor to modify the source file being displayed.  Exec File: Lets you set the executable file that GDB will use. (Like `exec-file'.)  Symbol File: Lets you set the symbol file that GDB will use. (Like `symbol-file'.)  Add Symbol File: Lets you add additional symbol files. (Like `add-symbol-file'.)  Core File: Lets you set the core file that GDB will use. (Like `core-file'.)  Close: Closes the current window.  Quit: quits GDB. (Like `quit'.) ═══ 4.1.2. 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. ═══ 4.1.3. 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. ═══ 4.2. Windows ═══ ═══ 4.2.1. 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. ═══ 4.2.2. 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.  Run -- Causes the debugee to execute from the beginning.  Start -- Sets a temporary breakpoint on the Ada main procedure, then runs the program from the beginning. This is the same as the `begin' command.  Next -- Single step, step over subprogram calls.  Step -- Single step, step into subprogram calls.  Cont -- Continue normal execution.  Finish -- Break on exit of current stack frame.  Up -- Traverse one step to the caller's stack frame.  Down -- Traverse one step to the callee's stack frame.  Bottom -- Return to frame 0.  Stop -- Send a SIGINT to the debugging engine. 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. ═══ 4.2.3. 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. ═══ 4.2.4. 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. ═══ 4.2.5. 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:  Auto Update -- Toggle whether the display follows the current value of this variable.  Dereference -- Create a new expression based on a dereferencing of the expression.  Memory Display -- Examine this variable using the Memory Display window.  Delete Expression -- Discard this table. 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:  New Expression -- Create a new table using this item as the expression.  Set Value -- change the value of this item 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. ═══ 4.2.6. 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. ═══ 4.2.7. 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:  GDB's internal breakpoint ID number  The breakpoint's location (file/line pair)  The breakpoint's address  Whether the breakpoint is currently enabled or disabled  What to do when the breakpoint is hit  The number of times the breakpoint has been hit  The number of times the breakpoint should be ignored  The conditions under which this breakpoint will actually break  Whether this breakpoint is active only while in a specific task/thread  Any commands that are to be executed when the breakpoint is hit 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. ═══ 4.2.8. 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. ═══ 4.2.9. 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.