+++ /dev/null
-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.
OSDN Git Service
