Merge to Cygnus 961112 + add some support (not ready) for shared libs

1 files changed, 386 insertions, 0 deletions

diff --git a/gnu/usr.bin/binutils/gdb/README.GDBTK b/gnu/usr.bin/binutils/gdb/README.GDBTK
new file mode 100644
index 00000000000..d2aecdd1d0f
--- /dev/null
+++ b/gnu/usr.bin/binutils/gdb/README.GDBTK
@@ -0,0 +1,386 @@
+				 README.GDBTK
+			   Written by Stu Grossman
+	      Updated 9/26/95 by Fred Fish for gdb 4.15 release
+
+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 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), 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.5a2, and Tk 4.1a2.
+
+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) 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 `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).
+
+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
+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.
+
+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"
+		. 
+		. 
+		. 
+