| <html> |
| <head> |
| <title>3.0 Debug Platform Change Notes</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| </head> |
| |
| <body bgcolor="#FFFFFF" text="#000000"> |
| <h1>3.0 Debug Platform Change Notes</h1> |
| <p>This document describes important changes in the 3.0 debug platform, relative |
| to the 2.1 release.</p> |
| <h2>New Features</h2> |
| <h3> Extensible Launch Modes</h3> |
| <p>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 - <code>org.eclipse.debug.core.launchModes</code>. |
| The debug platform now defines (contributes) three basic launch modes - run, |
| debug, and profile. Other clients may contribute new launch modes. The launch |
| manager (<code>ILaunchManager</code>) has additional API to retrieve all launch |
| modes, and a human readable label for each launch mode.</p> |
| <p>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 - |
| <code>org.eclipse.debug.core.launchDelegates</code>. 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).</p> |
| <p>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. </p> |
| <p>The debug platform has added an optional element (<code>launchMode</code>), |
| to the definition of a launch tab group extension - <code>(org.eclipse.debug.ui.launchConfigurationTabGroup</code>), |
| 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 launch |
| 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 <code>launchMode</code> element defines a <code>perspective</code> |
| attribute to specify the default perspective associated 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.</p> |
| <p>For backwards compatibility, the tab group contributed for a launch configuration |
| 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.</p> |
| <h3>Extensible Debug Events</h3> |
| <p>The debug platform supports an extensible set of debug events. A debug event |
| kind of <code>MODEL_SPECIFIC</code> has been added in the 3.0 release to indicate |
| an application specific debug event. When a debug event of kind <code>MODEL_SPECIFIC</code> |
| 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.</p> |
| <p>A data field has been added to debug events to allow clients to store application |
| specific data in debug events.</p> |
| <h3>Extensible Instruction Pointer Images</h3> |
| <p>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 (<code>IDebugModelPresentation</code>) can provide |
| specialized images by implementing the debug editor presentation interface (<code>IDebugEditorPresentation</code>).</p> |
| <h3>Editor Positioning and Custom Decorations</h3> |
| <p>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 achieved by having a debug model presentation implement the new interface |
| <code>IDebugEditorPresentation</code>, and implementing the appropriate methods |
| - <code>selectAndReveal</code>,<code> decorateEditor</code>, and <code>removeDecorations</code>.</p> |
| <h3>Extensible Watch Expressions</h3> |
| <p>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.</p> |
| <h3>Process Factories</h3> |
| <p>The debug platform provides an extension point (<code>org.eclipse.debug.core.processFactories</code>) |
| 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.<code> |
| org.eclipse.debug.core.DebugPlugin</code>) 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 <code>DebugPlugin.ATTR_PROCESS_FACTORY_ID</code>.</p> |
| <h3>Automatic Array Partitioning</h3> |
| <p>The debug plug-in now supports automatic array partitioning in the variables, |
| which partitions large arrays into sub-ranges in the variables view. This is |
| supported with the introduction of a new interface in the debug model representing |
| an indexed value - <code>org.eclipse.core.debug.model.IIndexedValue</code>. |
| If a value implements this interface, the variables view will automatically |
| partition its elements as required, into sub-ranges</p> |
| <h3>Logical Structure Types</h3> |
| <p>Often, it is convenient to navigate complex data structures in terms of a logical |
| structure, rather than an implementation structure. For example, no matter how |
| a list is implemented (i.e. linked list, collection of arrays, etc.), it is |
| often convenient to be able to view the list as an ordered collection. To facilitate |
| the display of logical structures in the variables view, an extension point |
| has been added (<code>org.eclipse.debug.core.logicalStructureTypes</code>) allowing |
| debug models to contribute logical structures of its values, where applicable. |
| Debug models may contribute delegates to translate raw implementation values |
| into logical values. The variables view will display the logical values, when |
| the option to display logical structures is turned on. More than one logical |
| structure can be provided for a single value - the user can choose which structure |
| to display.</p> |
| <h2>API Changes</h2> |
| <h3>Extensible Launch Modes</h3> |
| <p>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 <code>ILaunchConfigurationType.getDelegate()</code> |
| is now deprecated. The method <code>getDelegate(String mode)</code> 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 |
| <code>run</code> mode.</p> |
| <h3>Launch Tabs & Tab Groups</h3> |
| <p>Launch tab groups and launch tabs are no longer notified when a launch completes. |
| The method <code>launched(ILaunch)</code> in the interfaces <code>ILaunchConfigurationTab</code> |
| and <code>ILaunchConfigurationTabGroup</code> 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.</p> |
| <h3>Perspective Switching</h3> |
| <p>In prior releases, perspective switching was specified on a launch configuration, |
| via the launch configuration attributes <code>ATTR_TARGET_DEBUG_PERSPECTIVE</code> |
| and <code>ATTR_TARGET_RUN_PERSPECTIVE</code>. With the addition of extensible |
| launch modes in 3.0, this approach no longer scales. Perspective switching is |
| now specified on launch configuration type basis, per launch mode that a launch |
| configuration type supports. API has been added to <code>DebugUITools</code> |
| to set and get the perspective associated with a launch configuration type for |
| a specific launch mode.</p> |
| <p>An additional, optional, <code>launchMode</code> element has been added to |
| the <code>launchConfigurationTabGroup</code> extension point, allowing a contributed |
| tab group to specify a default perspective for a launch configuration type and |
| mode.</p> |
| <p>From the Eclipse user interface, users can edit the perspective associated |
| with a launch configuration type by opening the launch configuration dialog, |
| and selecting a launch configuration type node in the tree (rather than an individual |
| configuration). A tab is displayed allowing the user to set a perspective with |
| each supported launch mode.</p> |
| <h3>Generic Console</h3> |
| <p>With the work for the generic console support <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=37263"> |
| (Bug 37263)</a>, the view id for the Eclipse (formerly debug) console has changed. |
| This results in problems at startup such as "Could not restore workbench layout" |
| with details that "Could not create view: org.eclipse.debug.ui.ConsoleView" |
| for the particular perspective that contained reference to the old view id. |
| The equivalent view id is now: "org.eclipse.ui.console.ConsoleView".<br> |
| The generic console is available via the Window>Show View>Basic>Console and |
| is used by the Eclipse debug and Ant integration. </p> |
| <h3>Console Line Tracker Extension</h3> |
| <p>A console line tracker (<code>IConsoleLineTracker</code>) can be notified when |
| its associated console is closed (i.e. all of its streams are closed), by implementing |
| the new interface <code>IConsoleLineTrackerExtension</code>. The notification |
| indicates that no more output will be appended to the console.</p> |
| <h3>Launch Configuration Tab Enhancements</h3> |
| <p>Two methods have been added to the <code>ILaunchConfigurationTab</code> interface |
| - activated and deactivated. These new life cycle methods are called when a |
| tab is entered and exited respectively. Existing implementations of <code>ILaunchConfigurationTab</code> |
| that subclass the abstract class provided by the debug plug-in (<code>AbstractLaunchConfigurationTab</code>) |
| will maintain binary compatibility, as the methods have been added in the abstract |
| class.</p> |
| <p>In prior releases, a tab was sent the message <code>initializeFrom</code> when |
| it was activated, and <code>performApply</code> when it was deactivated. In |
| this way, the launch configuration tab framework provided inter-tab communication |
| via a launch configuration (by updating the configuration with current attribute |
| values when a tab is exited, and updating the newly entered tab). However, since |
| many tabs do not perform inter-tab communication, this can be inefficient. As |
| well, there was no way to distinguish between a tab being activated, and a tab |
| displaying a selected launch configuration for the first time. The newly added |
| methods allow tabs to distinguish between activation and initialization, and |
| deactivation and saving current values. </p> |
| <p>To avoid breaking the behavior of current tab implementations, the default |
| implementation of <code>activated</code>, provided by the abstract tab, calls |
| <code>initializeFrom</code>. And, the default implementation of <code>deactivated</code> |
| calls <code>performApply</code>. Tabs wishing to take advantage of the new API |
| should override these methods as required. Generally, for tabs that do not perform |
| inter-tab communication, a correct implementation of these methods is to do |
| nothing.</p> |
| </body> |
| </html> |
