| 1 | 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 seperate |
| 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 modifiy the |
| 145 | appropriate X resources. The other 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. Ie: |
| 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 for 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 seperated |
| 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: invalide 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 | |