2001-02-04 Fernando Nasser <fnasser@redhat.com>

	* library/plugins/plugins.tcl: Fix typos and remove "-transient"
	parameter from open command.
	* library/plugins/HOW-TO: New file.  Describes how to add a plug-in
	window to Insight.

3 files changed, 415 insertions, 3 deletions

diff --git a/gdb/gdbtk/ChangeLog b/gdb/gdbtk/ChangeLog
index 79cf7606117..5b6cb592e6d 100644
--- a/gdb/gdbtk/ChangeLog
+++ b/gdb/gdbtk/ChangeLog
@@ -1,3 +1,10 @@
+2001-02-04  Fernando Nasser  <fnasser@redhat.com>
+
+	* library/plugins/plugins.tcl: Fix typos and remove "-transient"
+	parameter from open command.
+	* library/plugins/HOW-TO: New file.  Describes how to add a plug-in
+	window to Insight.
+
 2001-02-01  Fernando Nasser  <fnasser@redhat.com>
 
 	* library/images/insight.gif: New splash screen/about graphics.
diff --git a/gdb/gdbtk/library/plugins/HOW-TO b/gdb/gdbtk/library/plugins/HOW-TO
new file mode 100644
index 00000000000..3e2a47a33e2
--- /dev/null
+++ b/gdb/gdbtk/library/plugins/HOW-TO
@@ -0,0 +1,405 @@
+INSIGHT PLUG-INS HOW-TO
+=======================
+
+This text describes the technical aspects of adding a plug-in window
+to Insight, the graphical front-end to the GNU debugger GDB.
+
+
+1) INTRODUCTION
+
+The plug-in facility allows for the addition of custom windows to
+Insight.  These windows are not to become part of the Insight
+distribution, but rather to be distributed separately.  They can be
+downloaded from the authors web site, may accompany some development
+board or embedded OS or come with anything else that can benefit from
+a custom window being added to the standard Insight.  As the plug-ins
+will be loaded into Insight/GDB for execution, the terms of the GPL
+also apply to the plug-in code.  Also, Red Hat provides this facility
+as-is and accepts no responsibility from its use.  Please refer to the
+text of the GPL for more details.
+
+The facilities described here provide support for custom
+visualizations (custom windows for displaying information retrieved
+from the target).  By writing a plug-in, it is possible to visualize
+target specific data that is not shown in the standard Insight
+windows.
+
+The plug-in facility cannot be used to control target execution.  The
+current implementation of Insight assumes that only the Source Window
+issues commands related to target execution control.  There is no
+mechanism to prevent one to call the commands that control execution,
+but its use may result in inconsistent GUI states.  This restriction
+may be lifted in future versions of Insight.
+
+The facility works as follows: A "plugins" subdirectory is added under
+the gdbtcl directory where Insight Tcl code is installed.  The custom
+plug-in code will be installed in a subdirectory of this "plugins"
+directory.  The plug-in window will be written as a [incr Tcl/Tk]
+class which inherits from the provided PluginWindow class and
+implements the methods necessary to display the desired custom
+data. GDB will read plug-in files on start-up and add a menu item to
+the PlugIn menu of the Insight Source Window.  When the menu item is
+chosen, GDB instantiates the custom plug-in class.
+
+The PluginWindow base class constructor creates a toplevel window (an
+Insight ManagedWin) which contains a "childsite".  In this case, the
+"childsite" is a frame in which the derived class (the custom plug-in)
+can draw.  The PluginWindow class also provides facilities to add a
+menu and a toolbar.  Among the methods provided by this class, the
+"running" method is called every time the debugger starts the target
+and the "stopped" method is called every time the target stops. In the
+"stopped" method, information can be gathered from the target and
+displayed.  The "running" method indicates that GDB is busy running
+the target.  No activities should be initiated by any GUI component
+while in this state (except for the STOP button in the Source Window).
+
+The remainder of this document describes how to install a custom
+plug-in and some details of the PluginWindow class.  Writing Tcl
+Extensions (technically is what plug-ins are) is beyond the scope of
+this document, but a simple example is given and some documentation
+references are provided.
+
+Please see the file CONTRIBUTE in this directory for some
+administrative details before you start developing your plug-in.
+
+
+2) HOW TO ADD A PLUG-IN WINDOW TO INSIGHT
+
+Once you have your plug-in class ready, here is how to make it show up
+in the Insight Source Window "PlugIn" menu.  You may perform these
+steps manually, but if you are distributing your plug-in, it may be
+convenient to provide with it an installation script that automate
+this steps.
+
+The examples in this section refer to the sample plug-in code provided
+with the Insight sources, located in the
+$(SOURCE)/gdb/gdbtk/library/plugins and
+$(SOURCE)/gdb/gdbtk/library/plugins/rhabout directories.
+
+Custom plug-ins are provided as "packages" (see [Welch 2000] and
+[Smith 2000]).  The following setup will cause your plug-in package to
+be loaded. 
+
+i) First, locate the $(INSTALL)/share/gdbtcl directory.  This is the
+directory which contains the Tcl/Tk code used by Insight.  Create a
+"plugins" subdirectory if it does not exist yet (i.e., if your plug-in
+is the first to be installed).  Now you must have a directory:
+   $(INSTALL)/share/gdbtcl/plugins
+in your installation tree.
+
+ii) Create a subdirectory for your plug-in code (named in accordance to
+the conventions set forth in the CONTRIBUTE file).  Add all your code
+to that directory.  Make sure you have a tclIndex file or use
+auto_mkindex to create it.  For instance, in the sample case we would
+have:
+   $(INSTALL)/share/gdbtcl/plugins/rhabout
+and it would contain:
+   rhabout.itcl  rhabout.so  tclIndex
+
+iii) In the "plugins" directory create a file that will actually load your
+plug-in package (named accordingly to the CONTRIBUTE conventions).  In
+the provided sample, this file is "rhabout.tcl" and would contain the
+following lines:
+
+   package provide RHABOUT 1.0
+   set dirname [file dirname [info script]]
+   lappend auto_path [file join $dirname rhabout]
+   load [file join $dirname rhabout rhabout.so] RHABOUT
+
+The first line states what package the sample plug-in code is
+providing.  Note that the subdirectory "rhabout" which contains the
+sample plug-in is added to the auto_path in the third line and there
+is a tclIndex file in that directory (that is how plug-in classes and
+methods are found).
+
+The last line is only necessary if your plug-in contains Tcl command
+procedures written in C.  Loading Tcl libraries is described in [Welch
+2000] and the [incr Tcl/Tk] bits can be found in [Smith 2000].  It is
+recommended that the reader also refer to the "load" Tcl man page if
+these dynamic libraries are to be loaded.
+
+iv) In the "plugins" directory, add an entry to the pkgIndex.tcl file,
+if it exists, with a "package ifneeded" command to source the file
+created in step (iii).  If the file does not exist, create it.  For
+the sample plug-in, this entry is:
+
+   package ifneeded RHABOUT 1.0 [list source [file join $dir rhabout.tcl]]
+
+This roughly corresponds to what would be created by a pkg_mkIndex
+command with the "-direct" option.
+
+If you are writing a install script, make sure to append to this file,
+not overwrite it.  If there are other plug-ins already installed you
+don't want to remove their "package ifneeded" commands (e.g., use ">>"
+in a c-shell script).  Be considerate.
+
+v) Create the file "plugins.tcl" in the "plugins" directory if it does
+not yet exist.  Again, this is a file shared by all plug-ins so make
+sure your install script does not overwrite, but append to it.
+
+This is a Tcl code fragment that will be sourced by the Insight Source
+Window constructor to add menu entries to the "PlugIn" menu that will
+instantiate the plug-in classes.  If there is any error in this few
+lines of code Insight will not start and a Tcl stack trace will be
+shown.  So test it in your build directory before installing in a
+system shared by others.
+
+For the sample plug-in, this lines would be:
+
+   # Add your window to the PlugIn menu here
+   # Don't forget to add your packet as well
+
+   if {1} {  #test here if your target is configured
+     #package require LIBGDB 1.0
+     package require RHABOUT 1.0
+     $Menu add command Other "About Red Hat" \
+       {ManagedWin::open RHAbout} \
+       -underline 0
+     set plugins_available 1
+   }
+
+You can ignore the LIBGDB "package require" command for now.  LIBGDB
+is under construction and not yet available.  But do not forget to
+add a "package require" command for your plug-in package.  Otherwise,
+when someone choses your plug-in menu entry a stack trace will be
+produced.
+
+The Tcl command starting with "$Menu" is similar to the ones provided
+by the "menubar" component of the PluginWindow class (described later
+in this document), but all one needs to do is to copy the above
+replacing the menu entry text "About Red Hat", the plug-in class name
+"RHAbout" and the underline index with the appropriate values.
+
+The "set plugins_available 1" command is important.  If the variable
+"plugins_available" is not set to 1 by any of the plug-in code
+fragments, the Source Window will not have a "PlugIn" menu.
+
+This brings us to the "if" statement in the first line.  The sample
+plug-in is generic, it works with any target.  However, a custom
+plug-in may be written for a specific target and be of no generic
+use. Furthermore, a target specific plug-in may not even work with
+other host and target configurations different from the one it was
+designed for.
+
+The Tcl code used by Insight is shared by all configurations (thus the
+subdirectory name "shared") and adding a plug-in in the wrong
+configuration could render Insight unusable.  To avoid this, a test
+for the right configuration must be made so that the plug-in menu
+entry is only added in the configurations that support it (the
+"package require" must also be protected).
+
+Insight has a global variable which contains configuration
+information. The array "GDBStartup" has the elements:
+   host_name     - host configuration triplet
+   target_name   - target configuration triplet 
+
+Use these values, $GDBStartup(host_name) and $GDBStartup(target_name),
+to verify that your plug-in code is supported.  Don't forget to add
+"global GDBStartup" before you refer to this array.
+
+For instance, if the sample code could only be used with Linux hosts,
+the sample code above would look like this:
+
+   # Add your window to the PlugIn menu here
+   # Don't forget to add your packet as well
+
+   global GDBStartup
+   if {[string first "linux" $GDBStartup(host_name)] != -1} {
+     #package require LIBGDB 1.0
+     package require RHABOUT 1.0
+     $Menu add command Other "About Red Hat" \
+       {ManagedWin::open RHAbout} \
+       -underline 0
+     set plugins_available 1
+   }
+
+
+3) DEVELOPING AN INSIGHT PLUG-IN
+
+Only itcl based windows will work.  They must also be derived (i.e.,
+inherit) from the PluginWindow class described in the next section.
+You must also follow the name conventions described in the CONTRIBUTE
+file to avoid class name clashes.
+
+The PluginWindow base class has facilities for adding a menu and a
+toolbar.  It already provides the code to deactivate buttons and menu
+entries when GDB is busy (running the target) and reactivate them when
+the target stops.  Your job usually consists of calling a method to
+redraw your window with updated information when the target stops.
+You can do this simply by adding a call to this method inside the
+"stopped" method provided.
+
+The Insight Tcl source file gdb/gdbtk/library/interface.tcl and the C
+file gdb/gdbtk/generic/gdbtk-cmds.c contain a (quite volatile) set of
+Tcl commands that can be used to retrieve information from and about
+the target.  Examples of the use of such commands exist all around the
+Insight source code and details are usually given near the procedure
+or function definitions.  Please refrain from using commands that
+control the target execution or change the GDB state in any way, they
+are reserved for use by the Source Window only.  Remember, plug-ins are
+a visualization facility only.
+
+A special remark is necessary about the gdb_cmd and gdb_immediate
+commands.  These are deprecated and will disappear (stop working) soon.
+The GDB maintainers have asked the Insight maintainers to stop using
+the hooks in GDB code that make them possible.  Conversion is already
+under way.  You can use them for prototyping (for now), but be
+prepared to write Tcl command procedures instead of parsing console text
+output.  
+
+If you need to issue target-dependent commands to retrieve information
+from your target (that cannot be retrieved with the standard register
+and memory access operations), you can write Tcl command procedures
+and add them to your target dependent file enclosed in 
+   #ifdef GDBTK
+   #endif
+The target dependent Tcl code will move to a subdirectory of gdbtk in
+the future, but for now, just add it to your existent target-dependent
+file.
+
+If you must access gdb functions that are not yet available in
+gdbtk-cmds.c (or in any of the spun-offs that will soon exist in the
+gdb/gdbtk/generic directory), consider writing to the Insight
+maintainers.  They will be able to tell you what command should be
+implemented and, if they have the time, add it to Insight.  As they
+may be busy, consider offering to write the code yourself and
+submitting it for approval (see CONTRIBUTE).  You can see how these
+Tcl command procedures in C are written by looking at what it is done
+in the gdbtk-cmds.c file and others in the gdb/gdbtk/generic
+subdirectory.  Again, you can use the gdb_cmd and gdb_immediate
+commands to invoke a GDB command line interface command, but they will
+not be available for long.
+
+Please refer to the sample source code located in the files:
+  gdb/gdbtk/library/plugins/rhabout/rhabout.itcl
+  gdb/gdbtk/library/plugins/rhabout/rhabout.c 
+
+The comments in these files provide a basic framework for a Insight
+plug-in.
+
+
+4) THE "PluginWindow" BASE CLASS
+
+The PluginWindow base class provides the following methods:
+
+childsite  -  returns the path of the frame component that can be used
+by the plug-in code to pack its custom display components.
+
+stopped  -  called when the target stops.  It should be overloaded and
+call the plug-in procedure that updates the display.  The child
+version must call the base class method implementation if it wants
+menu items and/or buttons to be automatically controlled.
+
+running  -  called when GDB becomes busy by running the target.  No
+commands shall be issued by a plug-in while GDB is busy.  The child
+version must call the base class method implementation if it wants
+menu items and/or buttons to be automatically controlled.
+
+no_inferior  -  called when GDB disconnects from the target.  The
+plug-in may want to forget some context information in this case,
+depending on the specifics of its implementation.  The child
+version must call the base class method implementation if it wants
+menu items and/or buttons to be automatically controlled.
+
+
+The PluginWindow base class contains two components which can be
+optionally used:
+
+menubar  -  allows a menu to be added to the plug-in window.  This
+facility is implemented by the GDBMenuBar class (gdbmenubar.itcl).
+
+toolbar  -  allows a toolbar to be added to the plug-in window.  This
+facility is implemented by the GDBToolBar class (gdbtoolbar.itcl).
+
+
+Both buttons and menu entries have "class" attributes.  Button classes
+and Menu entry classes are specified when they are created and are
+used for the automatic control of button and menu entry states.
+If the class is specified as "None", the menu entry or button will
+remain always active.  The classes "Control" and "Other" follow the
+following convention:
+
+   Control    Other     State
+     off       off      gdb is busy
+     on        on       gdb has inferior, and is idle
+     off       on       gdb has no inferior, and is idle
+
+
+The "menubutton" component offers the following supported commands:
+
+add menubutton  - add a menu button to the window menu bar.
+add command     - add an entry to the last menu created.
+add separator   - add a separator to the last menu created.
+show            - attach the created menu to the window.
+
+If the show command is not issued, the plug-in window will have no
+menu bar.  There are other methods and commands defined in the
+GDBMenuBar class.  They are for Insight internal use only and should
+not be used by plug-in windows.
+
+A menu named "help" will automatically be aligned to the right.
+
+The sample plug-in code creates a simple menu with the following commands:
+
+    $menubar add menubutton file "File" 0
+    $menubar add command None "Close" \
+      [code $this destroy_toplevel] \
+      -underline 1
+    $menubar add menubutton help "Help" 0
+    $menubar add command Other "Help Topics" \
+      {HtmlViewer::open_help index.html} \
+      -underline 0
+    $menubar add separator
+    $menubar add command Other "About GDB..." \
+      {ManagedWin::open About -transient} \
+      -underline 0
+
+    # The menu only shows up if you do this:
+    $menubar show
+
+
+The "toolbar" component offers the following supported commands:
+
+add button      - add a button to the window tool bar.
+add label       - add an label widget to the tool bar.
+add separator   - add a separator to the tool bar.
+itemconfigure   - configure a tool bar element.
+show            - make the toolbar visible.
+
+If the show command is not issued, the plug-in window will have no
+tool bar.  There are other methods and commands defined in the
+GDBToolBar class.  They are for Insight internal use only and should
+not be used by plug-in windows.
+
+Use the "itemconfigure" command to fill the label elements with the
+current data as necessary.
+
+The sample plug-in code creates a single button with the following commands:
+
+    $toolbar add button con Other {ManagedWin::open Console} \
+                           "Console (Ctrl+N)" -image console_img
+
+    # The toolbar will only show up if you do this:
+    $toolbar show
+
+
+The complete Tcl code of the sample plug-in can be found in the file
+   gdb/gdbtk/library/plugins/rhabout/rhabout.itcl
+and the PluginWindow class definition and implementation is in the file
+   gdb/gdbtk/library/pluginwin.itcl
+
+Please refer to the files
+   gdb/gdbtk/library/gdbmenubar.itcl
+and
+   gdb/gdbtk/library/gdbtoolbar.itcl
+for the current arguments accepted by the menubar and toolbar commands
+respectively.
+
+
+REFERENCES
+
+[Smith 2000] Chad Smith, "[incr Tcl/Tk] from the Ground Up".
+Chapters 9 and 10.  Osborne/McGraw-Hill, 2000. 
+
+[Welch 2000] Brent B. Welch, "Practical Programming in Tcl and Tk",
+3/e.  Chapters 12, 14, 44, 45, 46 and 47.  Prentice Hall PTR, 2000.
diff --git a/gdb/gdbtk/library/plugins/plugins.tcl b/gdb/gdbtk/library/plugins/plugins.tcl
index 949f917df34..a8e9481c1e7 100644
--- a/gdb/gdbtk/library/plugins/plugins.tcl
+++ b/gdb/gdbtk/library/plugins/plugins.tcl
@@ -1,12 +1,12 @@
 # Add your window to the PlugIn menu here
-# Dont forget to add your packet as well
+# Don't forget to add your packet as well
 
 if {1} {  #test here if your target is configured
   # Uncomment this when the PlugIn class is ready
-  #package require PLUGIN 1.0
+  #package require LIBGDB 1.0
   package require RHABOUT 1.0
   $Menu add command Other "About Red Hat" \
-    {ManagedWin::open RHAbout -transient} \
+    {ManagedWin::open RHAbout} \
     -underline 0
   # To activate the PlugIn sample, uncomment the next line
   set plugins_available 1