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
   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