--- /dev/null
+ 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.
projects / binutils-gdb.git / commitdiff