Soar Debugger (SDB) v1.0
Released 12May00
Contact: Glenn Taylor (glenn@soartech.com)
Soar Technology, Inc.

1. Overview
2. Watches/Breaks
3. How to Run
4. Release History
5. Known Issues
6. Wishlist

Overview

The Soar Debugger (SDB) makes an attempt being a "true" debugger along the lines of gdb or xdb, with breakpoints and watches on variables, and the ability to easily inspect deep structures. It has been written separately from the TSI or any agent window, and using an earlier version of Tcl/Tk (7.6/4.0) so it is more portable across different applications using Soar. (So far tested under TankSoar and TacAir-Soar.) It also runs just fine under Tcl 8.x. The debugger is not meant to contain all Soar or TSI functionality; that is, not every Soar function has a comparable graphical interface in the SDB. Instead, I've tried to incorporate more complex functionality, or more convenient methods for accessing typical functionality, while leaving the "normal" stuff to the TSI. (Popup menus I've tried to make exempt from this rule--they're too convenient to leave out.) A debugger is instantiated within an agent, and so is specific to that agent; multiple agents can each have their own debugger. However, default preferences are common to all debuggers. To modify individually, preferences would have to be loaded from a file once a specific debugger has been invoked. The SDB has several things to offer, most of which appear under the Tools menu. Each item in the menu is described below.

• Productions
  This pops up a dialog allowing the user to search (using glob-style matching) for production names. In the listbox containing the search results, some common operations are provided (via a pull-down menu) to act on those productions. Included in this pulldown menu are:
• Print
• firing-count
• matches ... -wmes
• matches ... -timetags
• Breaks
  • break on fire
    This creates a breakpoint to catch when the production fires. (It is done by adding (interrupt) to the end of the production)
• Excise
• Views
  These provide different views into Soar; each appears as a separate popup window whose arrangement on the screen is remembered by the debugger. Also, the view submenu can be "torn off" for quicker access to turn on or off any popup window; popups can also be safely dismissed using the close button on the window. (The first three of these were "borrowed" from the 3.0 version of the TSI.)
  • Preferences
    Provides a constantly-updated view of the current preferences considered.
  • Matches
    Provides a constantly-updated view of the current matches.
  • Stack
    Provides a constantly-updated view of the current stack.
  • StateMap
    Provides a expandable, hierarchical view of the current states. The data, however, is not constantly updated, and gives only a "snapshot" of the system, which could immediately go out of date. The "Update" button allows the user to refresh the tree on-demand. The statemap also has a context-dependent popup-menu (accessed by right-clicking the mouse) for the following functions:
    • Print - standard soar function
    • Preferences - standard soar function
    • Watches
      • Add Watch Creates a watchpoint for the selected attribute-value pair.
    • Breaks
      • Break on value change
        Creates a break for when the value of the selected item changes
      • Break on value expression
        Brings up a popup window to define a test on the selected item. Accepted conditionals are <,<=,=,>=,>,<>. The = is dropped in the created production, and is a "true" equal test, rather than the "equal types" test available in Soar. Also, = and <> can be used with multiple values to test inclusion in or exclusion from a set.
      • Break on Attribute On Symbol
        Brings up a dialog asking for an attribute to test for on the selected symbol. When that attribute appears on the symbol, the breakpoint is invoked. Optionally, an attribute-value pair can be tested.
      • Break on Attribute Not in Set
        Brings up a dialog asking for an expected set of attribute names; when a new attribute appears on the selected symbol, which is not part of the defined set, the break is invoked. [See below for a more detailed discussion of watches and breaks.]
    • WMEs
      • Add-Wme Brings up a popup window for defining the wme to add to the selected item (or its immediate parent, if the selected item is not a symbol)
      • Remove-Wme Removes the wme. Queries the user to make sure it's the right thing to do.
  • Watches
    Provides a list of the created watches, and a constantly updated value of the watched attribute. A checkbutton allows the activation/deactivation of the watch without actually deleting it. The Delete button deletes the selected watch.
  • Breakpoints
    Provides a list of the created breaks. When a breakpoint is hit, the relevant break is highlighted in the breakpoints window. A checkbutton allows the activation/deactivation of the break without actually deleting it. The Delete button deletes the selected breakpoint.

Watches/Breaks

Breakpoints and watches are implemented as Soar productions with attribute tests derived from the information in the StateMap which was clicked on. They are inserted into the user space of productions, so you will see something like debug_watch1 or debug_break1 if you list all the productions. When a watch or break is deleted, the corresponding production is excised from production memory. In the case of "Break On Production Fire", a new production is created with the same LHS as the chosen production, but with a different name, and whose RHS consists solely of the interrupt command. Due to how Soar matches, the interrupt will happen at the same time as if the chosen production had an interrupt in its RHS.

Since they are productions, they follow all the rules of matching under Soar. Thus, the following behaviors will be observed:

• a break will often occur immediately after the break was created, even if nothing changed
• a value-expression break will occur the first time the expression evaluates to true, but not subsequent times, until the tested value changes to cause retraction and rematching
• a break on <,<=,>,>= will break anytime the value changes and the test holds true, rather than each cycle

Judiciously activating/deactivating (without deleting!) breakpoints will make these behaviors a little more reliable or acceptable. This method was chosen due to the ease of implementation--it's all Tcl code, no architectural changes were necessary, and since they are productions, watches and breaks will only fire when the tested values match, so the efficiency overhead is negligible. However, some may see this method of breaks/watches-as-productions as too intrusive. If this seems to be the concensus, I'm open to other methods of implementation.

How to Run

To run, type the following in the agent window:

• cd <sdb directory>
• source debug.tcl
• debugger
• cd <back to original directory>

You'll want to cd back to the original directory, since, in some environments, you might not be able to create a new agent being in a different directory than Soar expects.

Release History

New in Version 1.0 (Soar20 Debut)

• HTML-ified the README, made website www.soartech.com/download.html
• Better error catching
• Made break-on-production-fire create a new production with duplicate LHS of production to break on.
• Better (?) grabs so windows doesn't freak out so often

New in Version 0.4b

• added "Search Set" to production finder, to allow print -user | -chunks | -defaults | -justifications | -all
• fixed some small GUI irregularities/problems/bothersomes
• added "firing-count" to ProductionTools pulldown menu
• fixed debug_attr_from_raw AV_DVD problem
• added "production-find" capability to statemap's window
• better state testing (full path linking to superstate nil)
• made "on-production-fire" breakpoint (from Production Finder)
• made watches and breaks list chronologically

New In Version 0.3b

This is more of a performance/beautifying release than a functionality release.

• Better interface, more flash, more consistency
• Tools menu replaces Views (views is now a submenu)
• Production search dialog
• Better environment preferences editor
• More pull-down menu functionality
• More "sanity checks"
• rudimentary online help

New In Version 0.2b

The following features are new to this version of the debugger.

• Load/Save Environment (menu item)
  Allows the user to load or save the preferences file on demand. Typically, this file is loaded on initialization, and saved on quitting. Included in the preferences are the locations of the popup windows. When a window is been moved, its place is remembered, and it will be recreated in that location.
• Edit Environment (menu item)
  Allows the user to modify the following properties of the debugger:
  • Files
    • Preferences File: the filename in which these properties are stored
  • Appearance
    • Background Color: the background color of the popup windows
    • Foreground Color: the text color of the popup windows (disabled)
    • Font/size: the common font name and font size for popup window text.
  • State Map Properties
    • Forget on Branch Collapse: If this option is on, then the collapse of a branch in the State Map will make the debugger regenerate that branch's children the next time the branch is open, which means the data in a freshly opened branch will always be new. If this option is off, data will not be regenerated, so sub-branches which have been previously expanded and hidden will still be available. (The statemap forgets by default) Breaks/Watches Properties
    • Debug Prefix: This is the prefix used in breakpoint and watch productions generated by the debugger. This prefix should only have to be changed if it creates conflicts with the user's production names.
  • Advanced
    • State Tree path divider: This is a character the state map widget uses to divide up elements in the path of an attribute; it's obscurely set to @ because this seems to be a good character which is not used in Soar's attribute names. This character should only be changed if the @ starts being seen in attribute names.
    • Attribute/Value divider: This is another character used by the state map to separate attributes and their values. Change it if it appears in attribute names.
• Statemap (changes)
  • Breaks
    • break-on-value-in-set Test if an attribute's value falls within a given set of values. This is accomplished by using the = conditional with multiple values.
    • break-on-value-not-in-set Test if an attribute's value doesn't fall within a given set of values. This is done by using the <> conditional with multiple values.
    • break-on-attrib-on-symbol (menu item) Given a symbol and path, break when a new attribute is added to that symbol, with an optional test for that attribute's value.
    • break-on-attrib-not-in-set (menu item) Given a symbol and path, break when an attribute is added which is not in the expected set.
  • Context-sensitive pulldown menu
    Depending on if the selected item in the statemap is a symbol or not, only show the user the possible commands to perform.

Bugs/Issues/Complaints/Workarounds

The following is an incomplete list of bugs or issues with the debugger (and possible workarounds, if applicable). The SDB has been tested under the following environments:

• RedHat Linux 5.2 with Tcl7.6/Tk4.0 and Tcl8.x (TacAir-Soar and TankSoar)
• Winows95 (TankSoar)

Unfortunately, I have no access to a Macintosh to know how it fares under that environment. If anyone tries it, let me know how it works. If you find issues that are not on this list, please send me a note describing the details of the problem, what environment you're running under, and the symptoms seed.

• Sometimes menubuttons get "stuck" and nothing else can be selected or win focus. [Win95] [Workaround: Select Help->About, then dismiss the dialog. Everything returns to normal. This is a very bizarre bug.]
• Values "flutter" when a watch matches multiple values. An attribute path can be non-unique, making the value displayed in the watches window unpredictable. I haven't thought too much about how to make the production for the watch more specific so it only fires on the specific attribute selected in the StateMap.
• Breaks act wierd. [See the discussion in the Watches/Breaks section earlier]
• Statemap collapses on an update. Because the entire tree can change from one update to the next, it is collapsed and completely redrawn, rather than changing only those items the user has expanded. This can probably be changed in a future version.
• The debugger windows don't refresh in expected ways in Windows as they do under Linux.
• The debugger makes everything a popup! This is a matter of taste. If most people want it one way or the other, I'll change it, or somehow make dockable toolbars or some compromise like that.
• The only way to create a watch or break is through the statemap. Not sure if this is an issue or not, just thought I'd write it down.
• Strange (and random) reversal of statemap font to something other than the preferences dictate.
• The [+/-] displays on the statemap are sometimes misleading if there's a symbol that has no value.
• dialogs don't accept RETURN as accept
• some dialogs let user return blank/invalid answers
• some unhelpful/obscured info in the watches & breaks windows
• Foreground Color editing causes core dump when watches window updates idle. (I disabled foreground color editing 10Sep99)
• preferences file is a list of tcl commands
• the main debugger window always shows up a little too low and right from where expected.
• wish8.0 crashes when env preferences are edited while the breaks window is open (There is some delay under wish4.0 (TacAirSoar), but it doesn't crash--20Sep99)
• sometimes the font/fontsize can be invalid for a given OS
• get a "Error: Can't read 'px': No such variable" when user goes to a different virtual desktop, then comes back while a combobox's list is displayed. (The combobox's popup menu is not closed when the mouse selects something outside the current application)
• sometimes combobox erases its value (happens after the above problem)
• if watches window is opened after creating a watch, and that value doesn't update regularly, the value may not show up in the window-- [To get around it,deactivate it, then activate again, using the checkbox.]
• cause a crash if agent is destroyed while debugger open in TacAirSoar

Wishlist/Next Version

The following is a growing list of features people have asked for, or things that were planned, but aren't yet implemented. Hopefully, time will allow at least some of them to find their way into a future version. Let me know if you'd like to see something in the debugger.

• commands in the Production Tools:
• break before production fire [i don't think this can be implemented how breaks are implemented now]
• better use of environment variables and push/pop for the location of the debugger, to be more conventional within soar. (although push/pop doesn't seem to work correctly)
• more/better preferences (font/color selector, etc)
• chunking utilities?
• better refresh on environment preferences accept
• stepping buttons (with user-defined commands for each? soar versions, etc)
• user-defined commands are needed since there are differences in how different soar versions handle stepping commands, etc.
• impasse debugging help
• auto-file loading if environmental preferences file changes in the editor
• Graph display for statemap? (RJ)
• save-state-map for later comparison? (for complete state map comparisons) (RJ)
• button for deleting all watches/breakpoints OR multiple select in my listboxes
• more formal/cleaner/standalone listbox-in-canvas implementations
• one debugger which can access any running interpreter?
• StateMap update options (collapse on update; update visible w/o collapsing; update selected) - keyed navigation of statemap/watches/breaks
• make breakpoint values not show up if breakpoint isn't firing (on a retraction?)
• "hotlinks" into statemap? (Vehicle, input link, etc)
• for "break on not-in-set" allow one click to get "anything not CURRENTLY in set" be default
• the equivalent of "print -depth ..." in the statemap (RC)
• break when attribute is no longer on a symbol See the file HISTORY for a revision history.