- README.GDBTK for gdb-4.14 release
- Created April 11, 1995 by Stu Grossman
+ 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 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...
+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.3 (or 7.4), and Tk 3.6.
-[We haven't ported to Tk 4.0 yet.]
+directory. You will also need to install Tcl version 7.6 and Tk version 4.2.
-You will also need to have X11 (R4/R5/R6) installed (this is a prerequisite to
-installing Tk).
+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.]
1) Command
2) Source
- 3) Disassembly
+ 3) Assembly
4) Register
5) Auto Command
6) Expression
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'.
+ that line, the indicator is replaced with a stop sign icon.
The buttons are:
The mouse can also be used to set and clear breakpoints when clicked
in the margin (on a breakpoint indicator).
-Disassembly window:
+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
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.
+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 gdbtk.tcl files.
+For more serious customizations, you will probably need to hack your
+~/.gdbtkinit or gdbtcl files.
X Resources
===========
particular, the `tk colormodel . monochrome' command should probably be
disabled if you want to use color.
-Hacking ~/.gdbtkinit and gdbtk.tcl
+Hacking ~/.gdbtkinit and gdbtcl
==================================
~/.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.
+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 gdbtk.tcl and a
+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 gdbtk.tcl. This file is
+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. 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.
+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
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"
+ .
+ .
+ .
+
projects / deliverable / binutils-gdb.git / blobdiff