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