1 |
578 |
markom |
README.GDBTK
|
2 |
|
|
Written by Stu Grossman
|
3 |
|
|
Updated 9/26/95 by Fred Fish for gdb 4.15 release
|
4 |
|
|
Updated 4/18/97 by Martin Hunt
|
5 |
|
|
|
6 |
|
|
This file describes how to build, install, use and hack on GDBtk, a TK based
|
7 |
|
|
GUI for GDB, the GNU debugger.
|
8 |
|
|
|
9 |
|
|
Introduction
|
10 |
|
|
============
|
11 |
|
|
|
12 |
|
|
GDBtk is a version of GDB that uses Tcl/Tk to implement a graphical
|
13 |
|
|
user inter-face. It is a fully integrated GUI, not a separate
|
14 |
|
|
front-end program. The interface consists of several separate
|
15 |
|
|
windows, which use standard elements like buttons, scrollbars, entry
|
16 |
|
|
boxes and such to create a fairly easy to use interface. Each window
|
17 |
|
|
has a distinct content and purpose, and can be enabled or disabled
|
18 |
|
|
individually. The windows contain things like the current source
|
19 |
|
|
file, a disassembly of the current function, text commands (for things
|
20 |
|
|
that aren't accessible via a button), and so forth.
|
21 |
|
|
|
22 |
|
|
Building and installing
|
23 |
|
|
=======================
|
24 |
|
|
|
25 |
|
|
Building GDBtk is very straightforward. The main difference is that you will
|
26 |
|
|
need to use the `--enable-gdbtk' option when you run configure in the top level
|
27 |
|
|
directory. You will also need to install Tcl version 7.6 and Tk version 4.2.
|
28 |
|
|
|
29 |
|
|
On Unix machines, you will also need to have X11 (R4/R5/R6) installed
|
30 |
|
|
(this is a prerequisite to installing Tk).
|
31 |
|
|
|
32 |
|
|
For Windows, you can obtain Tcl/Tk from ftp://ftp.smli.com:/pub/tcl/win76p2.exe.
|
33 |
|
|
There is a bug in this version of Tcl/tk that requires you to set the
|
34 |
|
|
environmental variable TK_LIBRARY to where the tk library directory is installed.
|
35 |
|
|
There is also a problem with the colors in images on 16-bit displays under
|
36 |
|
|
Windows, so some icons may look strange.
|
37 |
|
|
|
38 |
|
|
[See the GDB README file for more details on configure options and such.]
|
39 |
|
|
|
40 |
|
|
For example:
|
41 |
|
|
|
42 |
|
|
host> cd gdbtk
|
43 |
|
|
host> ./configure --enable-gdbtk
|
44 |
|
|
host> make
|
45 |
|
|
host> make install
|
46 |
|
|
|
47 |
|
|
Using GDBtk
|
48 |
|
|
===========
|
49 |
|
|
|
50 |
|
|
Just run it like you would a normal GDB (in fact, it's actually called `gdb').
|
51 |
|
|
If everything goes well, you should have several windows pop up. To get going,
|
52 |
|
|
hit the start button, and go exploring.
|
53 |
|
|
|
54 |
|
|
If you want to use GDB in command line mode, just use the -nw option. Or, you
|
55 |
|
|
can undefine the DISPLAY environment variable.
|
56 |
|
|
|
57 |
|
|
In the current version, you can have up to 6 windows active at once. They are:
|
58 |
|
|
|
59 |
|
|
1) Command
|
60 |
|
|
2) Source
|
61 |
|
|
3) Assembly
|
62 |
|
|
4) Register
|
63 |
|
|
5) Auto Command
|
64 |
|
|
6) Expression
|
65 |
|
|
|
66 |
|
|
Most windows have a similar layout consisting of a menubar, display area,
|
67 |
|
|
scrollbar, status box and window-specific buttons.
|
68 |
|
|
|
69 |
|
|
The menubar contains the following items:
|
70 |
|
|
|
71 |
|
|
File - General file control. Also has window close and quit buttons.
|
72 |
|
|
Options - Window specific options.
|
73 |
|
|
Window - A menu of other windows that can be popped up or created.
|
74 |
|
|
Help - Mostly unimplemented.
|
75 |
|
|
|
76 |
|
|
The status box indicates things like the current file and function, or the
|
77 |
|
|
current PC and function depending upon the window.
|
78 |
|
|
|
79 |
|
|
Command window:
|
80 |
|
|
|
81 |
|
|
This can be used to type commands at GDB (useful for when there isn't a
|
82 |
|
|
button for what you want to do).
|
83 |
|
|
|
84 |
|
|
Source window:
|
85 |
|
|
|
86 |
|
|
This contains the current source file. The margin displays line
|
87 |
|
|
numbers, and has an indicator for lines that actually contain code (and
|
88 |
|
|
therefore can have breakpoints as well). When a breakpoint is set at
|
89 |
|
|
that line, the indicator is replaced with a stop sign icon.
|
90 |
|
|
|
91 |
|
|
The buttons are:
|
92 |
|
|
|
93 |
|
|
Start - Put a breakpoint at main, and then run.
|
94 |
|
|
Stop - Stop the program (only active when program is running).
|
95 |
|
|
Step, Next, Cont[inue], Finish, Up, Down - Same as the corresponding
|
96 |
|
|
GDB command. (Finish runs the current subroutine until it's done.)
|
97 |
|
|
Bottom - Does a `frame 0' to put you at the innermost call frame.
|
98 |
|
|
|
99 |
|
|
There are also accelerators for various buttons (just type the letter
|
100 |
|
|
without any control/meta/alt/shift in the text frame):
|
101 |
|
|
|
102 |
|
|
s - Step
|
103 |
|
|
n - Next
|
104 |
|
|
c - Continue
|
105 |
|
|
f - Finish
|
106 |
|
|
u - Up
|
107 |
|
|
d - Down
|
108 |
|
|
|
109 |
|
|
The mouse can also be used to set and clear breakpoints when clicked
|
110 |
|
|
in the margin (on a breakpoint indicator).
|
111 |
|
|
|
112 |
|
|
Assembly window:
|
113 |
|
|
|
114 |
|
|
This displays a disassembly of the current function. It's buttons are
|
115 |
|
|
similar to those of the source window, except that it uses Stepi and
|
116 |
|
|
Nexti to run one instruction at a time instead of one statement at a
|
117 |
|
|
time. The accelerators and mouse actions are also similar.
|
118 |
|
|
|
119 |
|
|
Additionally, there is an option to enable mixed source and assembly.
|
120 |
|
|
|
121 |
|
|
Register window:
|
122 |
|
|
|
123 |
|
|
This displays the registers. It may have to be resized to properly
|
124 |
|
|
display all the registers. The displayed registers can be selected
|
125 |
|
|
via the Options|Config menu item.
|
126 |
|
|
|
127 |
|
|
Auto Command window:
|
128 |
|
|
|
129 |
|
|
Using this window, you can specify a command to be executed frequently.
|
130 |
|
|
The output will be automatically updated. Options|Accumulate-output
|
131 |
|
|
can be used to avoid clearing the window each time so that you can
|
132 |
|
|
accumulate a history.
|
133 |
|
|
|
134 |
|
|
Expressions:
|
135 |
|
|
|
136 |
|
|
The expression window can be used to just calculate an expression, or
|
137 |
|
|
to watch the value of an expression (ala the `display' command), using
|
138 |
|
|
the Update button. The expression window will also pop up
|
139 |
|
|
automatically when an expression is double-clicked in the source window.
|
140 |
|
|
|
141 |
|
|
Customizing GDBtk
|
142 |
|
|
=================
|
143 |
|
|
|
144 |
|
|
There are three primary ways to customize GDBtk. One is to modify the
|
145 |
|
|
appropriate X resources. Another is to hack a ~/.gdbtkinit file. The last
|
146 |
|
|
is to change the files in gdbtcl, which defines the most basic interface
|
147 |
|
|
elements.
|
148 |
|
|
|
149 |
|
|
X resources give you control over things like the choice of fonts, color
|
150 |
|
|
schemes and some geometry info.
|
151 |
|
|
|
152 |
|
|
For more serious customizations, you will probably need to hack your
|
153 |
|
|
~/.gdbtkinit or gdbtcl files.
|
154 |
|
|
|
155 |
|
|
X Resources
|
156 |
|
|
===========
|
157 |
|
|
|
158 |
|
|
The class name for GDBtk is `Gdb', and it's appname is `gdb'. The top-
|
159 |
|
|
level windows have instance names of `src', 'asm', 'reg', and 'cmd'. The main
|
160 |
|
|
display area in each has the class `Text'. So, to change the font in all the
|
161 |
|
|
main display areas, something like the following will do:
|
162 |
|
|
|
163 |
|
|
Gdb*Text*font: fixed
|
164 |
|
|
|
165 |
|
|
To change the font in only the source window:
|
166 |
|
|
|
167 |
|
|
Gdb*src*Text*font: fixed
|
168 |
|
|
|
169 |
|
|
To find out the names of the widgets do the following (in the command window):
|
170 |
|
|
|
171 |
|
|
tk info comm .*
|
172 |
|
|
|
173 |
|
|
To get the list of resources (and their classes) for a given widget, do some-
|
174 |
|
|
thing like:
|
175 |
|
|
|
176 |
|
|
tk .asm.text config
|
177 |
|
|
|
178 |
|
|
This will return a list of lists, where each sublist looks something like this:
|
179 |
|
|
|
180 |
|
|
{-height height Height 24 25}
|
181 |
|
|
|
182 |
|
|
The first item is the name of the config option used when creating the widget.
|
183 |
|
|
The second item is the instance name of this resource, the third is the class
|
184 |
|
|
name. The fourth item is the default value, and the last item is the current
|
185 |
|
|
value.
|
186 |
|
|
|
187 |
|
|
To get info about a single resource, add the config option name to the end of
|
188 |
|
|
the previous command. I.e.:
|
189 |
|
|
|
190 |
|
|
tk .asm.text config -font
|
191 |
|
|
|
192 |
|
|
will return just the info about the font.
|
193 |
|
|
|
194 |
|
|
To find out the class of a window, just do:
|
195 |
|
|
|
196 |
|
|
tk winfo class .asm.text
|
197 |
|
|
|
198 |
|
|
Note that some things may be explicitly overridden by gdbtk.tcl. In
|
199 |
|
|
particular, the `tk colormodel . monochrome' command should probably be
|
200 |
|
|
disabled if you want to use color.
|
201 |
|
|
|
202 |
|
|
Hacking ~/.gdbtkinit and gdbtcl
|
203 |
|
|
===============================
|
204 |
|
|
~/.gdbtkinit is sourced at the end of gdbtk.tcl. Currently there is no good
|
205 |
|
|
doc on this. See gdbtcl/main.tcl to see what you can change.
|
206 |
|
|
|
207 |
|
|
The GUI is primarily implemented by Tcl/Tk code which lives in gdbtcl and a
|
208 |
|
|
C file called gdbtk.c. The Tcl/Tk code determines the look and feel, the
|
209 |
|
|
layout, and the functions associated with all of the interface elements. The C
|
210 |
|
|
code is mostly just glue between GDB internals and Tclland. In essence, all of
|
211 |
|
|
the policy is implemented in Tcl/Tk, and is easily changed without recompiling.
|
212 |
|
|
|
213 |
|
|
To make more serious changes to the interface, such as adding a new window or
|
214 |
|
|
changing the framework, you will have to hack the tcl code. This directory is
|
215 |
|
|
installed in $(libdir) (probably /usr/local/lib/). But, you will probably want
|
216 |
|
|
to hack on your own private copy before putting it up for the rest of the
|
217 |
|
|
users. To find the GDB tcl code, GDB first checks for the environment variable
|
218 |
|
|
GDBTK_LIBRARY. This can be a directory name or a list of directories separated
|
219 |
|
|
by colons (semicolons on Windows). GDB will check each directory in order until
|
220 |
|
|
it finds "main.tcl". If GDBTK_LIBRARY is not set, GDB will look for
|
221 |
|
|
"gdbtcl/main.tcl" in the current directory, and finally, it will try to find
|
222 |
|
|
the tcl directory in the sources.
|
223 |
|
|
|
224 |
|
|
Note that the old GDBTK_FILENAME environment variable is no longer used.
|
225 |
|
|
|
226 |
|
|
Internally, GDBtk is basically GDB, linked with Tcl/Tk, and some glue code that
|
227 |
|
|
interfaces GDB internals to Tclland. This means that GDBtk operates as a
|
228 |
|
|
single program, not a front-end to GDB. All GDB commands, and a great deal of
|
229 |
|
|
the target program state are accessible to the Tcl programmer. In addition,
|
230 |
|
|
there are many callbacks from GDB to notify Tclland of important events.
|
231 |
|
|
|
232 |
|
|
Here is a brief rundown of the GDB<=>Tcl interfaces:
|
233 |
|
|
|
234 |
|
|
Tcl->GDB calls:
|
235 |
|
|
gdb_cmd - sends a text command to gdb. Returns the result
|
236 |
|
|
gdb_loc - takes PC, and returns a list consisting of a short file name,
|
237 |
|
|
the function name, a long file name, the line number and the
|
238 |
|
|
PC (in case you didn't supply it).
|
239 |
|
|
gdb_sourcelines - Takes a filename, and returns a list of lines that
|
240 |
|
|
contain code.
|
241 |
|
|
gdb_listfiles - Returns a list of all of the source files.
|
242 |
|
|
gdb_stop - Stops the target process.
|
243 |
|
|
gdb_regnames - Returns a list of all of the register names.
|
244 |
|
|
gdb_fetch_registers - Returns the contents of the specified registers.
|
245 |
|
|
gdb_changed_register_list - Returns a list of registers that have
|
246 |
|
|
changed since the last call.
|
247 |
|
|
gdb_disassemble - Takes a function or PC. Returns the text of a dis-
|
248 |
|
|
assembly of the entire function.
|
249 |
|
|
gdb_eval - Takes an expression. Returns it's value.
|
250 |
|
|
gdb_get_breakpoint_list - Does the obvious.
|
251 |
|
|
gdb_get_breakpoint_info - Takes a breakpoint number. Returns a list of
|
252 |
|
|
info about that breakpoint.
|
253 |
|
|
|
254 |
|
|
GDB->Tcl callbacks:
|
255 |
|
|
gdb_tcl_fputs - Sends output into Tcl for the command window.
|
256 |
|
|
gdb_tcl_query - Pops up a query window.
|
257 |
|
|
gdbtk_tcl_breakpoint - Notifies Tcl of changes to a breakpoint.
|
258 |
|
|
gdbtk_tcl_idle - Notifies Tcl that debugged process is now idle.
|
259 |
|
|
gdbtk_tcl_busy - Notifies Tcl that debugged process is now running.
|
260 |
|
|
|
261 |
|
|
For details, see the usage in gdbtk.tcl, or the definitions in gdbtk.c.
|
262 |
|
|
|
263 |
|
|
Additionally, there is a new GDB command `tk', which can be used to poke at
|
264 |
|
|
Tk/Tcl from the command window.
|
265 |
|
|
|
266 |
|
|
Problems
|
267 |
|
|
========
|
268 |
|
|
|
269 |
|
|
During building, you may run into problems with finding Tcl, Tk or X11. Look
|
270 |
|
|
in gdb/Makefile, and fix TCL_CFLAGS, TCL, TK_CFLAGS, TK, and ENABLE_CLIBS as
|
271 |
|
|
appropriate.
|
272 |
|
|
|
273 |
|
|
If you one of the following messages when you run gdb:
|
274 |
|
|
|
275 |
|
|
Tcl_Init failed: can't find init.tcl; perhaps you need to
|
276 |
|
|
install Tcl or set your TCL_LIBRARY environment variable?
|
277 |
|
|
or
|
278 |
|
|
Tk_Init failed: can't find tk.tcl; perhaps you need to
|
279 |
|
|
install Tk or set your TK_LIBRARY environment variable?
|
280 |
|
|
|
281 |
|
|
then you haven't installed Tcl or TK properly. Fix the appropriate environment
|
282 |
|
|
variable to point at the {tcl tk}/library directory, and restart gdb.
|
283 |
|
|
|
284 |
|
|
If you get the following:
|
285 |
|
|
|
286 |
|
|
/usr/local/lib/gdbtk.tcl:1: couldn't read file "/usr/local/lib/gdbtk.tcl": No such file or directory
|
287 |
|
|
Stack trace:
|
288 |
|
|
can't unset "auto_index": no such variable
|
289 |
|
|
while executing
|
290 |
|
|
"unset auto_index"
|
291 |
|
|
|
292 |
|
|
then GDBtk wasn't installed properly. You can set the GDBTK_FILENAME
|
293 |
|
|
environment variable to point at the gdbtk.tcl in your source directory. Note
|
294 |
|
|
that the stack trace displayed here is not valid. If you actually get an error
|
295 |
|
|
in gdbtk.tcl, the stack trace is useful to pinpoint the location.
|
296 |
|
|
|
297 |
|
|
Known Bugs
|
298 |
|
|
==========
|
299 |
|
|
|
300 |
|
|
generic problems
|
301 |
|
|
|
302 |
|
|
o If you open an Assembly window before you have run the program, gdbtk
|
303 |
|
|
pops up a dialog box titled "Error in Tcl Script" with the contents
|
304 |
|
|
"Error: No function contains the specified address". Trying to then
|
305 |
|
|
do other things brings up a dialog box with the contents "Error:
|
306 |
|
|
can't read 'current_asm_label': no such variable.
|
307 |
|
|
|
308 |
|
|
Solution: Close Assembly window when there is no program running.
|
309 |
|
|
|
310 |
|
|
o If you open Registers window before you have run the program, gdbtk
|
311 |
|
|
pops up a dialog box titled "Error in Tcl Script" with the contents
|
312 |
|
|
"Error: No registers". Trying to then do other things, like use the
|
313 |
|
|
Start button to run the program, repeatedly produce the same dialog
|
314 |
|
|
box and the action is not performed.
|
315 |
|
|
|
316 |
|
|
Solution: Close Registers window when there is no program running.
|
317 |
|
|
|
318 |
|
|
o Expressions are sometimes not displayed correctly in the Expression
|
319 |
|
|
window. I.E. "argc" works, as does "*(argv+argc)" but not "argv[argc]".
|
320 |
|
|
|
321 |
|
|
Solution: None
|
322 |
|
|
[ I believe this problem is fixed, but I have not tested it ]
|
323 |
|
|
|
324 |
|
|
o The Breakpoint window does not get automatically updated and changes
|
325 |
|
|
made in the window are not reflected back in the results from "info br".
|
326 |
|
|
I.E. the breakpoint count in the window is not updated at each hit and
|
327 |
|
|
enabling/disabling the breakpoint from the Breakpoint window has no effect.
|
328 |
|
|
|
329 |
|
|
Solution: Use the command interface to control breakpoints and don't
|
330 |
|
|
open a Breakpoint window.
|
331 |
|
|
|
332 |
|
|
o Sometimes while an expression window is active you get a dialog box
|
333 |
|
|
that complains "Error: invalid command name ".expr.e5.expr" for
|
334 |
|
|
example. The Tcl stack trace looks something like:
|
335 |
|
|
|
336 |
|
|
invalid command name ".expr.e5.expr"
|
337 |
|
|
while executing
|
338 |
|
|
"$e.expr get 0.0 end"
|
339 |
|
|
invoked from within
|
340 |
|
|
"set expr [$e.expr get 0.0 end]..."
|
341 |
|
|
(procedure "update_expr" line 17)
|
342 |
|
|
invoked from within
|
343 |
|
|
"update_expr $expr_num"
|
344 |
|
|
invoked from within
|
345 |
|
|
"if $expr_update_list($expr_num) {
|
346 |
|
|
update_expr $expr_num
|
347 |
|
|
.
|
348 |
|
|
.
|
349 |
|
|
.
|
350 |
|
|
|
351 |
|
|
Solution: None except close expression window and reopen it.
|
352 |
|
|
|
353 |
|
|
o If you select the "Down" button in either the Source or Assembly
|
354 |
|
|
window while in the bottom (innermost) frame, the error message that
|
355 |
|
|
results goes just to the command window and may be missed if the
|
356 |
|
|
command window is not open. This may also apply to other messages
|
357 |
|
|
as well. It should probably put up a notification box instead.
|
358 |
|
|
|
359 |
|
|
Solution: Keep Command window open to see error messages.
|
360 |
|
|
|
361 |
|
|
o Not really a problem, but it would be nice to have a backtrace
|
362 |
|
|
window.
|
363 |
|
|
|
364 |
|
|
Solution: Do bt in command window?
|
365 |
|
|
|
366 |
|
|
o Also not really a problem, but it might be nice to have a frame/stack
|
367 |
|
|
window that displays the last N words on the stack, along with
|
368 |
|
|
indications about which function owns a particular frame, how the
|
369 |
|
|
frame pointers are chained, and possibly the names of variables
|
370 |
|
|
alongside their frame slots.
|
371 |
|
|
|
372 |
|
|
m68k-hp-hpux9.00:
|
373 |
|
|
|
374 |
|
|
o Attempting to use a Register window results in a Tcl Script Error
|
375 |
|
|
"Error: Erroneous arithmetic operation". The Tcl stack trace is:
|
376 |
|
|
|
377 |
|
|
while executing
|
378 |
|
|
"gdb_fetch_registers $reg_format $regnum"
|
379 |
|
|
invoked from within
|
380 |
|
|
"set regval [gdb_fetch_registers $reg_format $regnum]..."
|
381 |
|
|
("foreach" body line 2)
|
382 |
|
|
invoked from within
|
383 |
|
|
"foreach regnum $reg_display_list {
|
384 |
|
|
set regval [gdb_fetch_registers $reg_format $regnum]
|
385 |
|
|
set regval [format "%-*s" $valwidth $regval]
|
386 |
|
|
$win del ..."
|
387 |
|
|
invoked from within
|
388 |
|
|
"if {$which == "all"} {
|
389 |
|
|
set lineindex 1
|
390 |
|
|
foreach regnum $reg_display_list {
|
391 |
|
|
set regval [gdb_fetch_registers $reg_format $regnum]
|
392 |
|
|
set regval [f ..."
|
393 |
|
|
(procedure "update_registers" line 16)
|
394 |
|
|
invoked from within
|
395 |
|
|
"update_registers all"
|
396 |
|
|
.
|
397 |
|
|
.
|
398 |
|
|
.
|
399 |
|
|
|
400 |
|
|
|