gdb/README.GDBTK

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