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).
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
allows clients to contribute an implementation of an
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
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
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
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
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,
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.
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
A new extension point,
variableValueEditors, allows debuggers
to contribute custom editors for modifying a variable's value selected in the
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
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 (
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
for the relevant element(s). The debug platform provides default adapters
for the standard debug elements.
Debug elements were always required to implement
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 -
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
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
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
to determine if a launch is registered (
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
A debugger must contribute the
to the appropriate editor (see javadoc for more details), and also register
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
mixed-case keys using the variable names recorded by the OS. Use
instead to get a WIN32 system environment where all keys have been normalized
An optional extension,
IStreamsProxy2, can be implemented by implementations
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,
has been added to the abstract implementation of
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
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
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.