[platform-debug-dev] Teaching Debug to share

[Jared Burns <jaredburns@xxxxxxx>]

After talking with DarinW on the phone today, we solidified our overall
story for sharing debug platform artifacts (the Debug perspective,
views, and actions) as follows. The "Views" section is basically a
repeat of the story that we've discussed here. The "Actions" section is
new. We'd like feedback on both.

##############################################################
# Activities versus contexts (background)
##############################################################
If you're not up to speed with the Eclipse 3.0 workbench yet, take
particular note of the fact that contexts and activities are not the
same thing. 

Activities are generally long-lived. Once the user creates a Java
project, for example, a "Developing Java" activity might be enabled.
This activity would remain active (populating the workbench with the
appropriate choices of views, preference pages, and actions) until the
user manually turned it off.

Contexts are much more dynamic. While a user is typing in an editor, for
example, an "Editing text" context might enable. This context might
enable and disable every time the user moves focus to and from the
editor. For our purposes, "Debugging Java" might be a context that is
only active while a Java debugger is running. Or perhaps only while a
Java debugger is running with a thread suspended.

##############################################################
# Views
##############################################################
When a CONTEXT is activated in the workbench, the Debug view
automatically opens/activates views which are bound to that context via
the org.eclipse.debug.ui.contextViewBindings extension point.

The Debug view activates CONTEXTS based on selection. If a selected
element provides an adapter for an IDebugModelProvider, the view will
get that adapter and query it for debug model identifiers. Otherwise, if
the selection is a stack frame, the view will ask that frame for its
debug model identifier. With these model identifiers in hand, the view
will then query the org.eclipse.debug.ui.debugModelContextBindings
extension point to see if any contexts are associated with the model
identifiers. Any such contexts are activated in the workbench (see
previous paragraph).

When a launch terminates, all "context submissions" from that launch are
removed from the workbench. When all such submissions are removed (when
there are no more Java programs running, for example), the appropriate
views are automatically closed.

Debuggers should make the following changes to support this behavior:
1. Any views contributed to the Debug perspective via the
org.eclipse.ui.perspectiveExtensions extension point should add:
    visible="false"
to their extensions. Failing to do this will mean your views will always
appear in the Debug perspective. If everyone's views appear in the
perspective all the time, the perspective quickly becomes difficult to
manage (which defeats the purpose of all of this).
2. Create a context for your debugger via the org.eclipse.ui.contexts
extension point. For example, the JDT Debugger provides
"org.eclipse.jdt.debug.ui.debugging".
3. Bind your debug model(s) to the context(s) you defined via the
org.eclipse.debug.ui.debugModelContextBindings extension point.
3a. (Not necessary and uncommon) If you want contexts activated for
something other than stack frames or if you want to return different
identifiers than you give in IDebugElement#getModelIdentifier(), provide
an IDebugModelProvider adapter for your elements.
4. Create context-to-view bindings for views that should be displayed
for a context via the org.eclipse.debug.ui.contextViewBindings extension
point. Note that the optional autoClose and autoOpen attributes are
provided for rare cases and most debuggers shouldn't specify them.

##############################################################
# Actions (PROPOSAL)
##############################################################
Debugger specific actions are currently enabled via the Debug Action
Group support. This support was essentially a precursor to the
ACTIVITIES support now provided by the workbench (Platform-UI).

WE PLAN TO REMOVE SUPPORT FOR DEBUG ACTION GROUPS.

Language-specific actions should be managed by activities (at the
feature or product level). For example, someone shipping JDT would
provide a "Developing Java" activity that would automatically filter out
all views, actions, and preferences with identifier starting with the
prefix "org.eclipse.jdt.*"

Activities are activated either manually by the user or programatically
via "trigger points". For example, creating a new project is a trigger
point. Creating a C++ project might turn on a "Developing C++" activity.
Once this happens, all views and actions related to C++ become
available.

Multi-language debugging seems like it should be another trigger point
for activities. If you are "Developing Java" and you step into a C++
stack frame, it would seem to make sense to turn on the "Developing C++"
activity if it's not already on. As such, we plan to add an extension
point, org.eclipse.debug.ui.debugModelActivityBinding, similar to the
current debugModelCONTEXTBinding. The activity-binding extension point
would have the same semantics as the one for context-binding; when an
element in the Debug view is selected which maps to an activity, we
would turn on that activity.

(PROPOSAL) Debuggers should make the following changes to support this
behavior:
1. Remove all references to the org.eclipse.debug.ui.debugActionGroups
extension point.
2. At the feature or product level (see the workbench's Activity
documentation), provide activities for developing your language and
provide appropriate pattern filters for those activities such that your
actions will be filtered out until those activities are enabled.
3. Bind your debug elements to the appropriate activities via the
org.eclipse.debug.ui.debugModelActivityBinding extension point (not yet
implemented).

Provided these stories don't change, this information will show up in
the Debug UI schemas and Debug Core "3.0 Porting Guide" in the near
future.

Questions and comments are encouraged. M9 isn't far off and whatever we
have for M9 is basically what's going to ship in 3.0.

Thanks,
- Jared