This document describes new features and important changes in the 3.1 debug platform, relative to the 3.0 release.
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 breakpointOrganizers extension point allows for other grouping
strategies to be contributed to the debug platform.
A new, optional, name 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.
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 logicalStructureProviders
allows clients to contribute an implementation of an ILogicalStrugureProvider.
A logical structure provider provides a simple way to contribute a single factory
of logical structures for a debug model.
In addition the optional interface ILogicalStructureTypeDelegate2
has been added to allow a logical structure delegate to provide a dynamic label
for a value's logical structure type.
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 org.eclipse.debug.ui.IDebugUIConstants.
ATTR_CONSOLE_ENCODINGATTR_CAPTURE_IN_CONSOLEATTR_CAPTURE_IN_FILEATTR_APPEND_TO_FILEThe Memory view, which was first released in 3.0 as internal API, has become
public API in 3.1. See the new extension point memoryRenderings,
and the new API package org.eclipse.debug.ui.memory for more information.
A convenience API method has been added to DebugPlugin to separate
arguments in a single string into an array of arguments that can be passed to
the command line for execution. See DebugPlugin.parseArguments(String).
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, RunToLineHandler,
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.
The RunToLineActionDelegate 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 IViewActionDelegate.
A new extension point, variableValueEditors, allows debuggers
to contribute custom editors for modifying a variable's value selected in the
Variables view.
To register a key-binding for a launch shortcut, define a command with an id the same as the launch shortcut id, suffixed with the launch mode. For example, the id of the "Java Application" launch short cut is org.eclipse.jdt.debug.ui.localJavaShortcut, so the command id for launching in debug mode is org.eclipse.jdt.debug.ui.localJavaShortcut.debug. Then define a key-binding for your command.
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.
API methods have been added to DebugUITools to facilitate source
lookup and display. See the methods lookupSource(Object, ISourceLocator)
and displaySource(ISourceLookupResult, IWorkbenchPage). When a
source lookup result for a stack frame is displayed, the open editor is also
annotated with an appropriate instruction pointer.
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.
In 3.1, debug model presentations (IDebugModelPresentation) may
optionally implement IColorProvider and IFontProvider to
override default fonts and colors for debug elements.
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 IWorkbenchAdapter or IDeferredWorkbenchAdapter
for the relevant element(s). The debug platform provides default adapters
for the standard debug elements.
Debug elements were always required to implement IAdaptable, and
now must be subclasses of PlatformObject in order for workbench
adapters to be properly registered and retrieved for debug elements.
An abstract implementation of a debug element is provided in 3.1 - DebugElement.
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.
The debug platform provides a "drop to frame" action and corresponding
capability interface (IDropToFrame). Debug elements supporting
the capability should implement this new interface to share the global action.
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 ILaunchable adapter
registered for it.
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 ILaunchConfiguration,
accepting a boolean argument determining whether the launch should be registered
(launch(String mode, IProgressMonitor monitor, boolean build, boolean
register)), and a new method has been added to ILaunchManager
to determine if a launch is registered (isRegistered(ILaunch launch)).
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: RulerToggleBreakpointActionDelegate and ToggleBreakpointAction.
A debugger must contribute the RulerToggleBreakpointActionDelegate
to the appropriate editor (see javadoc for more details), and also register
an IToggleBreakpointsTarget adapter with the editor.
Support has been added to ILaunchManager 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 getNativeEnvironmentCasePreserved() returns
mixed-case keys using the variable names recorded by the OS. Use getNativeEnvironment()
instead to get a WIN32 system environment where all keys have been normalized
to uppercase.
An optional extension, IStreamsProxy2, can be implemented by implementations
of IStreamsProxy. 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.
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, getBreakpoints(ILaunchConfiguration configuration),
has been added to the abstract implementation of LaunchConfigurationDelegate,
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.
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.
In releases 3.0 and prior, calling DebugPlugin.fireDebugEventSet(DebugEvent[])
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.
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.
The top level menus no longer support the perspective element, and launch shortcuts
must specify a "contextualLaunch" element to appear in
the Run/Debug cascade menus.