| <html> |
| <head> |
| <title>3.1 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.1 Debug Platform Change Notes</h1> |
| <p>This document describes new features and important changes in the 3.1 debug |
| platform, relative to the 3.0 release.</p> |
| |
| <h2>New Features</h2> |
| |
| <h3> Breakpoint Organizers</h3> |
| <p>The breakpoints view allows breakpoints to be displayed in groups. The platform |
| supports breakpoint groupings by breakpoint type, file, project, and breakpoint |
| working sets and resource based working sets (as well, it supports nested groupings). |
| The <code>breakpointOrganizers</code> extension point allows for other grouping |
| strategies to be contributed to the debug platform.</p> |
| <p>A new, optional, <code>name</code> attribute has been added to the breakpoints |
| extension point to provide a type name for breakpoints. This name appears as |
| the group label, when the user chooses to group breakpoints by type. If this |
| attribute is not specified on a breakpoint extension, the breakpoints are considered |
| to not have a type, and will be displayed in the "Others" group.</p> |
| <h3>Logical Structure Providers</h3> |
| <p>Logical structures have been enhanced to allow clients to more easily contribute |
| more than one logical structure for a given value. The new extension point <code>logicalStructureProviders</code> |
| allows clients to contribute an implementation of an <code>ILogicalStrugureProvider</code>. |
| A logical structure provider provides a simple way to contribute a single factory |
| of logical structures for a debug model.</p> |
| <p>In addition the optional interface <code>ILogicalStructureTypeDelegate2</code> |
| has been added to allow a logical structure delegate to provide a dynamic label |
| for a value's logical structure type.</p> |
| <h3>Process Console Enhancements</h3> |
| <p>The debug console has been enhanced to allow output to be multiplexed between |
| the console and/or a file. As well, the encoding used to translate output to |
| characters can now be specified. All of these options are available to the user |
| on the "Common" launch configuration tab. As well, the options are |
| available programmatically as launch configuration attributes. The following |
| attributes have been added to <code>org.eclipse.debug.ui.IDebugUIConstants</code>.</p> |
| <ul> |
| <li><code>ATTR_CONSOLE_ENCODING</code></li> |
| <li><code>ATTR_CAPTURE_IN_CONSOLE</code></li> |
| <li><code>ATTR_CAPTURE_IN_FILE</code></li> |
| <li><code>ATTR_APPEND_TO_FILE</code></li> |
| </ul> |
| <h3>Memory View</h3> |
| <p>The Memory view, which was first released in 3.0 as internal API, has become |
| public API in 3.1. See the new extension point <code>memoryRenderings</code>, |
| and the new API package <code>org.eclipse.debug.ui.memory</code> for more information.</p> |
| <h3>Parse Arguments</h3> |
| <p>A convenience API method has been added to <code>DebugPlugin</code> to separate |
| arguments in a single string into an array of arguments that can be passed to |
| the command line for execution. See <code>DebugPlugin.parseArguments(String)</code>.</p> |
| <h3>Run To Line Handler</h3> |
| <p>Many debuggers implement "run to line" functionality by creating |
| a breakpoint at the line a user has chosen to "run to", and then resuming |
| execution until that breakpoint is hit. A new API class, <code>RunToLineHandler</code>, |
| has been created to simplify the task. The handler manages the "skip breakpoints |
| while performing run to line" user preference as well canceling the operation |
| if another breakpoint is hit before the "run to line" operation completes.</p> |
| <h3>Run To Line Action Delegate</h3> |
| <p>The <code>RunToLineActionDelegate</code> introduced in 3.0 can now also be |
| contributed to a view (in 3.0 it could only be contributed to an editor). The |
| action additionally implements <code>IViewActionDelegate</code>.</p> |
| <h3>Variable Value Editors</h3> |
| <p>A new extension point, <code>variableValueEditors</code>, allows debuggers |
| to contribute custom editors for modifying a variable's value selected in the |
| Variables view.</p> |
| <h3>Launch Shortcut Keybindings</h3> |
| <p>To register a key-binding for a launch shortcut, define a command with an <font face="Courier New, Courier, mono">id |
| </font>the same as the launch shortcut <font face="Courier New, Courier, mono">id</font>, |
| suffixed with the launch mode. For example, the id of the "Java Application" |
| launch short cut is <font face="Courier New, Courier, mono">org.eclipse.jdt.debug.ui.localJavaShortcut</font>, |
| so the command id for launching in debug mode is <font face="Courier New, Courier, mono">org.eclipse.jdt.debug.ui.localJavaShortcut.debug</font>. |
| Then define a key-binding for your command.</p> |
| <p>When the command is invoked via the key-binding, the selection or active editor |
| will be used as the target for the launch shortcut's launch method. The shortcut |
| is only invoked if the shortcut is enabled for the selection or editor.</p> |
| <h3>Source Lookup/Display Facility</h3> |
| <p>API methods have been added to <code>DebugUITools</code> to facilitate source |
| lookup and display. See the methods <code>lookupSource(Object, ISourceLocator)</code> |
| and <code>displaySource(ISourceLookupResult, IWorkbenchPage)</code>. When a |
| source lookup result for a stack frame is displayed, the open editor is also |
| annotated with an appropriate instruction pointer.</p> |
| <h3>Watchpoints (IWatchpoint) and Images</h3> |
| <p>As watchpoints are common to many debug architectures, the notion of an IWatchpoint |
| has been added to the debug model. A watch point is a breakpoint that suspends |
| execution when an associated variable is read and/or written. As well, default |
| images for rendering watchpoints have been added to the debug platform.</p> |
| <h3>Colors and Fonts for Debug Elements</h3> |
| <p>In 3.1, debug model presentations (<code>IDebugModelPresentation</code>) may |
| optionally implement <code>IColorProvider </code>and <code>IFontProvider </code>to |
| override default fonts and colors for debug elements.</p> |
| <h3>Inserting Elements into Debug View</h3> |
| <p>The Debug view allows for debug models to insert arbitrary elements into the |
| debug model element hierarchy. For example, the Java debugger now displays lock |
| information directly in the view. To override the default presentation in the |
| view, a debugger must provide an <code>IWorkbenchAdapter</code> or <code>IDeferredWorkbenchAdapter |
| </code>for the relevant element(s). The debug platform provides default adapters |
| for the standard debug elements.</p> |
| <p>Debug elements were always required to implement <code>IAdaptable</code>, and |
| now must be subclasses of <code>PlatformObject</code> in order for workbench |
| adapters to be properly registered and retrieved for debug elements.</p> |
| <h3>Abstract Debug Element</h3> |
| <p>An abstract implementation of a debug element is provided in 3.1 - <code>DebugElement</code>. |
| Clients implementing debug models may choose to subclass this class when implementing |
| debug models. The class provides convenience methods for firing debug events, |
| reporting exceptions, and retrieving adapters.</p> |
| <h3>Drop to Frame Platform Action/Interface</h3> |
| <p>The debug platform provides a "drop to frame" action and corresponding |
| capability interface (<code>IDropToFrame</code>). Debug elements supporting |
| the capability should implement this new interface to share the global action.</p> |
| <h3>Context Menu Launching in Editors</h3> |
| <p>Launching from the context menu (for example, "Run As > Java Application"), |
| is now available in editors (In 3.1, this was only available in the package |
| explorer and resource navigator). To leverage this feature, the editor input |
| associated with a executable file must have an <code>ILaunchable</code> adapter |
| registered for it.</p> |
| <h3>Support for Unregistered Launch</h3> |
| <p>The launch framework allows for a launch to be performed without registering |
| a launch object with the launch manager. An unregistered launch does not appear |
| in the Debug view. A new launch method has been added to <code>ILaunchConfiguration</code>, |
| accepting a boolean argument determining whether the launch should be registered |
| (<code>launch(String mode, IProgressMonitor monitor, boolean build, boolean |
| register)</code>), and a new method has been added to <code>ILaunchManager</code> |
| to determine if a launch is registered (<code>isRegistered(ILaunch launch)</code>).</p> |
| <h3>Reusable Breakpoint Ruler Toggle Actions</h3> |
| <p>Providing double-click breakpoint creation in an editor's vertical ruler is |
| a common feature for debuggers. The debug platform provides two actions to facilitate |
| this: <code>RulerToggleBreakpointActionDelegate </code>and <code>ToggleBreakpointAction</code>. |
| A debugger must contribute the <code>RulerToggleBreakpointActionDelegate</code> |
| to the appropriate editor (see javadoc for more details), and also register |
| an <code>IToggleBreakpointsTarget </code>adapter with the editor.</p> |
| <h3>Environment Variables Case Preservation</h3> |
| <p>Support has been added to <code>ILaunchManager</code> to retrieve the environment |
| variables defined in the OS preserving case. This is important on the WIN32 |
| operating system. Although WIN32 is case insensitive, depending on what you |
| intend to do with the environment, the lack of normalization may or may not |
| cause problems. This method <code>getNativeEnvironmentCasePreserved()</code> returns |
| mixed-case keys using the variable names recorded by the OS. Use <code>getNativeEnvironment()</code> |
| instead to get a WIN32 system environment where all keys have been normalized |
| to uppercase.</p> |
| <h3>Closing an Input Stream</h3> |
| <p>An optional extension, <code>IStreamsProxy2</code>, can be implemented by implementations |
| of <code>IStreamsProxy</code>. When implemented, it allows the input stream |
| associated with a process to be closed. This is used to allow the user to signal |
| EOF when typing in the console.</p> |
| <h3>Launch in Debug Mode when Workspace Contains Breakpoints</h3> |
| <p>Since 3.0, The user preference "Launch in debug mode when workspace contains |
| breakpoints" is used to control whether a launch should use debug mode |
| even when "run" is pressed by the user, based on the presence of breakpoints |
| in the workspace. A new method, <code>getBreakpoints(ILaunchConfiguration configuration)</code>, |
| has been added to the abstract implementation of <code>LaunchConfigurationDelegate</code>, |
| to determine which breakpoints should be considered as relevant for a particular |
| launch. By default, all breakpoints in the workspace are considered, but subclasses |
| may override. For example, the Java Application launcher only considers Java |
| breakpoints.</p> |
| <h3>Case Insensitive Source Lookup and Relative Paths</h3> |
| <p>The debug platform's source lookup facilities now lookup source in folders |
| and directories in a case insensitive manner on platforms that are case insensitive. |
| As well, relative path names are supported in folders and directories.</p> |
| <h2>Changes</h2> |
| <h3>Debug Event Dispatch</h3> |
| <p>In releases 3.0 and prior, calling <code>DebugPlugin.fireDebugEventSet(DebugEvent[])</code> |
| resulted in debug events being fired synchronously in the calling thread. In |
| 3.1, debug event set listeners are notified of debug events asynchronously in |
| a different thread than the event is reported in.</p> |
| <h3>Debug Actions and Content in Background Jobs</h3> |
| <p>In 3.1, many actions that call debug element APIs (like "stepOver"), |
| now create jobs to communicate with debug elements in background threads. This |
| avoids blocking the UI in the case that a debug element method requires communication |
| with a debug target that can block, hang, or timeout. Similarly, many of the |
| debug views populate their content using background jobs to avoid blocking the |
| UI thread. The net difference is that in 3.1, more than one thread might be |
| accessing a debug model's APIs where previously only the UI thread was.</p> |
| <h3>Contextual Launch from Top Level Run/Debug Menus</h3> |
| <p>The top level menus no longer support the perspective element, and launch shortcuts |
| must specify a "<code>contextualLaunch</code>" element to appear in |
| the Run/Debug cascade menus.</p> |
| <p> </p> |
| </body> |
| </html> |
