282 lines
10 KiB
Plaintext
282 lines
10 KiB
Plaintext
README.GDBTK for gdb-4.14 release
|
|
Created April 11, 1995 by Stu Grossman
|
|
|
|
This file describes how to build, install, use and hack on GDBtk, a TK based
|
|
GUI for GDB, the GNU debugger.
|
|
|
|
Introduction
|
|
============
|
|
|
|
GDBtk is a version of GDB that uses Tcl/Tk to implement a graphical user inter-
|
|
face. It is a fully integrated GUI, not a seperate front-end program. The
|
|
interface consists of several seperate X windows, which use standard elements
|
|
like buttons, scrollbars, entry boxes and such to create a fairly easy to use
|
|
interface. Each window has a distinct content and purpose, and can be enabled
|
|
or disabled individually. The windows contain things like the current source
|
|
file, a disassembly of the current function, text commands (for things that
|
|
aren't accessible via a button), etc...
|
|
|
|
Building and installing
|
|
=======================
|
|
|
|
Building GDBtk is very straightforward. The main difference is that you will
|
|
need to use the `--enable-gdbtk' option when you run configure in the top level
|
|
directory. You will also need to install Tcl version 7.3 (or 7.4), and Tk 3.6.
|
|
[We haven't ported to Tk 4.0 yet.]
|
|
|
|
You will also need to have X11 (R4/R5/R6) installed (this is a prerequisite to
|
|
installing Tk).
|
|
|
|
[See the GDB README file for more details on configure options and such.]
|
|
|
|
For example:
|
|
|
|
host> cd gdbtk
|
|
host> ./configure --enable-gdbtk
|
|
host> make
|
|
host> make install
|
|
|
|
Using GDBtk
|
|
===========
|
|
|
|
Just run it like you would a normal GDB (in fact, it's actually called `gdb').
|
|
If everything goes well, you should have several windows pop up. To get going,
|
|
hit the start button, and go exploring.
|
|
|
|
If you want to use GDB in command line mode, just use the -nw option. Or, you
|
|
can undefine the DISPLAY environment variable.
|
|
|
|
In the current version, you can have up to 6 windows active at once. They are:
|
|
|
|
1) Command
|
|
2) Source
|
|
3) Disassembly
|
|
4) Register
|
|
5) Auto Command
|
|
6) Expression
|
|
|
|
Most windows have a similar layout consisting of a menubar, display area,
|
|
scrollbar, status box and window-specific buttons.
|
|
|
|
The menubar contains the following items:
|
|
|
|
File - General file control. Also has window close and quit buttons.
|
|
Options - Window specific options.
|
|
Window - A menu of other windows that can be popped up or created.
|
|
Help - Mostly unimplemented.
|
|
|
|
The status box indicates things like the current file and function, or the
|
|
current PC and function depending upon the window.
|
|
|
|
Command window:
|
|
|
|
This can be used to type commands at GDB (useful for when there isn't a
|
|
button for what you want to do).
|
|
|
|
Source window:
|
|
|
|
This contains the current source file. The margin displays line
|
|
numbers, and has an indicator for lines that actually contain code (and
|
|
therefore can have breakpoints as well). When a breakpoint is set at
|
|
that line, the indicator is replaced with a `B'.
|
|
|
|
The buttons are:
|
|
|
|
Start - Put a breakpoint at main, and then run.
|
|
Stop - Stop the program (only active when program is running).
|
|
Step, Next, Cont[inue], Finish, Up, Down - Same as the corresponding
|
|
GDB command. (Finish runs the current subroutine until it's done.)
|
|
Bottom - Does a `frame 0' to put you at the innermost call frame.
|
|
|
|
There are also accelerators for various buttons (just type the letter
|
|
without any control/meta/alt/shift in the text frame):
|
|
|
|
s - Step
|
|
n - Next
|
|
c - Continue
|
|
f - Finish
|
|
u - Up
|
|
d - Down
|
|
|
|
The mouse can also be used to set and clear breakpoints when clicked
|
|
in the margin (on a breakpoint indicator).
|
|
|
|
Disassembly window:
|
|
|
|
This displays a disassembly of the current function. It's buttons are
|
|
similar to those of the source window, except that it uses Stepi and
|
|
Nexti to run one instruction at a time instead of one statement at a
|
|
time. The accelerators and mouse actions are also similar.
|
|
|
|
Additionally, there is an option to enable mixed source and assembly.
|
|
|
|
Register window:
|
|
|
|
This displays the registers. It may have to be resized to properly
|
|
display all the registers. The displayed registers can be selected
|
|
via the Options|Config menu item.
|
|
|
|
Auto Command window:
|
|
|
|
Using this window, you can specify a command to be executed frequently.
|
|
The output will be automatically updated. Options|Accumulate-output
|
|
can be used to avoid clearing the window each time so that you can
|
|
accumulate a history.
|
|
|
|
Expressions:
|
|
|
|
The expression window can be used to just calculate an expression, or
|
|
to watch the value of an expression (ala the `display' command), using
|
|
the Update button. The expression window will also pop up
|
|
automatically when an expression is double-clicked in the source window.
|
|
|
|
Customizing GDBtk
|
|
=================
|
|
|
|
There are three primary ways to customize GDBtk. One is to modifiy the appropriate
|
|
X resources. The other is to hack a ~/.gdbtkinit file. The last is to change
|
|
gdbtk.tcl, which defines the most basic interface elements.
|
|
|
|
X resources give you control over things like the choice of fonts, color
|
|
schemes and some geometry info.
|
|
|
|
For more serious customizations, you will probably need to hack your ~/.gdbtkinit
|
|
or gdbtk.tcl files.
|
|
|
|
X Resources
|
|
===========
|
|
|
|
The class name for GDBtk is `Gdb', and it's appname is `gdb'. The top-
|
|
level windows have instance names of `src', 'asm', 'reg', and 'cmd'. The main
|
|
display area in each has the class `Text'. So, to change the font in all the
|
|
main display areas, something like the following will do:
|
|
|
|
Gdb*Text*font: fixed
|
|
|
|
To change the font in only the source window:
|
|
|
|
Gdb*src*Text*font: fixed
|
|
|
|
To find out the names of the widgets do the following (in the command window):
|
|
|
|
tk info comm .*
|
|
|
|
To get the list of resources (and their classes) for a given widget, do some-
|
|
thing like:
|
|
|
|
tk .asm.text config
|
|
|
|
This will return a list of lists, where each sublist looks something like this:
|
|
|
|
{-height height Height 24 25}
|
|
|
|
The first item is the name of the config option used when creating the widget.
|
|
The second item is the instance name of this resource, the third is the class
|
|
name. The fourth item is the default value, and the last item is the current
|
|
value.
|
|
|
|
To get info about a single resource, add the config option name to the end of
|
|
the previous command. Ie:
|
|
|
|
tk .asm.text config -font
|
|
|
|
will return just the info about the font.
|
|
|
|
To find out the class of a window, just do:
|
|
|
|
tk winfo class .asm.text
|
|
|
|
Note that some things may be explicitly overridden by gdbtk.tcl. In
|
|
particular, the `tk colormodel . monochrome' command should probably be
|
|
disabled if you want to use color.
|
|
|
|
Hacking ~/.gdbtkinit and gdbtk.tcl
|
|
==================================
|
|
~/.gdbtkinit is sourced at the end of gdbtk.tcl. Currently there is no good
|
|
doc on this. See gdbtk.tcl for see what you can change.
|
|
|
|
The GUI is primarily implemented by Tcl/Tk code which lives in gdbtk.tcl and a
|
|
C file called gdbtk.c. The Tcl/Tk code determines the look and feel, the
|
|
layout, and the functions associated with all of the interface elements. The C
|
|
code is mostly just glue between GDB internals and Tclland. In essence, all of
|
|
the policy is implemented in Tcl/Tk, and is easily changed without recompiling.
|
|
|
|
To make more serious changes to the interface, such as adding a new window or
|
|
changing the framework, you will have to hack gdbtk.tcl. This file is
|
|
installed in $(libdir) (probably /usr/local/lib/). But, you will probably want
|
|
to hack on your own private copy before putting it up for the rest of the
|
|
users. GDB actually searches three places for gdbtk.tcl. First, it looks in
|
|
the GDBTK_FILENAME environment variable. Second, it looks for ./gdbtk.tcl.
|
|
And third, it looks for $(libdir)/gdbtk.tcl.
|
|
|
|
Internally, GDBtk is basically GDB, linked with Tcl/Tk, and some glue code that
|
|
interfaces GDB internals to Tclland. This means that GDBtk operates as a
|
|
single program, not a front-end to GDB. All GDB commands, and a great deal of
|
|
the target program state are accessible to the Tcl programmer. In addition,
|
|
there are many callbacks from GDB to notify Tclland of important events.
|
|
|
|
Here is a brief rundown of the GDB<=>Tcl interfaces:
|
|
|
|
Tcl->GDB calls:
|
|
gdb_cmd - sends a text command to gdb. Returns the result
|
|
gdb_loc - takes PC, and returns a list consisting of a short file name,
|
|
the function name, a long file name, the line number and the
|
|
PC (in case you didn't supply it).
|
|
gdb_sourcelines - Takes a filename, and returns a list of lines that
|
|
contain code.
|
|
gdb_listfiles - Returns a list of all of the source files.
|
|
gdb_stop - Stops the target process.
|
|
gdb_regnames - Returns a list of all of the register names.
|
|
gdb_fetch_registers - Returns the contents of the specified registers.
|
|
gdb_changed_register_list - Returns a list of registers that have
|
|
changed since the last call.
|
|
gdb_disassemble - Takes a function or PC. Returns the text of a dis-
|
|
assembly of the entire function.
|
|
gdb_eval - Takes an expression. Returns it's value.
|
|
gdb_get_breakpoint_list - Does the obvious.
|
|
gdb_get_breakpoint_info - Takes a breakpoint number. Returns a list of
|
|
info about that breakpoint.
|
|
|
|
GDB->Tcl callbacks:
|
|
gdb_tcl_fputs - Sends output into Tcl for the command window.
|
|
gdb_tcl_query - Pops up a query window.
|
|
gdbtk_tcl_breakpoint - Notifies Tcl of changes to a breakpoint.
|
|
gdbtk_tcl_idle - Notifies Tcl that debugged process is now idle.
|
|
gdbtk_tcl_busy - Notifies Tcl that debugged process is now running.
|
|
|
|
For details, see the usage in gdbtk.tcl, or the definitions in gdbtk.c.
|
|
|
|
Additionally, there is a new GDB command `tk', which can be used to poke at
|
|
Tk/Tcl from the command window.
|
|
|
|
Problems
|
|
========
|
|
|
|
During building, you may run into problems with finding Tcl, Tk or X11. Look
|
|
in gdb/Makefile, and fix TCL_CFLAGS, TCL, TK_CFLAGS, TK, and ENABLE_CLIBS as
|
|
appropriate.
|
|
|
|
If you one of the following messages when you run gdb:
|
|
|
|
Tcl_Init failed: can't find init.tcl; perhaps you need to
|
|
install Tcl or set your TCL_LIBRARY environment variable?
|
|
or
|
|
Tk_Init failed: can't find tk.tcl; perhaps you need to
|
|
install Tk or set your TK_LIBRARY environment variable?
|
|
|
|
then you haven't installed Tcl or TK properly. Fix the appropriate environment
|
|
variable to point at the {tcl tk}/library directory, and restart gdb.
|
|
|
|
If you get the following:
|
|
|
|
/usr/local/lib/gdbtk.tcl:1: couldn't read file "/usr/local/lib/gdbtk.tcl": No such file or directory
|
|
Stack trace:
|
|
can't unset "auto_index": no such variable
|
|
while executing
|
|
"unset auto_index"
|
|
|
|
then GDBtk wasn't installed properly. You can set the GDBTK_FILENAME
|
|
environment variable to point at the gdbtk.tcl in your source directory. Note
|
|
that the stack trace displayed here is not valid. If you actually get an error
|
|
in gdbtk.tcl, the stack trace is useful to pinpoint the location.
|