gdb/README.GDBTK

   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