OS/2 Shareware BBS: 10 Tools/10-Tools.zip/adav313.zip/gnat-3_13p-docs.zip/gdbtk.INF

OS/2 Help File | 2001-09-16 | 15KB | 343 lines

ΓòÉΓòÉΓòÉ 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.