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