Subversion Repositories or1k

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.