3.0 Debug Platform Change Notes

This document describes important changes in the 3.0 debug platform, relative to the 2.1 release.

New Features

Extensible Launch Modes

The debug platform supports an extensible set of launch modes. Releases prior to 3.0 only supported two launch modes - run and debug. The debug platform now provides an extension point for contributing new launch modes - org.eclipse.debug.core.launchModes. The debug platform now defines (contributes) three basic launch modes - run, debug, and profile. Other clients may contribute new launch modes. The launch manager (ILaunchManager) has additional API to retrieve all launch modes, and a human readable label for each launch mode.

The debug platform has a new extension point to support the contribution of a launch delegate for a specific launch configuration type and launch mode - org.eclipse.debug.core.launchDelegates. This allows launch configurations to be extended by third parties, to support new launch modes. For example, a client could contribute a launch delegate that launches a Java Application in profile mode (currently, the SDK does not provide a profiler).

For backwards compatibility, the launch delegate supplied by a launch configuration type extension is used for the launch modes specified by the launch configuration type. A launch delegate supplied for a specific mode, is used only for that mode.

The debug platform has added an optional element (launchMode), to the definition of a launch tab group extension - (org.eclipse.debug.ui.launchConfigurationTabGroup), to support the contribution of a set of tabs for a specific launch configuration type and launch mode. This allows third parties to extend an existing lauch configuration user interface. For example, a client contributing a launch delegate to profile a Java Application would also contribute a set of tabs to configure the profiler. The launchMode element defines a perpsective attribute to specify the default perspective assocaited with the launch configuration type and mode. This controls the perspective that is switched to/opened, by default, when a configuration is launched in the associated mode. For example, a client contributing a profiler may also contribute a profiling perspective that should be displayed when an application is profiled.

For backwards compatibility, the tab group contributed for a launch confiugration type (specifying no launch mode), is used for all launch modes for which a specific launch tab group is not contributed. Thus, when a mode is not specified by a tab group, the tab group effectively becomes the default tab group.

Extensible Debug Events

The debug platform supports an extensible set of debug events. A debug event kind of MODEL_SPECIFIC has been added in the 3.0 release to indicate an application specific debug event. When a debug event of kind MODEL_SPECIFIC is created, the detail code in the event is client defined. The source of the event (debug element that generated the event) identifies the debug model from which the event was generated. The debug platform and user interface ignores model specific debug events.

A data field has been added to debug events to allow clients to store application specific data in debug events.

Extensible Instruction Pointer Images

When a stack frame is selected in the debug view, the debugger opens a corresponding editor and displays an image in the editor ruler on the line that corresponds to the selected stack frame. In releases prior to 3.0, the images were provided by the debug plug-in and could not be overridden by a debug model. In release 3.0, a debug model presentation (IDebugModelPresentation) can provide specialized images by implementing the debug editor presentation interface (IDebugEditorPresentation).

Editor Positioning and Custom Decorations

In release 3.0, debug model presentations can control the positioning of editors opened by the debugger for a stack frame, and may add extra decorations to the editor for a stack frame (for example, custom background coloring, etc.). This can be acheived by having a debug model presentation implement the new interface IDebugEditorPresentation, and implementing the appropriate methods - selectAndReveal, decorateEditor, and removeDecorations.

Extensible Watch Expressions

In release 3.0, the debug platform provides an implementation of watch expressions. Debug models can contribute watch expression delegates if they support watch expressions. When a stack frame is selected, the associated delegate is queried to provide a value for a watch expression in the given (stack frame) context. The debug platform provides persistence, enabling, disabling, entering, and editing of watch expressions.

Process Factories

The debug platform provides an extension point (org.eclipse.debug.core.processFactories) for contributing process factories. A process factory can be used to override default process creation for a launch configuration when the debug plug-in (i.e. org.eclipse.debug.core.DebugPlugin) is consulted to create a new process. A launch configuration can reference a process factory to use when creating a process, via the launch configuration attribute DebugPlugin.ATTR_PROCESS_FACTORY_ID.

API Changes

Extensible Launch Modes

With the introduction of extensible launch modes, more than one launch delegate can exist for a launch configuration type. Releases prior to 3.0 only supported one launch delegate per launch configuration type. The method ILaunchConfigurationType.getDelegate() is now deprecated. The method getDelegate(String mode) should be used in its place to retrieve the launch delegate for a specific launch mode. The deprecated method has been changed to return the launch delegate for the run mode.

Launch Tabs & Tab Groups

Launch tab groups and launch tabs are no longer notified when a launch completes. The method launched(ILaunch) in the interfaces ILaunchConfigurationTab and ILaunchConfigurationTabGroup has been deprecated and is no longer called. Relying on this method for launch function was always problematic, since tabs only exist when launching is performed from the launch dialog. Also, with the introduction of background launching, this method can no longer be called, as the launch dialog is be closed before the resulting launch object exists.