myslide1

Debug Platform: The Basics Darin Wright, Curtis Windatt IBM Rational Software March 17 th , 2008

Tutorial Structure This tutorial is arranged as a set of modules A simple example debugger is provided with a set of exercises To get the most from this tutorial you should work on the exercises on your own time Use the example source code for reference :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse org.eclipse.debug.examples.core org.eclipse.debug.examples.ui There are two tutorials “ (1) The Basics ” and “(2) Custom Integration ” Modules in “Custom Integration” build on information from this tutorial

Modules – The Basics Debug Platform Overview The Standard Debug Model The Launch Framework Breakpoints Source Lookup The Variables View and More

Module 1: Debug Platform Overview

A Platform Was Born Hypothesis A platform for building integrated tools should support integrated debuggers Most debuggers are very similar A debuggable process made up of threads, stack frames, variables, etc., with common functions like stepping, terminating, suspending, etc. The platform should provide Abstractions for the common entities and functions (interfaces that will be implemented by each debugger) A user interface that works against the abstractions and functions (debug, variables, breakpoint views with standard debug toolbar) Sales pitch All you have to do is provide an implementation of the core interfaces specific to your debug architecture, and you get basic a debugger without writing any UI code

Facilities and Frameworks Launch Framework Source Lookup Framework Standard I/O Console Standard Debug Model Breakpoint Management Perspective, Views, Actions Expression Management

Building a Debugger (from 30,000 feet) The platform provides: Interfaces defining processes, threads, frames, stepping… Views and actions to display and act on the model elements You provide: An implementation of the common interfaces A label provider to render your model elements Standard Debug Model

Building a Debugger (from 30,000 feet)

Building a Launcher The platform provides: Persistence of launch settings (launch configurations) and a dialog for editing launch settings You provide: An implementation of a launcher that initiates a debug session and instantiates your debug model A set of tabs to edit your launch settings Launch Framework

Building Breakpoints The platform provides: An abstract base class to subclass, breakpoint persistence, standard enable/disable actions, breakpoints view Retargettable actions for toggling breakpoints You provide: Concrete implementations of breakpoints specific to your debugger Implementation of a ‘breakpoint toggler’ to create/delete your breakpoints Breakpoint Management

Integrating Source Display The platform provides: Interface and implementation of a source locator that finds source files on a search path by name Standard icons and highlighting for painting the instruction pointer in a text editor You provide: The search path for a debug session The filename to search for and line number to highlight (given a suspended debug context) An editor (if needed) Source Lookup Framework

The Center Of The Universe A debugger revolves around the “active debug context” The “active debug context” is the selection in the debug view – a frame, thread, etc. This context drives source lookup, visible variables and registers, and action enablement Each workbench window has a “Debug Context Service” A service provides change notification whenever the active context changes Whenever the context changes, interested parties update

Providers and Listeners Debug View Selection Actions Source Lookup IDebugContextService Context activated Context activated Provides context (context service per window)

Context Providers The platform allows for multiple “debug context providers” per window The platform provides one context provider – the Debug view You could implement additional context providers if needed The “debug context” for a window comes from the active provider A context provider is usually associated with a workbench part The active provider is The active part (if it is a provider) Or the most recently active part that is a provider Context providers generate DebugContextEvent ’s as the active context changes

Context Listeners Context listeners register with a context service (window) for change notification Receive DebugContextEvent ’s each time the context changes Listeners can register for change notification in a specific part, an entire window, or from all windows Examples: View toolbar actions listen to a specific part Window menu actions listen to their window Source lookup listens to the window Modeled on the workbench selection service

PDA Example Debugger PDA (Push Down Automaton) Assembly language with an interpreter written in Perl Send request to the interpreter over one socket Read events over another socket var n pop $n push $n branch_not_zero gt0 push 1 return :gt0 …

Module 2: The Standard Debug Model Standard Debug Model

Introduction The Eclipse “Standard Debug Model” contains the basic abstractions common to imperative execution environments Process, Thread, Stack Frame, Variable, Register, Breakpoint, … The Eclipse Debug UI interacts with these abstractions Plug-in debuggers provide implementations

Custom Debugger Integration The standard debug model doesn’t represent all architectures For example, embedded hardware models are different – often there are multiple processors in multi-core, possibly with DSP configurations The platform provides support to integrate non-standard debuggers into the common views and actions We look at this in the “Custom Integration” tutorial

Introduction - Remote Targets The standard model has synchronous APIs abstracting remote connections/communication

The Players Debug Model Elements The program being debugged Capabilities Support for stepping, resuming, terminating, etc. Debug Events Describe happenings in an executing target or process Debug Model Presentation Provides labels and images for debug model elements

Debug Model Elements The standard debug model contains Debug Target IDebugTarget Threads IThread Stack Frames IStackFrame Variables IVariable Register Groups IRegisterGroup Variables, in this context contain Values ( IValue ), which can contain other variables to represent complex data structures A register group contains Registers ( IRegister ), which are just variables

Capabilities The standard debug capabilities are Step (over, into, return) IStep Terminate ITerminate Suspend & Resume ISuspendResume Disconnect IDisconnect Drop to Frame IDropToFrame The standard debug elements implement standard capabilities IDebugTarget extends ITerminate, ISuspendResume, IDisconnect IThread extends ITerminate, ISuspendResume, IStep IStackFrame extends ITerminate, ISuspendResume, IStep

Debug Model Elements and Capabilities

Debug Events A debug event describes something that has happened in a program being debugged An event has a type (kind) and detail code The user interface requires debug model elements and process implementations to generate debug events. For example: IProcess – CREATE, TERMINATE IDebugTarget – CREATE, TERMINATE, SUSPEND, RESUME IThread – CREATE, TERMINATE, SUSPEND, RESUME Required events are specified in the DebugEvent class

Debug Events Detail codes describe why an event occurred: A suspend could be caused by: STEP_END, BREAKPOINT, CLIENT_REQUEST, EVALUATION, EVALUATION_IMPLICIT A resume could be caused by: STEP_INTO, STEP_OVER, STEP_RETURN, CLIENT_REQUEST, EVALUATION, EVALUATION_IMPLICIT The debug platform provides event notification DebugPlugin.fireDebugEventSet(DebugEvent[] events) DebugPlugin.addDebugEventListener(IDebugEventSetListener listener)

Debug Events (more) Event notification is performed in a separate thread Events are queued and fired A debug event set contains all events that occurred at the same location in a program Most of the time and event set contains one event You could describe simultaneous events – for example, a step completing at the same location as a breakpoint

Events and Views Viewer Standard Model Event Listener add, remove refresh, select expand debug events

Debug View Updates IDebugTarget CREATE – expands the target TERMINATE – updates the label RESUME – select target, update label, refresh children SUSPEND – update label, refresh children IThread CREATE – adds the thread TERMINATE – removes the thread

Debug View Updates (more) IThread.RESUME Client request Update label, refresh children (should remove them), select Expecting suspend – i.e. step or evaluation Do nothing, until timeout (500ms) or suspend is received Timeout causes thread select & refresh (removes frames) IThread.SUSPEND Client request/Breakpoint Update thread label, expand, refresh children, select top frame Step end Update thread label, select top frame, update top frame label

Debug Model Presentation Debug model elements are displayed with text and images Standard images are provided by the platform Default labels are just element names (for example, IThead.getName() ) To provide custom labels and images Contribute a <debugModelPresentation> extension Provide corresponding implementation of IDebugModelPresentation , which is an ILabelProvider :

PDA Example The PDA debugger provides implementations of: IDebugTarget : PDADebugTarget IThread : PDAThread IStackFrame : PDAStackFrame IVariable : PDAVariable IValue : PDAValue Although PDA is single threaded, we provide an implementation of a model with one thread to conform to the standard model

PDA Implementation Communication between the PDA debug model and interpreter is performed by writing a request and reading a reply over a socket (simple, not robust) public String sendRequest(String request) throws DebugException { synchronized ( fRequestSocket ) { fRequestWriter .println(request); fRequestWriter .flush(); try { // wait for reply return fRequestReader .readLine(); } catch (IOException e) { requestFailed( "Request failed: " + request, e); } } return null ; }

PDA Debug Protocol Protocol documented in: org.eclipse.debug.examples.core/pdavm/docs/ protocol.html For example, to issue a step command, “ step ” is sent over the request socket and “ ok ” is returned to indicate the step request was received Events are sent over a separate socket and are documented in IPDAEventListener : The PDA debug target starts an event reader on the event socket and processes events For example, a step request results in two events – a “ resumed step ” event and a “ suspended step ” event.

Tip All PDA debug elements subclass PDADebugElement which subclasses DebugElement (an abstract class provided by the debug platform) The platform’s abstract class provides convenience methods for firing events, reporting exceptions, retrieving adapters, and debug target and launch accessors PDA’s abstract class provides convenience methods for sending requests to the interpreter and providing a debug model identifier

Summary Implement Debug model Implement debug elements: IDebugTarget , IThread , IStackFrame … Implement supported capabilities: IStep , ITerminate … Ensure model fires required DebugEvents Contribute an IDebugModelPresentation to the <debugModelPresentations> extension point

Module 3: The Launch Framework Launch Framework

Introduction Running and debugging code is fundamental to an IDE To run and debug, we have to launch The launch framework includes facilities for Spawning an O/S process Persisting information about how something is launched A framework for editing launch parameters (GUI) An extensible set of launch modes (run, debug, profile…) Selection sensitive actions for launching

Launching Players Launch Manager Manages types, configurations, and launch notifications Launches Container for launched targets and/or processes Launch Configuration Types The type of what to launch Launch Configurations Persisted description of what to launch Launch Delegates What actually performs the launch Launch Modes The modes to launch in

Launch Players – Continued Tab Groups UI for editing launch configurations Tabs UI contributions to tab groups Launch Shortcuts Context sensitive action for launching

Launch Manager Manages all launch configurations, configuration types and launches Can be queried for all available launch configurations Can be queried for all registered configuration types Can be queried for all registered launch modes Launches are registered/deregistered with the manager Provides change notification for launches Also manages all registered source container types, source path computers and creates source locaters (module 5)

Launches Container of processes and debug targets created by launching The debug platform provides a standard implementation of IProcess based on java.lang.Process Provides convenience methods for launching/creating an IProcess from a command line Allows you to provide your own implementation if desired The debugger provides a console to display the standard I/O streams of a process For each IProcess added to an ILaunch , the debug platform allocates a console attached to its I/O streams std.out and std.err are written in blue and red Keyboard is attached to std.in - input is buffered and written to std.in when <Enter> is pressed

Launch Configuration Types Each launch configuration is of a specific type e.g. Java Application The <launchConfigurationTypes> extension point Allows new launch types to be contributed to the platform All contributed launch types are available from the launch manager The platform provides the only implementation of launch configuration types – ILaunchConfigurationType . Each extension can contribute a launch delegate

Launch Configuration Types – Continued Each launch type has domain specific attributes associated with it, which are stored in individual launch configurations E.g. Java applications have attributes like main type whereas PDE has a set of plug-ins Each type can also provide: The id of a specific source path computer to use The id of a specific source locator to use (more on these in module 5)

Launch Configurations Description of how and what to launch Persisted map of keys and values The platform provides the only implementation of launch configurations – ILaunchConfiguration and ILaunchConfigurationWorkingCopy A launch configuration is read-only – a working copy is used to edit a configuration in a transaction-like manor A working copy is created from a launch configuration, can be nested (new) Launch tabs modify a working copy and can commit changes to the original or revert Designed to be shared across different launch modes For example, a launch configuration describes how to launch a Java application (main type, etc.), but can be launched in run, debug, or other modes, or combinations of modes (more on this later)

Lazy Launch Configurations The launch configuration (state) and launch delegate (behavior) are separated to promote lazy loading of plug-ins. The debug platform provides one implementation of launch configurations so they can be loaded and visible in the launch history without loading the launch delegates until/if they are needed to perform an actual launch. Launch configuration type images Contributed to the <launchConfigurationTypeImages> extension point Allows us to display images in history without loading your plug-in

Launch Configurations – Continued Launch configurations can be mapped to a set of resources Allows launch configurations to be shown as a property of a resource (property page) Clients must manage the resource mapping Launch configurations can be migrated Facilitates upgrading existing launch configurations to support new features Contributed by new optional <migrationDelegate> attribute on the launch configuration types extension point Must implement ILaunchConfigurationMigrationDelegate

Launch Delegates A launch configuration type contributes a launch delegate for specific launch modes Implements ILaunchConfigurationDelegate E.g. the Java debugger contributes a launch delegate for run and debug modes for Java applications The debug platform provides an abstract launch delegate that should be sub-classed. The abstract delegate ( LaunchConfigurationDelegate ) provides infrastructure to perform: Scoped builds before launching, allowing subclasses to specify the set of projects that should be compiled. Scoped search for errors/problems, allowing the launch to be aborted Scoped search for unsaved editors, allowing the editors to be saved

Launch Modes The debug platform has an extensible set of launch modes A mode represents the way a user has chosen to launch Delegates are passed the mode when launching The platform defines three launch modes: run, debug, profile Use the <launchModes> extension point to contribute others

Launch Sequence Launch Config The Launch Launch Manager Launch Delegate IProcess IDebugTarget Mode System Process Creates Registered In Creates Wrapped By Children

Extending Existing Types Launch configurations can be extended by other tools Example, a new launch mode like profiling for Java applications The <launchDelegates> extension point Allows a launch delegate to be contributed to an existing launch configuration type for a specific launch mode, or set of launch modes E.g., a tool can contribute a launch delegate for launching Java applications in profile mode, even though the base SDK does not support profiling. The <launchConfigurationTabGroups> extension point allows a tab group added for an existing configuration type for a specific mode

Extending Existing Types and Modes Pre-3.3 you could launch in one mode Run or Debug, etc If you wanted to provide additional capabilities, for example code coverage while debugging You would have to create a new type, delegate, mode, tabs, etc Since 3.3, you can launch in mixed modes There is a primary mode (run, debug, etc.) chosen by the user, and secondary modes provided by tooling (eg. code coverage) The secondary modes are set into the configuration A launch delegate can be contributed for mode combinations Additional tabs can be contributed to existing tab groups

Tab Groups A set of tabs is used to display and edit a single launch configuration Displayed in the launch dialog when a configuration is selected Tabs operate on a launch configuration working copy in a transaction-like manor – can commit or revert Contributed via the <launchConfigurationTabGroups> extension point Often the same set of tabs is used for all launch modes, but the extension point provides a <mode> attribute to allow a tab group to be contributed for a specific mode

Tabs Tabs Provide SWT controls to edit launch configurations attributes (state) Normally instantiated by a tab group The platform provides an abstract class – AbstractLaunchConfigurationTab Which should be used to create your tabs for your tab group Which also provides basic functionality for all launch tabs The <launchConfigurationTabs> extension point Is used to contribute a single tab to an existing tab group Can have an associated launch delegate Can have a relative placement Contributed tabs can be placed ‘after’ another existing tab

Tabs – Continued Example contributed tab to the Java Application tab group Placed after the Main tab With associated launch delegate <extension point="org.eclipse.debug.ui.launchConfigurationTabs"> <tab class="org.eclipse.example.ui.MyTab" group="org.eclipse.jdt.debug.ui.launchConfigurationTabGroup.localJavaApplication" id="org.eclipse.example.ui.myTab" name=“My Tab"> <placement after="org.eclipse.jdt.debug.ui.javaMainTab"></placement> <associatedDelegate delegate="org.eclipse.example.mydelegate"> </associatedDelegate> </tab> </extension>

Launch Shortcuts Launch shortcuts are added to the Run As… context menu Provides a simple way for users to launch a file/program Creates a configuration (if one does not already exist), and launches it Contributed via the <launchShortcuts> extension point Launch shortcuts provide enablement expressions Specify when it should be enabled for a selection in the workbench (i.e. appear in the Run As… context menu) Enablement expressions are XML boolean expressions that are common to many extension points The debug platform provides some property testers Filename pattern matching, file content type, project nature, etc.

Improving the User Experience History: In the beginning there was only the Launch Dialog and launch history In 2.0 we added Launch Shortcuts in context menu In 3.3 we added Contextual launch Press run or debug to launch the selection appropriately Contextual Launch Best approximation at launching an existing configuration associated with the selection/editor, or choosing the best launch shortcut to launch the selection/editor

What’s a “Best Approximation”? The most recently launched configuration in the history associated with the selection, or its project. Based on resource mapping provided by launch configuration If there are none, we prompt the user to choose a launch shortcut to launch the selection/editor Based on enablement expressions Helps if you provide launch shortcut descriptions (new attribute added in 3.3 displayed in prompt dialog)

But, I don’t launch IResources … To override default resource mappings and support contextual launch for non-resource based models we added an optional extension ILaunchShortcut2 in 3.4 Allows client to provide resource and/or launch configuration mappings for editors and selections

Got Two Profilers? Pre-3.3 similar tooling could cause conflicts Differing launch delegates for same mode E.g. we could have two profilers that both contributed a launch delegate for Java Application in debug mode Differing contributors for the same tab group in the launch dialog E.g. we could have two profilers (again) that both contribute a tab group to Java Application Pre-3.3 there was no way to differentiate the previous cases Launch delegates and tab group to use would be selected non-deterministically

Preferred Launch Delegates Preference page shows conflicting tooling by launch configuration type User selects preferred delegate User is prompted to choose preferred delegate at launch time if not already chosen

Summary Contribute any <launchConfigurationTypes> Specify migration delegate if needed (upgrade resource mappings) Implement ILaunchConfiugrationDelegate Contribute with <launchConfigurationType> or use <launchDelegates> for existing types Contribute <launchConfigurationTabGroups> Or use <launchConfigurationTabs> for existing tab groups Implement tabs extending from AbstractLaunchConfigurationTab Maintain resource mappings for contextual launch Contribute <launchShortcuts> Provide enablement expressions Consider ILaunchShortcut2 for contextual launch

Module 4: Breakpoints Breakpoint Management

Introduction What are breakpoints? A way to suspend execution at a specified location or upon a specified condition. Line breakpoints, Watchpoints, Run-to-Line, and Exception Traps are kinds of breakpoints. The breakpoint framework provides facilities for: Add, remove, change notification Persistence of breakpoints across workbench invocations Temporarily skipping breakpoints Retargetable actions for creating breakpoints Exporting and importing breakpoints to/from a file

Introduction Continued The types of breakpoints a debugger provides depends on: The capabilities provided by the underlying debug architecture Aggregate functions that can be built with those capabilities Examples Implementing run-to-line with line breakpoints Implementing hit counts on the client side Implementing conditional breakpoints with client side evaluations

Breakpoint Players Breakpoint extension point Extension point for contributing kinds of breakpoints Breakpoint Model object representing an instance of a breakpoint Marker Used to persist a breakpoint’s attributes and display a breakpoint in an editor Breakpoint Manager Breakpoint repository, provides change notification Debug Target Installs breakpoints in underlying runtime

More Breakpoint Players Retargettable actions Actions for toggling breakpoints in editor/active selection Editor Displays markers in vertical ruler Debug Model Presentation Renders breakpoints Breakpoint properties dialog Editing breakpoint properties

Breakpoint Extension Point The platform provides an extension point for contributing kinds of breakpoints <extension point="org.eclipse.debug.core.breakpoints"> <breakpoint class="example.debug.core.breakpoints.PDALineBreakpoint" name="PDA Line Breakpoints" markerType="example.debug.core.pda.markerType.lineBreakpoint" id="pda.lineBreakpoint"/> </extension>

Breakpoint Model object representing a breakpoint All breakpoints implement IBreakpoint The platform also defines base interfaces for ILineBreakpoint and IWatchpoint A breakpoint contains the information required to install itself into a debug target All implementations must have a default constructor such that the platform can instantiate persisted breakpoints on workspace startup The platform provides abstract classes that must be sub-classed when implementing breakpoints – Breakpoint and LineBreakpoint .

Breakpoint Continued The platform’s implementation provides enablement and attribute persistence A breakpoint’s attributes are stored in a marker Breakpoint behavior is provided by client implementations I.e. Custom properties, installation, adhering to enablement For example, the Java debugger supports: Line breakpoints, watchpoints, method breakpoints, exception breakpoints, class load breakpoints Hit counts, suspend VM vs. thread, conditions, thread filters, location filters, instance breakpoints, suspend on caught vs. uncaught An API for creating and configuring these breakpoints Property pages and actions for editing Java breakpoint properties

Breakpoint Mechanisms The actual mechanism used to suspend execution on a debuggable process differs between debug architectures E.g. JVM debug interface accepts requests to suspend execution at specific line number in a class file This only works when line number debug attributes are present in the class file An IBreakpoint simply stores the information required to install a breakpoint in a specific architecture For example, a Java line breakpoint stores a fully qualified type name and line number. When added to a target, we first check if the corresponding class is loaded, and if so make a request to suspend at the associated location. If not loaded, we ask to be notified when the class is loaded and install the request later (deferred breakpoint).

Marker Breakpoint attributes are stored in markers IMarker ’s are provided by the platform as general purpose “markers” in files (book marks, compilation errors, etc), that can be displayed in an editor ruler An marker is just a store of key/value pairs of primitive data types The platform provides the only implementation of IMarker Breakpoint behaviors are implemented in IBreakpoint ’s To provide complex breakpoint behavior, debuggers provide implementations of IBreakpoint All breakpoints have an associated marker to persist it attributes and display in an editor

Marker Continued Contribute marker extension associated with breakpoint type Notes Must specify persistent as true if you want your breakpoints to be persisted Must specify attributes you want persisted <extension id="commonJavaLineBreakpointMarker" point="org.eclipse.core.resources.markers"> <super type="org.eclipse.jdt.debug.javaBreakpointMarker“/> <super type="org.eclipse.debug.core.lineBreakpointMarker“/> <persistent value="true“/> <attribute name="org.eclipse.jdt.debug.core.typeName“/> <attribute name="org.eclipse.jdt.debug.core.installCount“/> <attribute name="org.eclipse.jdt.debug.core.hitCount“/> <attribute name="org.eclipse.jdt.debug.core.expired“/> </extension>

Breakpoint Manager The breakpoint manager ( IBreakpointManager ) is a repository of breakpoints in the workspace When a breakpoint is created, it is registered with the manager When a breakpoint is deleted, it is removed from the manager Provides change notification as breakpoints are added, removed, and when a breakpoint attribute changes Clients interested in breakpoints Implement IBreakpointsListener and register with the manager For example, debug targets listen for change notification so they can install/remove/update breakpoints as they change Clients should also register as IBreakpointManagerListener ’s Notified when the breakpoint manager has been disabled/enabled This feature allows all breakpoints to be temporarily disabled with out changing the enablement state of individual breakpoints (i.e. skip breakpoints)

Debug Target The debug target installs breakpoints IDebugTarget extends IBreakpointListener When a debug target is created, it should query the breakpoint manager for all existing relevant breakpoints and install them (deferred breakpoints) Listens for breakpoints being added/removed/changed during its lifecycle, and updates them in the underlying runtime

Retargettable Actions Most debuggers support a common set of breakpoint types Line breakpoints, method breakpoints, and watchpoints Global actions are provided for creating these kinds of breakpoints Promotes a common look and feel across debuggers Avoids polluting menus with similarly named actions

Retargetting How does it work? The global actions ask the active editor, view, or selection for its IToggleBreakpointsTarget adapter. Debuggers register adapters with the appropriate editors, views, objects. Actions interact with adapter to determine action enablement and toggle breakpoints Action Editor View Selection { }

The Editor The editor visualizes the location of breakpoint/watchpoints Displays markers in vertical ruler and updates as markers are changed Provides adapter to hook into the retargetable breakpoint actions Editors that subclass AbstractDecoratedTextEditor have a ruler to display markers associated with the file (resource) they are editing

Debug Model Presentation The IDebugModelPresentation associated with the debug model provides image and label for breakpoints in editors and the Breakpoints view Each time a breakpoint attribute changes the breakpoints image and text are updated

Editor & Double Click Toggle The debug platform provides an action that can be contributed to editors to enable “double click” breakpoint toggling The action interacts with the editor’s IToggleBreakpointsTarget Contribute the action to your editor with the special RulerDoubleClick action identifier <extension point="org.eclipse.ui.editorActions"> <editorContribution targetID="pda.editor" id="pda.rulerActions"> <action label="Not Used" class="org.eclipse.debug.ui.actions. RulerToggleBreakpointActionDelegate " style="push" actionID=" RulerDoubleClick " id="pda.doubleClickBreakpointAction"/>

Breakpoint Properties Breakpoints have editable properties Hit count Suspend policy Enablement Condition Breakpoint editors are not currently provided by the platform The Java debugger provides its own

Breakpoint Summary Determine the kinds of breakpoints your debugger will support and contribute an <breakpoint> extension for each Create an implementation of IBreakpoint for each Define the <marker> extension associated with each breakpoint kind, enumerating attributes Implement breakpoint installation in your debug target via its IBreakpointListener interface Implement IBreakpointManagerListener in your debug target to support “skip breakpoints” Ensure that you have a source code editor; this can be as simple as a subclass of the standard TextEditor Create an implementation of an IToggleBreakpointsTarget adapter using, and register the adapter with your editor Contribute a RulerToggleBreakpointActionDelegate to your editor using the <editorActions> extension point Provide images and labels in model presentation Create breakpoint properties editor if desired

Module 5: Source Lookup Source Lookup Framework

Introduction Highlighting the current source code line or statement The debugger has to find source code for a binary location and display that source code in the editor. Typically, finding source code means looking for a particular file along a path of directories (or zips or jars or databases or …)

Source Lookup Players Launch each launch has a source locator Source Locator locates source element for a stack frame Stack Frame provides context for source lookup Debug Model Presentation provides editor mapping for source element

The Basic Source Lookup Interaction A stack frame is selected The source locator finds a source element for a stack frame The debug model presentation maps the source element to an editor input and editor id The platform opens the editor Positions to the line specified by the stack frame Adds instruction pointer annotation for the stack frame Stack Frame Source Locator Source Element Debug Model Presentation Editor Id Editor Input

Source Lookup Framework An implementation of a source locator with a standard ‘search along a path’ type of source locator, which consists of: director – holds the ordered list that is the “path” participants – map stack frames to filenames containers – find files by filename in directories, zips, jars, etc. The director-container-participant trio is similar to a Unix® path Containers .:/shared/java/classes : /user/bin/jre/lib/tools.jar Director

Director Interaction To locate source for a stack frame, the director iterates through its participants. For each participant: The director asks the participant to translate the stack frame into a source file name The director iterates through its source containers asking each container for the source element matching a file name Stack Frame Director Participant Filename Containers Source Element

Source Lookup Director Continued The default implementation of the source lookup director provides an implementation of a ‘path’ as a consistently ordered sequence of containers Leaving only two artifacts to be created Initial participants – the objects that map stack frames to file names Initial set of containers – the places to search for source files If the user has not specified an explicit source path, the director computes a default source path (set of source containers), based on launch configuration type.

Source Lookup Participants A source lookup director usually has one participant We allow for multiple participants to support multi-language debug scenarios where there can be different kinds of stack frames requiring participants from each model to provide source file names To initialize your director with participants Subclass AbstractSourceLookupDirector and override initializeParticipants() public void initializeParticipants() { addParticipants( new ISourceLookupParticipant[] { new JavaSourceLookupParticipant()}); }

Default Source Lookup Path The default source lookup path consists of one container The DefaultSourceContainer Uses an ISourcePathComputer to compute the default source path. On each launch the source path computer computes the source path Allows a source path to be dynamically generated on each launch Use the <sourcePathComputer> extension to contribute a source path computer. A launch configuration type extension can specify a source path computer You implement ISourcePathComputerDelegate which computes a default set of source containers for a launch configuration

Instantiating a Source Locator A launch delegate can instantiate a source locator and set it on a launch object However, if you don’t want to write code to instantiate the source locator when your launch delegate sets up the launch, then… The framework can use the <launchConfigurationType> and <sourceLocator> extensions to instantiate the source locator for you

Source Containers The platform provides implementations of standard source containers Workspace folders, projects, and archives Local file system directories and archives The set of containers is extensible Contribute new types of containers with the <sourceContainerTypes> extension point If you contribute a source container, you also need to contribute a corresponding <sourceContainerPresentation> to provide an icon and browser The browser is used to choose and edit a source container

Source Path Editing The framework provides a UI to edit a source lookup path Source lookup tab – launch configuration tab provides a UI for configuring and modifying a source lookup path Users may specify an explicit path (set of containers) to search, or specify to use the default source path

The Source Lookup Model Continued

Source Highlighting Text editors Positions the editor to the stack frame line number Highlights to statement ( charStart() , charEnd() ) or line (-1,-1) Distinguishes top and non-top stack frames Upon thread resume/terminate automatically removes annotations Colors are styles are preference controllable Non-text Editors The IDebugEditorPresentation API provides an escape mechanism

Source Highlighting in Text Editors Source Highlighting for Text Editors

Source Highlighting in non-Text Editors Source Highlighting for Non-Text Editors

Source Highlighting in Multipane Editors Source Highlighting for Multi-Part Text Editors

Instruction Pointer Presentation The debug platform provides support to override default instruction pointers displayed in editor rulers. Do this by having your debug model presentation implement the optional interface IInstructionPointerPresentation Allows customization of Provide the raw annotations (part of text framework, out of scope) Or provide image and hover text

Source Lookup Summary Create an implementation of ISourceLookupParticipant to provide file names for your stack frames Create subclass of AbstractSourceLookupDirector and override initializeParticipants to instantiate your participant Create an implementation of ISourcePathComputerDelegate that computes a default source lookup path for your launch configurations Define a <sourceLocator> extension to point to your director Define a <sourcePathComputer> extension to In your <launchConfigurationType> extension, refer to (4) and (5)

Module 6: The Variables View and More Standard I/O Console Perspective, Views, Actions Expression Management

Introduction Standard I/O Console: Displays content from standard input/output streams Allows for pattern matching Variables, Expressions and Registers Views: Basic structure, view inputs Displaying details for a selection Variable labels and columns Emphasizing variables that change value Displaying “logical structures” vs. raw implementation structures Editing variable values Expression Management: Watch expressions and custom expressions Evaluating watch expressions using delegates Creating a custom watch expression from a variable

Standard I/O Console There is a console framework: org.eclipse.ui.console Provides the Console view that displays all IConsoles Has implementations of text stream based consoles that can be extended Can attach output streams to the console Also has input stream connected to the keyboard The debug platform extends this framework and provides a standard I/O console Connects standard out and error streams from an IProcess to the console Connects the input stream (keyboard) to the standard in of the IProcess

Hooking up an IProcess A debug target usually has an associated system process Abstracted by IProcess IProcess implementation is provided by the debug platform for java.lang.Process An IProcess has an IStreamsProxy providing access to its streams exec(…) java. lang. Process IProcess IStreams Proxy Console

Console Pattern Matching Can contribute <consolePatternMatchListeners> To specific consoles (using enablement expressions) Specify a regular expression for pattern matching Notified of matches, can perform arbitrary actions Like, adding an IHyperlink to the console

Variables View Displays variables returned by the selected stack frame IStackFrame.getVariables() Displays current values of variables, along with children variables Variables are retrieved asynchronously

Registers View Similar to Variables View Displays register groups returned by selected stack frame IStackFrame.getRegisterGroups()

Expressions View Displays expressions returned by the Expression Manager When a stack frame is selected, watch expressions are evaluated to determine their value Debuggers must provide delegates to perform the evaluation More in Expression Management

Detail Pane Source viewer used to display details for the current selection Text is provided by a debug model presentation asynchronously computeDetail(IValue value, IValueDetailListener listener) Java Debugger does a toString() evaluation A debug model presentation can specify a SourceViewerConfiguration to install in the details area Allows for code assist, formatting, etc.

Variable Columns The variables view can be displayed with columns or as a standard tree The standard tree view labels are populated from the debug model presentation getText(Object element) The platform defines a standard set of columns that can be populated from the standard model: name, value, declared type, and actual type A debugger can provide its own columns and custom cell editors Discussed in the Custom Integration tutorial

Emphasizing Value Changes Variables that change value while stepping are rendered in red If columns are shown, the background is yellow instead A variable must implement hasValueChanged() for this to work Spec says: “returns whether the value of this variable has changed since the last suspend event” Implementation in the Java debugger The debug target maintains a count of how many times it has suspended; the count is incremented each time a thread suspends representing arbitrary points in time: 0, 1, 2, … Each time a variable retrieves its value, it checks if it has changed since the last time it was asked, and if so, synchronizes its counter with the debug targets suspend count. When a variable counter == debug counter its value has changed

Logical Structures A logical structure is an alternate presentation of a variable’s value Often, it’s more natural to navigate a complex data structure via an alternate semantic presentation of the value, rather than it’s implementation. For example, no matter how a list is implemented (linked, array, etc.), a user wants to see the elements in the list in terms of an ordered collection There are two extension points for contributing logical structures The <logicalStructureTypes> extension point is used to contribute one logical structure per variable value The <logicalStructureProviders> extension point is used to contribute a delegate that can provide multiple logical structures for a variable value dynamically

Logical Structure Type Extension Provides a single logical structure for per value Has a description that is presented in the “Show As >” menu For example, “Show As > Array” Contributes an ILogicalStructureTypeDelegate to translate value public boolean providesLogicalStructure(IValue) public IValue getLogicalStructure(IValue) public String getDescription(IValue)** ** (this method is actually defined by ILogicalStuctureTypeDelegate2 )

Logical Structure Provider Provides logical structure types for a variable value by implementing ILogicalStructureProvider public ILogicalStructureType[] getLogicalStructureTypes(IValue) Allows for a dynamic set of structures to be provided per value For example the Java debugger uses this extension point to allow users to configure logical structures via code snippets

Extensible Logical Structures for Java Debugger

Value Editing The variables view provides a standard dialog for editing a variable’s value (for variables that support value modification) You can also type into the details area and save (Ctrl-S) Calls setValue(String expression) on variable Custom dialogs can be provided by debuggers using an extension point More details in the Custom Integration tutorial

Expression Management Expressions are handled by the Expression Manager Expressions are registered with the manager The expressions view displays all registered expressions IWatchExpression is an expression implementation provided by the platform Consists of a text expression and an evaluation context (i.e. stack frame) Clients must contribute a delegate that can compute value from expression and context at <org.eclipse.debug.core.watchExpressionDelegates> Evaluations are done asynchronously and fire appropriate events Result contains a value or error messages Clients can implement IExpression to create custom expressions

Creating Watch Expressions The debug platform provides actions to allow user to provide text for a new watch expression. Platform also provides an action to create a watch expression from a selected variable By default, the expression is the variable’s name A debugger can customize this by providing an IWatchExpressionFactoryAdapterExtension registered as an adapter on a variable The factory is used to Determine if the action should be enabled for a variable Create an expression for a variable

Variables View and More Summary Standard I/O Console: Wrapper your process with an IProcess to connect streams to console framework Contribute a <consolePatternMatchListeners> extension for custom pattern matching Variables, Expressions and Registers Views: Use the debug model presentation to customize view labels and details Contribute a SourceViewerConfiguration for code assist and formatting in the detail pane Implement IVariable ’s hasVariableChanged(…) so variables are emphasized red when they change value Contribute a <logicalStructureTypes> or <logicalStructureProviders> extension to provide logical structures Implement IVariable ’s setValue(…) so variables can be edited Expression Management: Contribute a <watchExpressionDelegates> extension to evaluate watch expressions Provide an IWatchExpressionFactoryAdapterExtension as an adapter on a variable for custom watch expression creation

Legal Notices Copyright © IBM Corp., 2007-2008. All rights reserved. Source code in this presentation is made available under the EPL, v1.0, remainder of the presentation is licensed under Creative Commons Att. Nc Nd 2.5 license. IBM and the IBM logo are trademarks or registered trademarks of IBM Corporation, in the United States, other countries or both. Rational and the Rational logo are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries or both. Java and all Java-based marks, among others, are trademarks or registered trademarks of Sun Microsystems in the United States, other countries or both. Eclipse and the Eclipse logo are trademarks of Eclipse Foundation, Inc. Other company, product and service names may be trademarks or service marks of others. THE INFORMATION DISCUSSED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION, IT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, AND IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, SUCH INFORMATION. ANY INFORMATION CONCERNING IBM'S PRODUCT PLANS OR STRATEGY IS SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.

myslide1

More Related Content

What's hot (19)

Viewers also liked (12)

Similar to myslide1 (20)

More from Sandeep Putrevu (20)

myslide1