diff options
Diffstat (limited to 'gdb/gdbtk/README.GDBTK')
| -rw-r--r-- | gdb/gdbtk/README.GDBTK | 400 |
1 files changed, 0 insertions, 400 deletions
diff --git a/gdb/gdbtk/README.GDBTK b/gdb/gdbtk/README.GDBTK deleted file mode 100644 index 818d519ba1d..00000000000 --- a/gdb/gdbtk/README.GDBTK +++ /dev/null @@ -1,400 +0,0 @@ - README.GDBTK - Written by Stu Grossman - Updated 9/26/95 by Fred Fish for gdb 4.15 release - Updated 4/18/97 by Martin Hunt - -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 separate -front-end program. The interface consists of several seperate -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), and so forth. - -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.6 and Tk version 4.2. - -On Unix machines, you will also need to have X11 (R4/R5/R6) installed -(this is a prerequisite to installing Tk). - -For Windows, you can obtain Tcl/Tk from ftp://ftp.smli.com:/pub/tcl/win76p2.exe. -There is a bug in this version of Tcl/tk that requires you to set the -environmental variable TK_LIBRARY to where the tk library directory is installed. -There is also a problem with the colors in images on 16-bit displays under -Windows, so some icons may look strange. - -[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) Assembly - 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 stop sign icon. - - 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). - -Assembly 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 the files in gdbtcl, 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 gdbtcl 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 gdbtcl -================================== -~/.gdbtkinit is sourced at the end of gdbtk.tcl. Currently there is no good -doc on this. See gdbtcl/main.tcl for see what you can change. - -The GUI is primarily implemented by Tcl/Tk code which lives in gdbtcl 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 the tcl code. This directory 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. To find the GDB tcl code, GDB first checks for the environment variable -GDBTK_LIBRARY. This can be a directory name or a list of directories seperated -by colons (semicolons on Windows). GDB will check each directory in order until -it finds "main.tcl". If GDBTK_LIBRARY is not set, GDB will look for -"gdbtcl/main.tcl" in the current directory, and finally, it will try to find -the tcl directory in the sources. - -Note that the old GDBTK_FILENAME environment variable is no longer used. - -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. - -Known Bugs -========== - -generic problems - - o If you open an Assembly window before you have run the program, gdbtk - pops up a dialog box titled "Error in Tcl Script" with the contents - "Error: No function contains the specified address". Trying to then - do other things brings up a dialog box with the contents "Error: - can't read 'current_asm_label': no such variable. - - Solution: Close Assembly window when there is no program running. - - o If you open Registers window before you have run the program, gdbtk - pops up a dialog box titled "Error in Tcl Script" with the contents - "Error: No registers". Trying to then do other things, like use the - Start button to run the program, repeatedly produce the same dialog - box and the action is not performed. - - Solution: Close Registers window when there is no program running. - - o Expressions are sometimes not displayed correctly in the Expression - window. I.E. "argc" works, as does "*(argv+argc)" but not "argv[argc]". - - Solution: None - [ I believe this problem is fixed, but I have not tested it ] - - o The Breakpoint window does not get automatically updated and changes - made in the window are not reflected back in the results from "info br". - I.E. the breakpoint count in the window is not updated at each hit and - enabling/disabling the breakpoint from the Breakpoint window has no effect. - - Solution: Use the command interface to control breakpoints and don't - open a Breakpoint window. - - o Sometimes while an expression window is active you get a dialog box - that complains "Error: invalide command name ".expr.e5.expr" for - example. The Tcl stack trace looks something like: - - invalid command name ".expr.e5.expr" - while executing - "$e.expr get 0.0 end" - invoked from within - "set expr [$e.expr get 0.0 end]..." - (procedure "update_expr" line 17) - invoked from within - "update_expr $expr_num" - invoked from within - "if $expr_update_list($expr_num) { - update_expr $expr_num - . - . - . - - Solution: None except close expression window and reopen it. - - o If you select the "Down" button in either the Source or Assembly - window while in the bottom (innermost) frame, the error message that - results goes just to the command window and may be missed if the - command window is not open. This may also apply to other messages - as well. It should probably put up a notification box instead. - - Solution: Keep Command window open to see error messages. - - o Not really a problem, but it would be nice to have a backtrace - window. - - Solution: Do bt in command window? - - o Also not really a problem, but it might be nice to have a frame/stack - window that displays the last N words on the stack, along with - indications about which function owns a particular frame, how the - frame pointers are chained, and possibly the names of variables - alongside their frame slots. - -m68k-hp-hpux9.00: - - o Attempting to use a Register window results in a Tcl Script Error - "Error: Erroneous arithmetic operation". The Tcl stack trace is: - - while executing - "gdb_fetch_registers $reg_format $regnum" - invoked from within - "set regval [gdb_fetch_registers $reg_format $regnum]..." - ("foreach" body line 2) - invoked from within - "foreach regnum $reg_display_list { - set regval [gdb_fetch_registers $reg_format $regnum] - set regval [format "%-*s" $valwidth $regval] - $win del ..." - invoked from within - "if {$which == "all"} { - set lineindex 1 - foreach regnum $reg_display_list { - set regval [gdb_fetch_registers $reg_format $regnum] - set regval [f ..." - (procedure "update_registers" line 16) - invoked from within - "update_registers all" - . - . - . - - |