* README.GDBTK: New file. Contains the obvious.

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.