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.3 (or 7.4), and Tk 3.6.
  27 [We haven't ported to Tk 4.0 yet.]
  28
  29 You will also need to have X11 (R4/R5/R6) installed (this is a prerequisite to
  30 installing Tk).
  31
  32 [See the GDB README file for more details on configure options and such.]
  33
  34 For example:
  35
  36         host> cd gdbtk
  37         host> ./configure --enable-gdbtk
  38         host> make
  39         host> make install
  40
  41 Using GDBtk
  42 ===========
  43
  44 Just run it like you would a normal GDB (in fact, it's actually called `gdb').
  45 If everything goes well, you should have several windows pop up.  To get going,
  46 hit the start button, and go exploring.
  47
  48 If you want to use GDB in command line mode, just use the -nw option.  Or, you
  49 can undefine the DISPLAY environment variable.
  50
  51 In the current version, you can have up to 6 windows active at once.  They are:
  52
  53         1) Command
  54         2) Source
  55         3) Assembly
  56         4) Register
  57         5) Auto Command
  58         6) Expression
  59
  60 Most windows have a similar layout consisting of a menubar, display area,
  61 scrollbar, status box and window-specific buttons.
  62
  63 The menubar contains the following items:
  64
  65         File    - General file control.  Also has window close and quit buttons.
  66         Options - Window specific options.
  67         Window  - A menu of other windows that can be popped up or created.
  68         Help    - Mostly unimplemented.
  69
  70 The status box indicates things like the current file and function, or the
  71 current PC and function depending upon the window.
  72
  73 Command window:
  74
  75         This can be used to type commands at GDB (useful for when there isn't a
  76         button for what you want to do).
  77
  78 Source window:
  79
  80         This contains the current source file.  The margin displays line
  81         numbers, and has an indicator for lines that actually contain code (and
  82         therefore can have breakpoints as well).  When a breakpoint is set at
  83         that line, the indicator is replaced with a `B'.
  84
  85         The buttons are:
  86
  87         Start - Put a breakpoint at main, and then run.
  88         Stop - Stop the program (only active when program is running).
  89         Step, Next, Cont[inue], Finish, Up, Down - Same as the corresponding
  90               GDB command.  (Finish runs the current subroutine until it's done.)
  91         Bottom - Does a `frame 0' to put you at the innermost call frame.
  92
  93         There are also accelerators for various buttons (just type the letter
  94         without any control/meta/alt/shift in the text frame):
  95
  96         s - Step
  97         n - Next
  98         c - Continue
  99         f - Finish
 100         u - Up
 101         d - Down
 102
 103         The mouse can also be used to set and clear breakpoints when clicked
 104         in the margin (on a breakpoint indicator).
 105
 106 Assembly window:
 107
 108         This displays a disassembly of the current function.  It's buttons are
 109         similar to those of the source window, except that it uses Stepi and
 110         Nexti to run one instruction at a time instead of one statement at a
 111         time.  The accelerators and mouse actions are also similar.
 112
 113         Additionally, there is an option to enable mixed source and assembly.
 114
 115 Register window:
 116
 117         This displays the registers.  It may have to be resized to properly
 118         display all the registers.  The displayed registers can be selected
 119         via the Options|Config menu item.
 120
 121 Auto Command window:
 122
 123         Using this window, you can specify a command to be executed frequently.
 124         The output will be automatically updated.  Options|Accumulate-output
 125         can be used to avoid clearing the window each time so that you can
 126         accumulate a history.
 127
 128 Expressions:
 129
 130         The expression window can be used to just calculate an expression, or
 131         to watch the value of an expression (ala the `display' command), using
 132         the Update button.  The expression window will also pop up
 133         automatically when an expression is double-clicked in the source window.
 134
 135 Customizing GDBtk
 136 =================
 137
 138 There are three primary ways to customize GDBtk.  One is to modifiy the appropriate
 139 X resources.  The other is to hack a ~/.gdbtkinit file.  The last is to change
 140 gdbtk.tcl, which defines the most basic interface elements.
 141
 142 X resources give you control over things like the choice of fonts, color
 143 schemes and some geometry info.
 144
 145 For more serious customizations, you will probably need to hack your ~/.gdbtkinit
 146 or gdbtk.tcl files.
 147
 148 X Resources
 149 ===========
 150
 151         The class name for GDBtk is `Gdb', and it's appname is `gdb'.  The top-
 152 level windows have instance names of `src', 'asm', 'reg', and 'cmd'.  The main
 153 display area in each has the class `Text'.  So, to change the font in all the
 154 main display areas, something like the following will do:
 155
 156         Gdb*Text*font:          fixed
 157
 158 To change the font in only the source window:
 159
 160         Gdb*src*Text*font:              fixed
 161
 162 To find out the names of the widgets do the following (in the command window):
 163
 164         tk info comm .*
 165
 166 To get the list of resources (and their classes) for a given widget, do some-
 167 thing like:
 168
 169         tk .asm.text config
 170
 171 This will return a list of lists, where each sublist looks something like this:
 172
 173         {-height height Height 24 25}
 174
 175 The first item is the name of the config option used when creating the widget.
 176 The second item is the instance name of this resource, the third is the class
 177 name.  The fourth item is the default value, and the last item is the current
 178 value.
 179
 180 To get info about a single resource, add the config option name to the end of
 181 the previous command.  Ie:
 182
 183         tk .asm.text config -font
 184
 185 will return just the info about the font.
 186
 187 To find out the class of a window, just do:
 188
 189         tk winfo class .asm.text
 190
 191 Note that some things may be explicitly overridden by gdbtk.tcl.  In
 192 particular, the `tk colormodel . monochrome' command should probably be
 193 disabled if you want to use color.
 194
 195 Hacking ~/.gdbtkinit and gdbtk.tcl
 196 ==================================
 197 ~/.gdbtkinit is sourced at the end of gdbtk.tcl.  Currently there is no good
 198 doc on this.  See gdbtk.tcl for see what you can change.
 199
 200 The GUI is primarily implemented by Tcl/Tk code which lives in gdbtk.tcl and a
 201 C file called gdbtk.c.  The Tcl/Tk code determines the look and feel, the
 202 layout, and the functions associated with all of the interface elements.  The C
 203 code is mostly just glue between GDB internals and Tclland.  In essence, all of
 204 the policy is implemented in Tcl/Tk, and is easily changed without recompiling.
 205
 206 To make more serious changes to the interface, such as adding a new window or
 207 changing the framework, you will have to hack gdbtk.tcl.  This file is
 208 installed in $(libdir) (probably /usr/local/lib/).  But, you will probably want
 209 to hack on your own private copy before putting it up for the rest of the
 210 users.  GDB actually searches three places for gdbtk.tcl.  First, it looks in
 211 the GDBTK_FILENAME environment variable.  Second, it looks for ./gdbtk.tcl.
 212 And third, it looks for $(libdir)/gdbtk.tcl.
 213
 214 Internally, GDBtk is basically GDB, linked with Tcl/Tk, and some glue code that
 215 interfaces GDB internals to Tclland.  This means that GDBtk operates as a
 216 single program, not a front-end to GDB.  All GDB commands, and a great deal of
 217 the target program state are accessible to the Tcl programmer.  In addition,
 218 there are many callbacks from GDB to notify Tclland of important events.
 219
 220 Here is a brief rundown of the GDB<=>Tcl interfaces:
 221
 222 Tcl->GDB calls:
 223         gdb_cmd - sends a text command to gdb.  Returns the result
 224         gdb_loc - takes PC, and returns a list consisting of a short file name,
 225                   the function name, a long file name, the line number and the
 226                   PC (in case you didn't supply it).
 227         gdb_sourcelines - Takes a filename, and returns a list of lines that
 228                   contain code.
 229         gdb_listfiles - Returns a list of all of the source files.
 230         gdb_stop - Stops the target process.
 231         gdb_regnames - Returns a list of all of the register names.
 232         gdb_fetch_registers - Returns the contents of the specified registers.
 233         gdb_changed_register_list - Returns a list of registers that have
 234                   changed since the last call.
 235         gdb_disassemble - Takes a function or PC.  Returns the text of a dis-
 236                   assembly of the entire function.
 237         gdb_eval - Takes an expression.  Returns it's value.
 238         gdb_get_breakpoint_list - Does the obvious.
 239         gdb_get_breakpoint_info - Takes a breakpoint number.  Returns a list of
 240                   info about that breakpoint.
 241
 242 GDB->Tcl callbacks:
 243         gdb_tcl_fputs - Sends output into Tcl for the command window.
 244         gdb_tcl_query - Pops up a query window.
 245         gdbtk_tcl_breakpoint - Notifies Tcl of changes to a breakpoint.
 246         gdbtk_tcl_idle - Notifies Tcl that debugged process is now idle.
 247         gdbtk_tcl_busy - Notifies Tcl that debugged process is now running.
 248
 249 For details, see the usage in gdbtk.tcl, or the definitions in gdbtk.c.
 250
 251 Additionally, there is a new GDB command `tk', which can be used to poke at
 252 Tk/Tcl from the command window.
 253
 254 Problems
 255 ========
 256
 257 During building, you may run into problems with finding Tcl, Tk or X11.  Look
 258 in gdb/Makefile, and fix TCL_CFLAGS, TCL, TK_CFLAGS, TK, and ENABLE_CLIBS as
 259 appropriate.
 260
 261 If you one of the following messages when you run gdb:
 262
 263         Tcl_Init failed: can't find init.tcl; perhaps you need to
 264         install Tcl or set your TCL_LIBRARY environment variable?
 265 or
 266         Tk_Init failed: can't find tk.tcl; perhaps you need to
 267         install Tk or set your TK_LIBRARY environment variable?
 268
 269 then you haven't installed Tcl or TK properly.  Fix the appropriate environment
 270 variable to point at the {tcl tk}/library directory, and restart gdb.
 271
 272 If you get the following:
 273
 274         /usr/local/lib/gdbtk.tcl:1: couldn't read file "/usr/local/lib/gdbtk.tcl": No such file or directory
 275         Stack trace:
 276         can't unset "auto_index": no such variable
 277             while executing
 278         "unset auto_index"
 279
 280 then GDBtk wasn't installed properly.  You can set the GDBTK_FILENAME
 281 environment variable to point at the gdbtk.tcl in your source directory.  Note
 282 that the stack trace displayed here is not valid.  If you actually get an error
 283 in gdbtk.tcl, the stack trace is useful to pinpoint the location.
 284
 285 Known Bugs
 286 ==========
 287
 288 generic problems
 289
 290     o   If you open an Assembly window before you have run the program, gdbtk
 291         pops up a dialog box titled "Error in Tcl Script" with the contents
 292         "Error: No function contains the specified address".  Trying to then
 293         do other things brings up a dialog box with the contents "Error:
 294         can't read 'current_asm_label': no such variable.
 295
 296         Solution:  Close Assembly window when there is no program running.
 297
 298     o   If you open Registers window before you have run the program, gdbtk
 299         pops up a dialog box titled "Error in Tcl Script" with the contents
 300         "Error: No registers".  Trying to then do other things, like use the
 301         Start button to run the program, repeatedly produce the same dialog
 302         box and the action is not performed.
 303
 304         Solution:  Close Registers window when there is no program running.
 305
 306     o   Expressions are sometimes not displayed correctly in the Expression
 307         window.  I.E. "argc" works, as does "*(argv+argc)" but not "argv[argc]".
 308
 309         Solution:  None
 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