Commit | Line | Data |
---|---|---|
6fd934a6 SG |
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. |