diff options
| -rw-r--r-- | gdb/ChangeLog | 6 | ||||
| -rw-r--r-- | gdb/README.GDBTK | 281 |
2 files changed, 287 insertions, 0 deletions
diff --git a/gdb/ChangeLog b/gdb/ChangeLog index 8e2c1b0..93b116f 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -1,3 +1,9 @@ +start-sanitize-gdbtk +Fri Apr 14 10:18:20 1995 Stu Grossman (grossman@cygnus.com) + + * README.GDBTK: New file. Contains the obvious. + +end-sanitize-gdbtk Thu Apr 13 16:17:04 1995 Rob Savoye <rob@darkstar.cygnus.com> * remote-array.c: New file for Array Tech LSI33k based controller diff --git a/gdb/README.GDBTK b/gdb/README.GDBTK new file mode 100644 index 0000000..9df59ea --- /dev/null +++ b/gdb/README.GDBTK @@ -0,0 +1,281 @@ + README.GDBTK for gdb-4.14 release + Created April 11, 1995 by Stu Grossman + +This file describes how to build, install, use and hack on GDBtk, a TK based +GUI for GDB, the GNU debugger. + +Introduction +============ + +GDBtk is a version of GDB that uses Tcl/Tk to implement a graphical user inter- +face. It is a fully integrated GUI, not a seperate front-end program. The +interface consists of several seperate X windows, which use standard elements +like buttons, scrollbars, entry boxes and such to create a fairly easy to use +interface. Each window has a distinct content and purpose, and can be enabled +or disabled individually. The windows contain things like the current source +file, a disassembly of the current function, text commands (for things that +aren't accessible via a button), etc... + +Building and installing +======================= + +Building GDBtk is very straightforward. The main difference is that you will +need to use the `--enable-gdbtk' option when you run configure in the top level +directory. You will also need to install Tcl version 7.3 (or 7.4), and Tk 3.6. +[We haven't ported to Tk 4.0 yet.] + +You will also need to have X11 (R4/R5/R6) installed (this is a prerequisite to +installing Tk). + +[See the GDB README file for more details on configure options and such.] + +For example: + + host> cd gdbtk + host> ./configure --enable-gdbtk + host> make + host> make install + +Using GDBtk +=========== + +Just run it like you would a normal GDB (in fact, it's actually called `gdb'). +If everything goes well, you should have several windows pop up. To get going, +hit the start button, and go exploring. + +If you want to use GDB in command line mode, just use the -nw option. Or, you +can undefine the DISPLAY environment variable. + +In the current version, you can have up to 6 windows active at once. They are: + + 1) Command + 2) Source + 3) Disassembly + 4) Register + 5) Auto Command + 6) Expression + +Most windows have a similar layout consisting of a menubar, display area, +scrollbar, status box and window-specific buttons. + +The menubar contains the following items: + + File - General file control. Also has window close and quit buttons. + Options - Window specific options. + Window - A menu of other windows that can be popped up or created. + Help - Mostly unimplemented. + +The status box indicates things like the current file and function, or the +current PC and function depending upon the window. + +Command window: + + This can be used to type commands at GDB (useful for when there isn't a + button for what you want to do). + +Source window: + + This contains the current source file. The margin displays line + numbers, and has an indicator for lines that actually contain code (and + therefore can have breakpoints as well). When a breakpoint is set at + that line, the indicator is replaced with a `B'. + + The buttons are: + + Start - Put a breakpoint at main, and then run. + Stop - Stop the program (only active when program is running). + Step, Next, Cont[inue], Finish, Up, Down - Same as the corresponding + GDB command. (Finish runs the current subroutine until it's done.) + Bottom - Does a `frame 0' to put you at the innermost call frame. + + There are also accelerators for various buttons (just type the letter + without any control/meta/alt/shift in the text frame): + + s - Step + n - Next + c - Continue + f - Finish + u - Up + d - Down + + The mouse can also be used to set and clear breakpoints when clicked + in the margin (on a breakpoint indicator). + +Disassembly window: + + This displays a disassembly of the current function. It's buttons are + similar to those of the source window, except that it uses Stepi and + Nexti to run one instruction at a time instead of one statement at a + time. The accelerators and mouse actions are also similar. + + Additionally, there is an option to enable mixed source and assembly. + +Register window: + + This displays the registers. It may have to be resized to properly + display all the registers. The displayed registers can be selected + via the Options|Config menu item. + +Auto Command window: + + Using this window, you can specify a command to be executed frequently. + The output will be automatically updated. Options|Accumulate-output + can be used to avoid clearing the window each time so that you can + accumulate a history. + +Expressions: + + The expression window can be used to just calculate an expression, or + to watch the value of an expression (ala the `display' command), using + the Update button. The expression window will also pop up + automatically when an expression is double-clicked in the source window. + +Customizing GDBtk +================= + +There are three primary ways to customize GDBtk. One is to modifiy the appropriate +X resources. The other is to hack a ~/.gdbtkinit file. The last is to change +gdbtk.tcl, which defines the most basic interface elements. + +X resources give you control over things like the choice of fonts, color +schemes and some geometry info. + +For more serious customizations, you will probably need to hack your ~/.gdbtkinit +or gdbtk.tcl files. + +X Resources +=========== + + The class name for GDBtk is `Gdb', and it's appname is `gdb'. The top- +level windows have instance names of `src', 'asm', 'reg', and 'cmd'. The main +display area in each has the class `Text'. So, to change the font in all the +main display areas, something like the following will do: + + Gdb*Text*font: fixed + +To change the font in only the source window: + + Gdb*src*Text*font: fixed + +To find out the names of the widgets do the following (in the command window): + + tk info comm .* + +To get the list of resources (and their classes) for a given widget, do some- +thing like: + + tk .asm.text config + +This will return a list of lists, where each sublist looks something like this: + + {-height height Height 24 25} + +The first item is the name of the config option used when creating the widget. +The second item is the instance name of this resource, the third is the class +name. The fourth item is the default value, and the last item is the current +value. + +To get info about a single resource, add the config option name to the end of +the previous command. Ie: + + tk .asm.text config -font + +will return just the info about the font. + +To find out the class of a window, just do: + + tk winfo class .asm.text + +Note that some things may be explicitly overridden by gdbtk.tcl. In +particular, the `tk colormodel . monochrome' command should probably be +disabled if you want to use color. + +Hacking ~/.gdbtkinit and gdbtk.tcl +================================== +~/.gdbtkinit is sourced at the end of gdbtk.tcl. Currently there is no good +doc on this. See gdbtk.tcl for see what you can change. + +The GUI is primarily implemented by Tcl/Tk code which lives in gdbtk.tcl and a +C file called gdbtk.c. The Tcl/Tk code determines the look and feel, the +layout, and the functions associated with all of the interface elements. The C +code is mostly just glue between GDB internals and Tclland. In essence, all of +the policy is implemented in Tcl/Tk, and is easily changed without recompiling. + +To make more serious changes to the interface, such as adding a new window or +changing the framework, you will have to hack gdbtk.tcl. This file is +installed in $(libdir) (probably /usr/local/lib/). But, you will probably want +to hack on your own private copy before putting it up for the rest of the +users. GDB actually searches three places for gdbtk.tcl. First, it looks in +the GDBTK_FILENAME environment variable. Second, it looks for ./gdbtk.tcl. +And third, it looks for $(libdir)/gdbtk.tcl. + +Internally, GDBtk is basically GDB, linked with Tcl/Tk, and some glue code that +interfaces GDB internals to Tclland. This means that GDBtk operates as a +single program, not a front-end to GDB. All GDB commands, and a great deal of +the target program state are accessible to the Tcl programmer. In addition, +there are many callbacks from GDB to notify Tclland of important events. + +Here is a brief rundown of the GDB<=>Tcl interfaces: + +Tcl->GDB calls: + gdb_cmd - sends a text command to gdb. Returns the result + gdb_loc - takes PC, and returns a list consisting of a short file name, + the function name, a long file name, the line number and the + PC (in case you didn't supply it). + gdb_sourcelines - Takes a filename, and returns a list of lines that + contain code. + gdb_listfiles - Returns a list of all of the source files. + gdb_stop - Stops the target process. + gdb_regnames - Returns a list of all of the register names. + gdb_fetch_registers - Returns the contents of the specified registers. + gdb_changed_register_list - Returns a list of registers that have + changed since the last call. + gdb_disassemble - Takes a function or PC. Returns the text of a dis- + assembly of the entire function. + gdb_eval - Takes an expression. Returns it's value. + gdb_get_breakpoint_list - Does the obvious. + gdb_get_breakpoint_info - Takes a breakpoint number. Returns a list of + info about that breakpoint. + +GDB->Tcl callbacks: + gdb_tcl_fputs - Sends output into Tcl for the command window. + gdb_tcl_query - Pops up a query window. + gdbtk_tcl_breakpoint - Notifies Tcl of changes to a breakpoint. + gdbtk_tcl_idle - Notifies Tcl that debugged process is now idle. + gdbtk_tcl_busy - Notifies Tcl that debugged process is now running. + +For details, see the usage in gdbtk.tcl, or the definitions in gdbtk.c. + +Additionally, there is a new GDB command `tk', which can be used to poke at +Tk/Tcl from the command window. + +Problems +======== + +During building, you may run into problems with finding Tcl, Tk or X11. Look +in gdb/Makefile, and fix TCL_CFLAGS, TCL, TK_CFLAGS, TK, and ENABLE_CLIBS as +appropriate. + +If you one of the following messages when you run gdb: + + Tcl_Init failed: can't find init.tcl; perhaps you need to + install Tcl or set your TCL_LIBRARY environment variable? +or + Tk_Init failed: can't find tk.tcl; perhaps you need to + install Tk or set your TK_LIBRARY environment variable? + +then you haven't installed Tcl or TK properly. Fix the appropriate environment +variable to point at the {tcl tk}/library directory, and restart gdb. + +If you get the following: + + /usr/local/lib/gdbtk.tcl:1: couldn't read file "/usr/local/lib/gdbtk.tcl": No such file or directory + Stack trace: + can't unset "auto_index": no such variable + while executing + "unset auto_index" + +then GDBtk wasn't installed properly. You can set the GDBTK_FILENAME +environment variable to point at the gdbtk.tcl in your source directory. Note +that the stack trace displayed here is not valid. If you actually get an error +in gdbtk.tcl, the stack trace is useful to pinpoint the location. |