Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.



Published on


  • Be the first to comment

  • Be the first to like this


  1. 1. Debug Platform: The Basics Darin Wright, Curtis Windatt IBM Rational Software March 17 th , 2008
  2. 2. Tutorial Structure <ul><li>This tutorial is arranged as a set of modules </li></ul><ul><li>A simple example debugger is provided with a set of exercises </li></ul><ul><ul><li>To get the most from this tutorial you should work on the exercises on your own time </li></ul></ul><ul><ul><li>Use the example source code for reference </li></ul></ul><ul><ul><li> </li></ul></ul><ul><ul><ul><li>org.eclipse.debug.examples.core </li></ul></ul></ul><ul><ul><ul><li>org.eclipse.debug.examples.ui </li></ul></ul></ul><ul><li>There are two tutorials </li></ul><ul><ul><li>“ (1) The Basics ” and “(2) Custom Integration ” </li></ul></ul><ul><ul><li>Modules in “Custom Integration” build on information from this tutorial </li></ul></ul>
  3. 3. Modules – The Basics <ul><li>Debug Platform Overview </li></ul><ul><li>The Standard Debug Model </li></ul><ul><li>The Launch Framework </li></ul><ul><li>Breakpoints </li></ul><ul><li>Source Lookup </li></ul><ul><li>The Variables View and More </li></ul>
  4. 4. Module 1: Debug Platform Overview
  5. 5. A Platform Was Born <ul><li>Hypothesis </li></ul><ul><ul><li>A platform for building integrated tools should support integrated debuggers </li></ul></ul><ul><ul><li>Most debuggers are very similar </li></ul></ul><ul><ul><ul><li>A debuggable process made up of threads, stack frames, variables, etc., with common functions like stepping, terminating, suspending, etc. </li></ul></ul></ul><ul><ul><li>The platform should provide </li></ul></ul><ul><ul><ul><li>Abstractions for the common entities and functions (interfaces that will be implemented by each debugger) </li></ul></ul></ul><ul><ul><ul><li>A user interface that works against the abstractions and functions (debug, variables, breakpoint views with standard debug toolbar) </li></ul></ul></ul><ul><li>Sales pitch </li></ul><ul><ul><li>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 </li></ul></ul>
  6. 6. Facilities and Frameworks Launch Framework Source Lookup Framework Standard I/O Console Standard Debug Model Breakpoint Management Perspective, Views, Actions Expression Management
  7. 7. Building a Debugger (from 30,000 feet) <ul><li>The platform provides: </li></ul><ul><ul><li>Interfaces defining processes, threads, frames, stepping… </li></ul></ul><ul><ul><li>Views and actions to display and act on the model elements </li></ul></ul><ul><li>You provide: </li></ul><ul><ul><li>An implementation of the common interfaces </li></ul></ul><ul><ul><li>A label provider to render your model elements </li></ul></ul>Standard Debug Model
  8. 8. Building a Debugger (from 30,000 feet)
  9. 9. Building a Launcher <ul><li>The platform provides: </li></ul><ul><ul><li>Persistence of launch settings (launch configurations) and a dialog for editing launch settings </li></ul></ul><ul><li>You provide: </li></ul><ul><ul><li>An implementation of a launcher that initiates a debug session and instantiates your debug model </li></ul></ul><ul><ul><li>A set of tabs to edit your launch settings </li></ul></ul>Launch Framework
  10. 10. Building a Launcher
  11. 11. Building Breakpoints <ul><li>The platform provides: </li></ul><ul><ul><li>An abstract base class to subclass, breakpoint persistence, standard enable/disable actions, breakpoints view </li></ul></ul><ul><ul><li>Retargettable actions for toggling breakpoints </li></ul></ul><ul><li>You provide: </li></ul><ul><ul><li>Concrete implementations of breakpoints specific to your debugger </li></ul></ul><ul><ul><li>Implementation of a ‘breakpoint toggler’ to create/delete your breakpoints </li></ul></ul>Breakpoint Management
  12. 12. Building Breakpoints
  13. 13. Integrating Source Display <ul><li>The platform provides: </li></ul><ul><ul><li>Interface and implementation of a source locator that finds source files on a search path by name </li></ul></ul><ul><ul><li>Standard icons and highlighting for painting the instruction pointer in a text editor </li></ul></ul><ul><li>You provide: </li></ul><ul><ul><li>The search path for a debug session </li></ul></ul><ul><ul><li>The filename to search for and line number to highlight (given a suspended debug context) </li></ul></ul><ul><ul><li>An editor (if needed) </li></ul></ul>Source Lookup Framework
  14. 14. Integrating Source Display
  15. 15. The Center Of The Universe <ul><li>A debugger revolves around the “active debug context” </li></ul><ul><ul><li>The “active debug context” is the selection in the debug view – a frame, thread, etc. </li></ul></ul><ul><ul><li>This context drives source lookup, visible variables and registers, and action enablement </li></ul></ul><ul><li>Each workbench window has a “Debug Context Service” </li></ul><ul><ul><li>A service provides change notification whenever the active context changes </li></ul></ul><ul><ul><li>Whenever the context changes, interested parties update </li></ul></ul>
  16. 16. Providers and Listeners Debug View Selection Actions Source Lookup IDebugContextService Context activated Context activated Provides context (context service per window)
  17. 17. Context Providers <ul><li>The platform allows for multiple “debug context providers” per window </li></ul><ul><ul><li>The platform provides one context provider – the Debug view </li></ul></ul><ul><ul><li>You could implement additional context providers if needed </li></ul></ul><ul><li>The “debug context” for a window comes from the active provider </li></ul><ul><ul><li>A context provider is usually associated with a workbench part </li></ul></ul><ul><ul><li>The active provider is </li></ul></ul><ul><ul><ul><li>The active part (if it is a provider) </li></ul></ul></ul><ul><ul><ul><li>Or the most recently active part that is a provider </li></ul></ul></ul><ul><li>Context providers generate DebugContextEvent ’s as the active context changes </li></ul>
  18. 18. Context Listeners <ul><li>Context listeners register with a context service (window) for change notification </li></ul><ul><ul><li>Receive DebugContextEvent ’s each time the context changes </li></ul></ul><ul><ul><li>Listeners can register for change notification in a specific part, an entire window, or from all windows </li></ul></ul><ul><ul><ul><li>Examples: </li></ul></ul></ul><ul><ul><ul><ul><li>View toolbar actions listen to a specific part </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Window menu actions listen to their window </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Source lookup listens to the window </li></ul></ul></ul></ul><ul><ul><li>Modeled on the workbench selection service </li></ul></ul>
  19. 19. PDA Example Debugger <ul><li>PDA (Push Down Automaton) </li></ul><ul><li>Assembly language with an interpreter written in Perl </li></ul><ul><li>Send request to the interpreter over one socket </li></ul><ul><li>Read events over another socket </li></ul>var n pop $n push $n branch_not_zero gt0 push 1 return :gt0 …
  20. 20. Module 2: The Standard Debug Model Standard Debug Model
  21. 21. Introduction <ul><li>The Eclipse “Standard Debug Model” contains the basic abstractions common to imperative execution environments </li></ul><ul><ul><li>Process, Thread, Stack Frame, Variable, Register, Breakpoint, … </li></ul></ul><ul><li>The Eclipse Debug UI interacts with these abstractions </li></ul><ul><ul><li>Plug-in debuggers provide implementations </li></ul></ul>
  22. 22. Custom Debugger Integration <ul><li>The standard debug model doesn’t represent all architectures </li></ul><ul><ul><li>For example, embedded hardware models are different – often there are multiple processors in multi-core, possibly with DSP configurations </li></ul></ul><ul><li>The platform provides support to integrate non-standard debuggers into the common views and actions </li></ul><ul><ul><li>We look at this in the “Custom Integration” tutorial </li></ul></ul>
  23. 23. Introduction - Remote Targets <ul><li>The standard model has synchronous APIs abstracting remote connections/communication </li></ul>
  24. 24. The Players <ul><li>Debug Model Elements </li></ul><ul><ul><li>The program being debugged </li></ul></ul><ul><li>Capabilities </li></ul><ul><ul><li>Support for stepping, resuming, terminating, etc. </li></ul></ul><ul><li>Debug Events </li></ul><ul><ul><li>Describe happenings in an executing target or process </li></ul></ul><ul><li>Debug Model Presentation </li></ul><ul><ul><li>Provides labels and images for debug model elements </li></ul></ul>
  25. 25. Debug Model Elements <ul><li>The standard debug model contains </li></ul><ul><ul><li>Debug Target IDebugTarget </li></ul></ul><ul><ul><ul><li>Threads IThread </li></ul></ul></ul><ul><ul><ul><ul><li>Stack Frames IStackFrame </li></ul></ul></ul></ul><ul><ul><ul><ul><ul><li>Variables IVariable </li></ul></ul></ul></ul></ul><ul><ul><ul><ul><ul><li>Register Groups IRegisterGroup </li></ul></ul></ul></ul></ul><ul><li>Variables, in this context contain </li></ul><ul><ul><li>Values ( IValue ), which can contain other variables to represent complex data structures </li></ul></ul><ul><li>A register group contains </li></ul><ul><ul><li>Registers ( IRegister ), which are just variables </li></ul></ul>
  26. 26. Capabilities <ul><li>The standard debug capabilities are </li></ul><ul><ul><li>Step (over, into, return) IStep </li></ul></ul><ul><ul><li>Terminate ITerminate </li></ul></ul><ul><ul><li>Suspend & Resume ISuspendResume </li></ul></ul><ul><ul><li>Disconnect IDisconnect </li></ul></ul><ul><ul><li>Drop to Frame IDropToFrame </li></ul></ul><ul><li>The standard debug elements implement standard capabilities </li></ul><ul><li>IDebugTarget extends ITerminate, ISuspendResume, IDisconnect </li></ul><ul><li>IThread extends ITerminate, ISuspendResume, IStep </li></ul><ul><li>IStackFrame extends ITerminate, ISuspendResume, IStep </li></ul>
  27. 27. Debug Model Elements and Capabilities
  28. 28. Debug Events <ul><li>A debug event describes something that has happened in a program being debugged </li></ul><ul><ul><li>An event has a type (kind) and detail code </li></ul></ul><ul><li>The user interface requires debug model elements and process implementations to generate debug events. For example: </li></ul><ul><ul><li>IProcess – CREATE, TERMINATE </li></ul></ul><ul><ul><li>IDebugTarget – CREATE, TERMINATE, SUSPEND, RESUME </li></ul></ul><ul><ul><li>IThread – CREATE, TERMINATE, SUSPEND, RESUME </li></ul></ul><ul><li>Required events are specified in the DebugEvent class </li></ul>
  29. 29. Debug Events <ul><li>Detail codes describe why an event occurred: </li></ul><ul><ul><li>A suspend could be caused by: STEP_END, BREAKPOINT, CLIENT_REQUEST, EVALUATION, EVALUATION_IMPLICIT </li></ul></ul><ul><ul><li>A resume could be caused by: STEP_INTO, STEP_OVER, STEP_RETURN, CLIENT_REQUEST, EVALUATION, EVALUATION_IMPLICIT </li></ul></ul><ul><li>The debug platform provides event notification </li></ul><ul><ul><li>DebugPlugin.fireDebugEventSet(DebugEvent[] events) </li></ul></ul><ul><ul><li>DebugPlugin.addDebugEventListener(IDebugEventSetListener listener) </li></ul></ul>
  30. 30. Debug Events (more) <ul><li>Event notification is performed in a separate thread </li></ul><ul><ul><li>Events are queued and fired </li></ul></ul><ul><li>A debug event set contains all events that occurred at the same location in a program </li></ul><ul><ul><li>Most of the time and event set contains one event </li></ul></ul><ul><ul><li>You could describe simultaneous events – for example, a step completing at the same location as a breakpoint </li></ul></ul>
  31. 31. Events and Views Viewer Standard Model Event Listener add, remove refresh, select expand debug events
  32. 32. Debug View Updates <ul><li>IDebugTarget </li></ul><ul><ul><li>CREATE – expands the target </li></ul></ul><ul><ul><li>TERMINATE – updates the label </li></ul></ul><ul><ul><li>RESUME – select target, update label, refresh children </li></ul></ul><ul><ul><li>SUSPEND – update label, refresh children </li></ul></ul><ul><li>IThread </li></ul><ul><ul><li>CREATE – adds the thread </li></ul></ul><ul><ul><li>TERMINATE – removes the thread </li></ul></ul>
  33. 33. Debug View Updates (more) <ul><li>IThread.RESUME </li></ul><ul><ul><li>Client request </li></ul></ul><ul><ul><ul><li>Update label, refresh children (should remove them), select </li></ul></ul></ul><ul><ul><li>Expecting suspend – i.e. step or evaluation </li></ul></ul><ul><ul><ul><li>Do nothing, until timeout (500ms) or suspend is received </li></ul></ul></ul><ul><ul><ul><li>Timeout causes thread select & refresh (removes frames) </li></ul></ul></ul><ul><li>IThread.SUSPEND </li></ul><ul><ul><li>Client request/Breakpoint </li></ul></ul><ul><ul><ul><li>Update thread label, expand, refresh children, select top frame </li></ul></ul></ul><ul><ul><li>Step end </li></ul></ul><ul><ul><ul><li>Update thread label, select top frame, update top frame label </li></ul></ul></ul>
  34. 34. Debug Model Presentation <ul><li>Debug model elements are displayed with text and images </li></ul><ul><ul><li>Standard images are provided by the platform </li></ul></ul><ul><ul><li>Default labels are just element names (for example, IThead.getName() ) </li></ul></ul><ul><li>To provide custom labels and images </li></ul><ul><ul><li>Contribute a <debugModelPresentation> extension </li></ul></ul><ul><ul><li>Provide corresponding implementation of IDebugModelPresentation , which is an ILabelProvider : </li></ul></ul>
  35. 35. The Debug Model
  36. 36. PDA Example <ul><li>The PDA debugger provides implementations of: </li></ul><ul><ul><li>IDebugTarget : PDADebugTarget </li></ul></ul><ul><ul><li>IThread : PDAThread </li></ul></ul><ul><ul><li>IStackFrame : PDAStackFrame </li></ul></ul><ul><ul><li>IVariable : PDAVariable </li></ul></ul><ul><ul><li>IValue : PDAValue </li></ul></ul><ul><li>Although PDA is single threaded, we provide an implementation of a model with one thread to conform to the standard model </li></ul>
  37. 37. PDA Implementation <ul><li>Communication between the PDA debug model and interpreter is performed by writing a request and reading a reply over a socket (simple, not robust) </li></ul><ul><li>public String sendRequest(String request) throws DebugException { </li></ul><ul><li>synchronized ( fRequestSocket ) { </li></ul><ul><li>fRequestWriter .println(request); </li></ul><ul><li>fRequestWriter .flush(); </li></ul><ul><li>try { </li></ul><ul><li>// wait for reply </li></ul><ul><li>return fRequestReader .readLine(); </li></ul><ul><li>} catch (IOException e) { </li></ul><ul><li>requestFailed( &quot;Request failed: &quot; + request, e); </li></ul><ul><li>} </li></ul><ul><li>} </li></ul><ul><li>return null ; </li></ul><ul><li>} </li></ul>
  38. 38. PDA Debug Protocol <ul><li>Protocol documented in: </li></ul><ul><ul><li>org.eclipse.debug.examples.core/pdavm/docs/ protocol.html </li></ul></ul><ul><ul><li>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 </li></ul></ul><ul><li>Events are sent over a separate socket and are documented in IPDAEventListener : </li></ul><ul><ul><li>The PDA debug target starts an event reader on the event socket and processes events </li></ul></ul><ul><ul><li>For example, a step request results in two events – a “ resumed step ” event and a “ suspended step ” event. </li></ul></ul>
  39. 39. Tip <ul><li>All PDA debug elements subclass PDADebugElement which subclasses DebugElement (an abstract class provided by the debug platform) </li></ul><ul><ul><li>The platform’s abstract class provides convenience methods for firing events, reporting exceptions, retrieving adapters, and debug target and launch accessors </li></ul></ul><ul><ul><li>PDA’s abstract class provides convenience methods for sending requests to the interpreter and providing a debug model identifier </li></ul></ul>
  40. 40. Summary <ul><li>Implement Debug model </li></ul><ul><ul><li>Implement debug elements: IDebugTarget , IThread , IStackFrame … </li></ul></ul><ul><ul><li>Implement supported capabilities: IStep , ITerminate … </li></ul></ul><ul><ul><li>Ensure model fires required DebugEvents </li></ul></ul><ul><li>Contribute an IDebugModelPresentation to the <debugModelPresentations> extension point </li></ul>
  41. 41. Module 3: The Launch Framework Launch Framework
  42. 42. Introduction <ul><li>Running and debugging code is fundamental to an IDE </li></ul><ul><ul><li>To run and debug, we have to launch </li></ul></ul><ul><li>The launch framework includes facilities for </li></ul><ul><ul><li>Spawning an O/S process </li></ul></ul><ul><ul><li>Persisting information about how something is launched </li></ul></ul><ul><ul><li>A framework for editing launch parameters (GUI) </li></ul></ul><ul><ul><li>An extensible set of launch modes (run, debug, profile…) </li></ul></ul><ul><ul><li>Selection sensitive actions for launching </li></ul></ul>
  43. 43. Launching Players <ul><li>Launch Manager </li></ul><ul><ul><li>Manages types, configurations, and launch notifications </li></ul></ul><ul><li>Launches </li></ul><ul><ul><li>Container for launched targets and/or processes </li></ul></ul><ul><li>Launch Configuration Types </li></ul><ul><ul><li>The type of what to launch </li></ul></ul><ul><li>Launch Configurations </li></ul><ul><ul><li>Persisted description of what to launch </li></ul></ul><ul><li>Launch Delegates </li></ul><ul><ul><li>What actually performs the launch </li></ul></ul><ul><li>Launch Modes </li></ul><ul><ul><li>The modes to launch in </li></ul></ul>
  44. 44. Launch Players – Continued <ul><li>Tab Groups </li></ul><ul><ul><li>UI for editing launch configurations </li></ul></ul><ul><li>Tabs </li></ul><ul><ul><li>UI contributions to tab groups </li></ul></ul><ul><li>Launch Shortcuts </li></ul><ul><ul><li>Context sensitive action for launching </li></ul></ul>
  45. 45. Launching Players
  46. 46. Launch Manager <ul><li>Manages all launch configurations, configuration types and launches </li></ul><ul><ul><li>Can be queried for all available launch configurations </li></ul></ul><ul><ul><li>Can be queried for all registered configuration types </li></ul></ul><ul><ul><li>Can be queried for all registered launch modes </li></ul></ul><ul><ul><li>Launches are registered/deregistered with the manager </li></ul></ul><ul><ul><li>Provides change notification for launches </li></ul></ul><ul><ul><li>Also manages all registered source container types, source path computers and creates source locaters (module 5) </li></ul></ul>
  47. 47. Launches <ul><li>Container of processes and debug targets created by launching </li></ul><ul><ul><li>The debug platform provides a standard implementation of IProcess based on java.lang.Process </li></ul></ul><ul><ul><li>Provides convenience methods for launching/creating an IProcess from a command line </li></ul></ul><ul><ul><li>Allows you to provide your own implementation if desired </li></ul></ul><ul><li>The debugger provides a console to display the standard I/O streams of a process </li></ul><ul><ul><li>For each IProcess added to an ILaunch , the debug platform allocates a console attached to its I/O streams </li></ul></ul><ul><ul><ul><li>std.out and std.err are written in blue and red </li></ul></ul></ul><ul><ul><ul><li>Keyboard is attached to - input is buffered and written to when <Enter> is pressed </li></ul></ul></ul>
  48. 48. Launch Configuration Types <ul><li>Each launch configuration is of a specific type </li></ul><ul><ul><li>e.g. Java Application </li></ul></ul><ul><li>The <launchConfigurationTypes> extension point </li></ul><ul><ul><li>Allows new launch types to be contributed to the platform </li></ul></ul><ul><ul><li>All contributed launch types are available from the launch manager </li></ul></ul><ul><li>The platform provides the only implementation of launch configuration types – ILaunchConfigurationType . </li></ul><ul><ul><li>Each extension can contribute a launch delegate </li></ul></ul>
  49. 49. Launch Configuration Types – Continued <ul><li>Each launch type has domain specific attributes associated with it, which are stored in individual launch configurations </li></ul><ul><ul><li>E.g. Java applications have attributes like main type whereas PDE has a set of plug-ins </li></ul></ul><ul><li>Each type can also provide: </li></ul><ul><ul><li>The id of a specific source path computer to use </li></ul></ul><ul><ul><li>The id of a specific source locator to use (more on these in module 5) </li></ul></ul>
  50. 50. Launch Configurations <ul><li>Description of how and what to launch </li></ul><ul><ul><li>Persisted map of keys and values </li></ul></ul><ul><ul><li>The platform provides the only implementation of launch configurations – ILaunchConfiguration and ILaunchConfigurationWorkingCopy </li></ul></ul><ul><ul><li>A launch configuration is read-only – a working copy is used to edit a configuration in a transaction-like manor </li></ul></ul><ul><ul><ul><li>A working copy is created from a launch configuration, can be nested (new) </li></ul></ul></ul><ul><ul><ul><li>Launch tabs modify a working copy and can commit changes to the original or revert </li></ul></ul></ul><ul><li>Designed to be shared across different launch modes </li></ul><ul><ul><li>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) </li></ul></ul>
  51. 51. Lazy Launch Configurations <ul><li>The launch configuration (state) and launch delegate (behavior) are separated to promote lazy loading of plug-ins. </li></ul><ul><ul><li>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. </li></ul></ul><ul><li>Launch configuration type images </li></ul><ul><ul><li>Contributed to the <launchConfigurationTypeImages> extension point </li></ul></ul><ul><ul><li>Allows us to display images in history without loading your plug-in </li></ul></ul>
  52. 52. Launch Configurations – Continued <ul><li>Launch configurations can be mapped to a set of resources </li></ul><ul><ul><li>Allows launch configurations to be shown as a property of a resource (property page) </li></ul></ul><ul><ul><li>Clients must manage the resource mapping </li></ul></ul><ul><li>Launch configurations can be migrated </li></ul><ul><ul><li>Facilitates upgrading existing launch configurations to support new features </li></ul></ul><ul><ul><li>Contributed by new optional <migrationDelegate> attribute on the launch configuration types extension point </li></ul></ul><ul><ul><li>Must implement ILaunchConfigurationMigrationDelegate </li></ul></ul>
  53. 53. Launch Delegates <ul><li>A launch configuration type contributes a launch delegate for specific launch modes </li></ul><ul><ul><li>Implements ILaunchConfigurationDelegate </li></ul></ul><ul><ul><li>E.g. the Java debugger contributes a launch delegate for run and debug modes for Java applications </li></ul></ul><ul><li>The debug platform provides an abstract launch delegate that should be sub-classed. </li></ul><ul><ul><li>The abstract delegate ( LaunchConfigurationDelegate ) provides infrastructure to perform: </li></ul></ul><ul><ul><ul><li>Scoped builds before launching, allowing subclasses to specify the set of projects that should be compiled. </li></ul></ul></ul><ul><ul><ul><li>Scoped search for errors/problems, allowing the launch to be aborted </li></ul></ul></ul><ul><ul><ul><li>Scoped search for unsaved editors, allowing the editors to be saved </li></ul></ul></ul>
  54. 54. Launch Modes <ul><li>The debug platform has an extensible set of launch modes </li></ul><ul><ul><li>A mode represents the way a user has chosen to launch </li></ul></ul><ul><ul><li>Delegates are passed the mode when launching </li></ul></ul><ul><li>The platform defines three launch modes: </li></ul><ul><ul><li>run, debug, profile </li></ul></ul><ul><li>Use the <launchModes> extension point to contribute others </li></ul>
  55. 55. Launch Sequence Launch Config The Launch Launch Manager Launch Delegate IProcess IDebugTarget Mode System Process Creates Registered In Creates Wrapped By Children
  56. 56. Extending Existing Types <ul><li>Launch configurations can be extended by other tools </li></ul><ul><ul><li>Example, a new launch mode like profiling for Java applications </li></ul></ul><ul><li>The <launchDelegates> extension point </li></ul><ul><ul><li>Allows a launch delegate to be contributed to an existing launch configuration type for a specific launch mode, or set of launch modes </li></ul></ul><ul><ul><li>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. </li></ul></ul><ul><li>The <launchConfigurationTabGroups> extension point </li></ul><ul><ul><li>allows a tab group added for an existing configuration type </li></ul></ul><ul><ul><li>for a specific mode </li></ul></ul>
  57. 57. Extending Existing Types and Modes <ul><li>Pre-3.3 you could launch in one mode </li></ul><ul><ul><li>Run or Debug, etc </li></ul></ul><ul><li>If you wanted to provide additional capabilities, for example code coverage while debugging </li></ul><ul><ul><li>You would have to create a new type, delegate, mode, tabs, etc </li></ul></ul><ul><li>Since 3.3, you can launch in mixed modes </li></ul><ul><ul><li>There is a primary mode (run, debug, etc.) chosen by the user, and secondary modes provided by tooling (eg. code coverage) </li></ul></ul><ul><ul><li>The secondary modes are set into the configuration </li></ul></ul><ul><ul><li>A launch delegate can be contributed for mode combinations </li></ul></ul><ul><ul><li>Additional tabs can be contributed to existing tab groups </li></ul></ul>
  58. 58. Tab Groups <ul><li>A set of tabs is used to display and edit a single launch configuration </li></ul><ul><ul><li>Displayed in the launch dialog when a configuration is selected </li></ul></ul><ul><ul><li>Tabs operate on a launch configuration working copy in a transaction-like manor – can commit or revert </li></ul></ul><ul><li>Contributed via the <launchConfigurationTabGroups> extension point </li></ul><ul><ul><li>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 </li></ul></ul>
  59. 59. Tabs <ul><li>Tabs </li></ul><ul><ul><li>Provide SWT controls to edit launch configurations attributes (state) </li></ul></ul><ul><ul><li>Normally instantiated by a tab group </li></ul></ul><ul><li>The platform provides an abstract class – AbstractLaunchConfigurationTab </li></ul><ul><ul><li>Which should be used to create your tabs for your tab group </li></ul></ul><ul><ul><li>Which also provides basic functionality for all launch tabs </li></ul></ul><ul><li>The <launchConfigurationTabs> extension point </li></ul><ul><ul><li>Is used to contribute a single tab to an existing tab group </li></ul></ul><ul><ul><li>Can have an associated launch delegate </li></ul></ul><ul><ul><li>Can have a relative placement </li></ul></ul><ul><ul><ul><li>Contributed tabs can be placed ‘after’ another existing tab </li></ul></ul></ul>
  60. 60. Tabs – Continued <ul><li>Example contributed tab to the Java Application tab group </li></ul><ul><ul><li>Placed after the Main tab </li></ul></ul><ul><ul><li>With associated launch delegate </li></ul></ul><extension point=&quot;org.eclipse.debug.ui.launchConfigurationTabs&quot;> <tab class=&quot;org.eclipse.example.ui.MyTab&quot; group=&quot;org.eclipse.jdt.debug.ui.launchConfigurationTabGroup.localJavaApplication&quot; id=&quot;org.eclipse.example.ui.myTab&quot; name=“My Tab&quot;> <placement after=&quot;org.eclipse.jdt.debug.ui.javaMainTab&quot;></placement> <associatedDelegate delegate=&quot;org.eclipse.example.mydelegate&quot;> </associatedDelegate> </tab> </extension>
  61. 61. Launch Shortcuts <ul><li>Launch shortcuts are added to the Run As… context menu </li></ul><ul><ul><li>Provides a simple way for users to launch a file/program </li></ul></ul><ul><ul><li>Creates a configuration (if one does not already exist), and launches it </li></ul></ul><ul><ul><li>Contributed via the <launchShortcuts> extension point </li></ul></ul><ul><li>Launch shortcuts provide enablement expressions </li></ul><ul><ul><li>Specify when it should be enabled for a selection in the workbench (i.e. appear in the Run As… context menu) </li></ul></ul><ul><ul><li>Enablement expressions are XML boolean expressions that are common to many extension points </li></ul></ul><ul><ul><li>The debug platform provides some property testers </li></ul></ul><ul><ul><ul><li>Filename pattern matching, file content type, project nature, etc. </li></ul></ul></ul>
  62. 62. Improving the User Experience <ul><li>History: </li></ul><ul><ul><li>In the beginning there was only the Launch Dialog and launch history </li></ul></ul><ul><ul><li>In 2.0 we added Launch Shortcuts in context menu </li></ul></ul><ul><ul><li>In 3.3 we added Contextual launch </li></ul></ul><ul><ul><ul><li>Press run or debug to launch the selection appropriately </li></ul></ul></ul><ul><li>Contextual Launch </li></ul><ul><ul><li>Best approximation at launching an existing configuration associated with the selection/editor, or choosing the best launch shortcut to launch the selection/editor </li></ul></ul>
  63. 63. What’s a “Best Approximation”? <ul><li>The most recently launched configuration in the history associated with the selection, or its project. </li></ul><ul><ul><li>Based on resource mapping provided by launch configuration </li></ul></ul><ul><li>If there are none, we prompt the user to choose a launch shortcut to launch the selection/editor </li></ul><ul><ul><li>Based on enablement expressions </li></ul></ul><ul><ul><li>Helps if you provide launch shortcut descriptions (new attribute added in 3.3 displayed in prompt dialog) </li></ul></ul>
  64. 64. But, I don’t launch IResources … <ul><li>To override default resource mappings and support contextual launch for non-resource based models we added an optional extension ILaunchShortcut2 in 3.4 </li></ul><ul><ul><li>Allows client to provide resource and/or launch configuration mappings for editors and selections </li></ul></ul>
  65. 65. Got Two Profilers? <ul><li>Pre-3.3 similar tooling could cause conflicts </li></ul><ul><ul><li>Differing launch delegates for same mode </li></ul></ul><ul><ul><ul><li>E.g. we could have two profilers that both contributed a launch delegate for Java Application in debug mode </li></ul></ul></ul><ul><ul><li>Differing contributors for the same tab group in the launch dialog </li></ul></ul><ul><ul><ul><li>E.g. we could have two profilers (again) that both contribute a tab group to Java Application </li></ul></ul></ul><ul><ul><li>Pre-3.3 there was no way to differentiate the previous cases </li></ul></ul><ul><ul><ul><li>Launch delegates and tab group to use would be selected non-deterministically </li></ul></ul></ul>
  66. 66. Preferred Launch Delegates <ul><li>Preference page shows conflicting tooling by launch configuration type </li></ul><ul><li>User selects preferred delegate </li></ul><ul><li>User is prompted to choose preferred delegate at launch time if not already chosen </li></ul>
  67. 67. Summary <ul><li>Contribute any <launchConfigurationTypes> </li></ul><ul><ul><li>Specify migration delegate if needed (upgrade resource mappings) </li></ul></ul><ul><li>Implement ILaunchConfiugrationDelegate </li></ul><ul><ul><li>Contribute with <launchConfigurationType> or use <launchDelegates> for existing types </li></ul></ul><ul><li>Contribute <launchConfigurationTabGroups> </li></ul><ul><ul><li>Or use <launchConfigurationTabs> for existing tab groups </li></ul></ul><ul><ul><li>Implement tabs extending from AbstractLaunchConfigurationTab </li></ul></ul><ul><ul><li>Maintain resource mappings for contextual launch </li></ul></ul><ul><li>Contribute <launchShortcuts> </li></ul><ul><ul><li>Provide enablement expressions </li></ul></ul><ul><ul><li>Consider ILaunchShortcut2 for contextual launch </li></ul></ul>
  68. 68. Module 4: Breakpoints Breakpoint Management
  69. 69. Introduction <ul><li>What are breakpoints? </li></ul><ul><ul><li>A way to suspend execution at a specified location or upon a specified condition. </li></ul></ul><ul><ul><li>Line breakpoints, Watchpoints, Run-to-Line, and Exception Traps are kinds of breakpoints. </li></ul></ul><ul><li>The breakpoint framework provides facilities for: </li></ul><ul><ul><li>Add, remove, change notification </li></ul></ul><ul><ul><li>Persistence of breakpoints across workbench invocations </li></ul></ul><ul><ul><li>Temporarily skipping breakpoints </li></ul></ul><ul><ul><li>Retargetable actions for creating breakpoints </li></ul></ul><ul><ul><li>Exporting and importing breakpoints to/from a file </li></ul></ul>
  70. 70. Introduction Continued <ul><li>The types of breakpoints a debugger provides depends on: </li></ul><ul><ul><li>The capabilities provided by the underlying debug architecture </li></ul></ul><ul><ul><li>Aggregate functions that can be built with those capabilities </li></ul></ul><ul><li>Examples </li></ul><ul><ul><li>Implementing run-to-line with line breakpoints </li></ul></ul><ul><ul><li>Implementing hit counts on the client side </li></ul></ul><ul><ul><li>Implementing conditional breakpoints with client side evaluations </li></ul></ul>
  71. 71. Breakpoint Players <ul><li>Breakpoint extension point </li></ul><ul><ul><li>Extension point for contributing kinds of breakpoints </li></ul></ul><ul><li>Breakpoint </li></ul><ul><ul><li>Model object representing an instance of a breakpoint </li></ul></ul><ul><li>Marker </li></ul><ul><ul><li>Used to persist a breakpoint’s attributes and display a breakpoint in an editor </li></ul></ul><ul><li>Breakpoint Manager </li></ul><ul><ul><li>Breakpoint repository, provides change notification </li></ul></ul><ul><li>Debug Target </li></ul><ul><ul><li>Installs breakpoints in underlying runtime </li></ul></ul>
  72. 72. More Breakpoint Players <ul><li>Retargettable actions </li></ul><ul><ul><li>Actions for toggling breakpoints in editor/active selection </li></ul></ul><ul><li>Editor </li></ul><ul><ul><li>Displays markers in vertical ruler </li></ul></ul><ul><li>Debug Model Presentation </li></ul><ul><ul><li>Renders breakpoints </li></ul></ul><ul><li>Breakpoint properties dialog </li></ul><ul><ul><li>Editing breakpoint properties </li></ul></ul>
  73. 73. Breakpoint Extension Point <ul><li>The platform provides an extension point for contributing kinds of breakpoints </li></ul><extension point=&quot;org.eclipse.debug.core.breakpoints&quot;> <breakpoint class=&quot;example.debug.core.breakpoints.PDALineBreakpoint&quot; name=&quot;PDA Line Breakpoints&quot; markerType=&quot;example.debug.core.pda.markerType.lineBreakpoint&quot; id=&quot;pda.lineBreakpoint&quot;/> </extension>
  74. 74. Breakpoint <ul><li>Model object representing a breakpoint </li></ul><ul><ul><li>All breakpoints implement IBreakpoint </li></ul></ul><ul><ul><li>The platform also defines base interfaces for ILineBreakpoint and IWatchpoint </li></ul></ul><ul><ul><li>A breakpoint contains the information required to install itself into a debug target </li></ul></ul><ul><ul><li>All implementations must have a default constructor such that the platform can instantiate persisted breakpoints on workspace startup </li></ul></ul><ul><ul><li>The platform provides abstract classes that must be sub-classed when implementing breakpoints – Breakpoint and LineBreakpoint . </li></ul></ul>
  75. 75. Breakpoint Continued <ul><li>The platform’s implementation provides enablement and attribute persistence </li></ul><ul><ul><li>A breakpoint’s attributes are stored in a marker </li></ul></ul><ul><li>Breakpoint behavior is provided by client implementations </li></ul><ul><ul><li>I.e. Custom properties, installation, adhering to enablement </li></ul></ul><ul><li>For example, the Java debugger supports: </li></ul><ul><ul><li>Line breakpoints, watchpoints, method breakpoints, exception breakpoints, class load breakpoints </li></ul></ul><ul><ul><ul><li>Hit counts, suspend VM vs. thread, conditions, thread filters, location filters, instance breakpoints, suspend on caught vs. uncaught </li></ul></ul></ul><ul><ul><li>An API for creating and configuring these breakpoints </li></ul></ul><ul><ul><li>Property pages and actions for editing Java breakpoint properties </li></ul></ul>
  76. 76. Breakpoint Mechanisms <ul><li>The actual mechanism used to suspend execution on a debuggable process differs between debug architectures </li></ul><ul><ul><li>E.g. JVM debug interface accepts requests to suspend execution at specific line number in a class file </li></ul></ul><ul><ul><li>This only works when line number debug attributes are present in the class file </li></ul></ul><ul><li>An IBreakpoint simply stores the information required to install a breakpoint in a specific architecture </li></ul><ul><ul><li>For example, a Java line breakpoint stores a fully qualified type name and line number. </li></ul></ul><ul><ul><li>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). </li></ul></ul>
  77. 77. Marker <ul><li>Breakpoint attributes are stored in markers </li></ul><ul><ul><li>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 </li></ul></ul><ul><ul><li>An marker is just a store of key/value pairs of primitive data types </li></ul></ul><ul><ul><li>The platform provides the only implementation of IMarker </li></ul></ul><ul><li>Breakpoint behaviors are implemented in IBreakpoint ’s </li></ul><ul><ul><li>To provide complex breakpoint behavior, debuggers provide implementations of IBreakpoint </li></ul></ul><ul><ul><li>All breakpoints have an associated marker to persist it attributes and display in an editor </li></ul></ul>
  78. 78. Marker Continued <ul><li>Contribute marker extension associated with breakpoint type </li></ul><ul><ul><li>Notes </li></ul></ul><ul><ul><ul><li>Must specify persistent as true if you want your breakpoints to be persisted </li></ul></ul></ul><ul><ul><ul><li>Must specify attributes you want persisted </li></ul></ul></ul><extension id=&quot;commonJavaLineBreakpointMarker&quot; point=&quot;org.eclipse.core.resources.markers&quot;> <super type=&quot;org.eclipse.jdt.debug.javaBreakpointMarker“/> <super type=&quot;org.eclipse.debug.core.lineBreakpointMarker“/> <persistent value=&quot;true“/> <attribute name=&quot;org.eclipse.jdt.debug.core.typeName“/> <attribute name=&quot;org.eclipse.jdt.debug.core.installCount“/> <attribute name=&quot;org.eclipse.jdt.debug.core.hitCount“/> <attribute name=&quot;org.eclipse.jdt.debug.core.expired“/> </extension>
  79. 79. Breakpoint Manager <ul><li>The breakpoint manager ( IBreakpointManager ) is a repository of breakpoints in the workspace </li></ul><ul><ul><li>When a breakpoint is created, it is registered with the manager </li></ul></ul><ul><ul><li>When a breakpoint is deleted, it is removed from the manager </li></ul></ul><ul><ul><li>Provides change notification as breakpoints are added, removed, and when a breakpoint attribute changes </li></ul></ul><ul><li>Clients interested in breakpoints </li></ul><ul><ul><li>Implement IBreakpointsListener and register with the manager </li></ul></ul><ul><ul><li>For example, debug targets listen for change notification so they can install/remove/update breakpoints as they change </li></ul></ul><ul><li>Clients should also register as IBreakpointManagerListener ’s </li></ul><ul><ul><li>Notified when the breakpoint manager has been disabled/enabled </li></ul></ul><ul><ul><li>This feature allows all breakpoints to be temporarily disabled with out changing the enablement state of individual breakpoints (i.e. skip breakpoints) </li></ul></ul>
  80. 80. Debug Target <ul><li>The debug target installs breakpoints </li></ul><ul><ul><li>IDebugTarget extends IBreakpointListener </li></ul></ul><ul><ul><li>When a debug target is created, it should query the breakpoint manager for all existing relevant breakpoints and install them (deferred breakpoints) </li></ul></ul><ul><ul><li>Listens for breakpoints being added/removed/changed during its lifecycle, and updates them in the underlying runtime </li></ul></ul>
  81. 81. Retargettable Actions <ul><li>Most debuggers support a common set of breakpoint types </li></ul><ul><ul><li>Line breakpoints, method breakpoints, and watchpoints </li></ul></ul><ul><li>Global actions are provided for creating these kinds of breakpoints </li></ul><ul><ul><li>Promotes a common look and feel across debuggers </li></ul></ul><ul><ul><li>Avoids polluting menus with similarly named actions </li></ul></ul>
  82. 82. Retargetting <ul><li>How does it work? </li></ul><ul><ul><li>The global actions ask the active editor, view, or selection for its IToggleBreakpointsTarget adapter. </li></ul></ul><ul><ul><li>Debuggers register adapters with the appropriate editors, views, objects. </li></ul></ul><ul><ul><li>Actions interact with adapter to determine action enablement and toggle breakpoints </li></ul></ul>Action Editor View Selection { }
  83. 83. The Editor <ul><li>The editor visualizes the location of breakpoint/watchpoints </li></ul><ul><ul><li>Displays markers in vertical ruler and updates as markers are changed </li></ul></ul><ul><ul><li>Provides adapter to hook into the retargetable breakpoint actions </li></ul></ul><ul><ul><li>Editors that subclass AbstractDecoratedTextEditor have a ruler to display markers associated with the file (resource) they are editing </li></ul></ul>
  84. 84. Debug Model Presentation <ul><li>The IDebugModelPresentation associated with the debug model provides image and label for breakpoints in editors and the Breakpoints view </li></ul><ul><ul><li>Each time a breakpoint attribute changes the breakpoints image and text are updated </li></ul></ul>
  85. 85. Editor & Double Click Toggle <ul><li>The debug platform provides an action that can be contributed to editors to enable “double click” breakpoint toggling </li></ul><ul><ul><li>The action interacts with the editor’s IToggleBreakpointsTarget </li></ul></ul><ul><li>Contribute the action to your editor with the special RulerDoubleClick action identifier </li></ul><ul><li><extension point=&quot;org.eclipse.ui.editorActions&quot;> </li></ul><ul><li><editorContribution </li></ul><ul><li>targetID=&quot;pda.editor&quot; </li></ul><ul><li>id=&quot;pda.rulerActions&quot;> </li></ul><ul><li><action </li></ul><ul><li>label=&quot;Not Used&quot; class=&quot;org.eclipse.debug.ui.actions. </li></ul><ul><li>RulerToggleBreakpointActionDelegate &quot; </li></ul><ul><li>style=&quot;push&quot; </li></ul><ul><li>actionID=&quot; RulerDoubleClick &quot; </li></ul><ul><li>id=&quot;pda.doubleClickBreakpointAction&quot;/> </li></ul>
  86. 86. Breakpoint Properties <ul><li>Breakpoints have editable properties </li></ul><ul><ul><li>Hit count </li></ul></ul><ul><ul><li>Suspend policy </li></ul></ul><ul><ul><li>Enablement </li></ul></ul><ul><ul><li>Condition </li></ul></ul><ul><li>Breakpoint editors are not currently provided by the platform </li></ul><ul><ul><li>The Java debugger provides its own </li></ul></ul>
  87. 87. Breakpoint Summary <ul><li>Determine the kinds of breakpoints your debugger will support and contribute an <breakpoint> extension for each </li></ul><ul><li>Create an implementation of IBreakpoint for each </li></ul><ul><li>Define the <marker> extension associated with each breakpoint kind, enumerating attributes </li></ul><ul><li>Implement breakpoint installation in your debug target via its IBreakpointListener interface </li></ul><ul><li>Implement IBreakpointManagerListener in your debug target to support “skip breakpoints” </li></ul><ul><li>Ensure that you have a source code editor; this can be as simple as a subclass of the standard TextEditor </li></ul><ul><li>Create an implementation of an IToggleBreakpointsTarget adapter using, and register the adapter with your editor </li></ul><ul><li>Contribute a RulerToggleBreakpointActionDelegate to your editor using the <editorActions> extension point </li></ul><ul><li>Provide images and labels in model presentation </li></ul><ul><li>Create breakpoint properties editor if desired </li></ul>
  88. 88. Module 5: Source Lookup Source Lookup Framework
  89. 89. Introduction <ul><li>Highlighting the current source code line or statement </li></ul><ul><li>The debugger has to find source code for a binary location and display that source code in the editor. </li></ul><ul><li>Typically, finding source code means looking for a particular file along a path of directories (or zips or jars or databases or …) </li></ul>
  90. 90. Source Lookup Players <ul><li>Launch </li></ul><ul><ul><li>each launch has a source locator </li></ul></ul><ul><li>Source Locator </li></ul><ul><ul><li>locates source element for a stack frame </li></ul></ul><ul><li>Stack Frame </li></ul><ul><ul><li>provides context for source lookup </li></ul></ul><ul><li>Debug Model Presentation </li></ul><ul><ul><li>provides editor mapping for source element </li></ul></ul>
  91. 91. The Basic Source Lookup Interaction <ul><li>A stack frame is selected </li></ul><ul><li>The source locator finds a source element for a stack frame </li></ul><ul><li>The debug model presentation maps the source element to an editor input and editor id </li></ul><ul><li>The platform opens the editor </li></ul><ul><ul><li>Positions to the line specified by the stack frame </li></ul></ul><ul><ul><li>Adds instruction pointer annotation for the stack frame </li></ul></ul>Stack Frame Source Locator Source Element Debug Model Presentation Editor Id Editor Input
  92. 92. Source Lookup Framework <ul><li>An implementation of a source locator with a standard ‘search along a path’ type of source locator, which consists of: </li></ul><ul><ul><li>director – holds the ordered list that is the “path” </li></ul></ul><ul><ul><li>participants – map stack frames to filenames </li></ul></ul><ul><ul><li>containers – find files by filename in directories, zips, jars, etc. </li></ul></ul><ul><li>The director-container-participant trio is similar to a Unix® path </li></ul><ul><li> Containers </li></ul><ul><li>.:/shared/java/classes : /user/bin/jre/lib/tools.jar </li></ul>Director
  93. 93. Director Interaction <ul><li>To locate source for a stack frame, the director iterates through its participants. For each participant: </li></ul><ul><ul><li>The director asks the participant to translate the stack frame into a source file name </li></ul></ul><ul><ul><li>The director iterates through its source containers asking each container for the source element matching a file name </li></ul></ul>Stack Frame Director Participant Filename Containers Source Element
  94. 94. Source Lookup Director Continued <ul><li>The default implementation of the source lookup director provides an implementation of a ‘path’ as a consistently ordered sequence of containers </li></ul><ul><li>Leaving only two artifacts to be created </li></ul><ul><ul><li>Initial participants – the objects that map stack frames to file names </li></ul></ul><ul><ul><li>Initial set of containers – the places to search for source files </li></ul></ul><ul><li>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. </li></ul>
  95. 95. Source Lookup Participants <ul><li>A source lookup director usually has one participant </li></ul><ul><ul><li>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 </li></ul></ul><ul><li>To initialize your director with participants </li></ul><ul><ul><li>Subclass AbstractSourceLookupDirector and override initializeParticipants() </li></ul></ul><ul><li>public void initializeParticipants() { </li></ul><ul><li>addParticipants( new ISourceLookupParticipant[] { </li></ul><ul><li>new JavaSourceLookupParticipant()}); </li></ul><ul><li>} </li></ul>
  96. 96. Default Source Lookup Path <ul><li>The default source lookup path consists of one container </li></ul><ul><ul><li>The DefaultSourceContainer </li></ul></ul><ul><ul><li>Uses an ISourcePathComputer to compute the default source path. </li></ul></ul><ul><li>On each launch the source path computer computes the source path </li></ul><ul><ul><li>Allows a source path to be dynamically generated on each launch </li></ul></ul><ul><li>Use the <sourcePathComputer> extension to contribute a source path computer. </li></ul><ul><ul><li>A launch configuration type extension can specify a source path computer </li></ul></ul><ul><ul><li>You implement ISourcePathComputerDelegate which computes a default set of source containers for a launch configuration </li></ul></ul>
  97. 97. Instantiating a Source Locator <ul><li>A launch delegate can instantiate a source locator and set it on a launch object </li></ul><ul><li>However, if you don’t want to write code to instantiate the source locator when your launch delegate sets up the launch, then… </li></ul><ul><ul><li>The framework can use the <launchConfigurationType> and <sourceLocator> extensions to instantiate the source locator for you </li></ul></ul>
  98. 98. Source Containers <ul><li>The platform provides implementations of standard source containers </li></ul><ul><ul><li>Workspace folders, projects, and archives </li></ul></ul><ul><ul><li>Local file system directories and archives </li></ul></ul><ul><li>The set of containers is extensible </li></ul><ul><ul><li>Contribute new types of containers with the <sourceContainerTypes> extension point </li></ul></ul><ul><ul><li>If you contribute a source container, you also need to contribute a corresponding <sourceContainerPresentation> to provide an icon and browser </li></ul></ul><ul><ul><ul><li>The browser is used to choose and edit a source container </li></ul></ul></ul>
  99. 99. Source Path Editing <ul><li>The framework provides a UI to edit a source lookup path </li></ul><ul><ul><li>Source lookup tab – launch configuration tab provides a UI for configuring and modifying a source lookup path </li></ul></ul><ul><ul><li>Users may specify an explicit path (set of containers) to search, or specify to use the default source path </li></ul></ul>
  100. 100. The Source Lookup Model
  101. 101. The Source Lookup Model Continued
  102. 102. Source Highlighting <ul><li>Text editors </li></ul><ul><ul><li>Positions the editor to the stack frame line number </li></ul></ul><ul><ul><li>Highlights to statement ( charStart() , charEnd() ) or line (-1,-1) </li></ul></ul><ul><ul><li>Distinguishes top and non-top stack frames </li></ul></ul><ul><ul><li>Upon thread resume/terminate automatically removes annotations </li></ul></ul><ul><ul><li>Colors are styles are preference controllable </li></ul></ul><ul><li>Non-text Editors </li></ul><ul><ul><li>The IDebugEditorPresentation API provides an escape mechanism </li></ul></ul>
  103. 103. Source Highlighting in Text Editors Source Highlighting for Text Editors
  104. 104. Source Highlighting in non-Text Editors Source Highlighting for Non-Text Editors
  105. 105. Source Highlighting in Multipane Editors Source Highlighting for Multi-Part Text Editors
  106. 106. Instruction Pointer Presentation <ul><li>The debug platform provides support to override default instruction pointers displayed in editor rulers. </li></ul><ul><ul><li>Do this by having your debug model presentation implement the optional interface IInstructionPointerPresentation </li></ul></ul><ul><li>Allows customization of </li></ul><ul><ul><li>Provide the raw annotations (part of text framework, out of scope) </li></ul></ul><ul><ul><li>Or provide image and hover text </li></ul></ul>
  107. 107. Source Lookup Summary <ul><li>Create an implementation of ISourceLookupParticipant to provide file names for your stack frames </li></ul><ul><li>Create subclass of AbstractSourceLookupDirector and override initializeParticipants to instantiate your participant </li></ul><ul><li>Create an implementation of ISourcePathComputerDelegate that computes a default source lookup path for your launch configurations </li></ul><ul><li>Define a <sourceLocator> extension to point to your director </li></ul><ul><li>Define a <sourcePathComputer> extension to </li></ul><ul><li>In your <launchConfigurationType> extension, refer to (4) and (5) </li></ul>
  108. 108. Module 6: The Variables View and More Standard I/O Console Perspective, Views, Actions Expression Management
  109. 109. Introduction <ul><li>Standard I/O Console: </li></ul><ul><ul><li>Displays content from standard input/output streams </li></ul></ul><ul><ul><li>Allows for pattern matching </li></ul></ul><ul><li>Variables, Expressions and Registers Views: </li></ul><ul><ul><li>Basic structure, view inputs </li></ul></ul><ul><ul><li>Displaying details for a selection </li></ul></ul><ul><ul><li>Variable labels and columns </li></ul></ul><ul><ul><li>Emphasizing variables that change value </li></ul></ul><ul><ul><li>Displaying “logical structures” vs. raw implementation structures </li></ul></ul><ul><ul><li>Editing variable values </li></ul></ul><ul><li>Expression Management: </li></ul><ul><ul><li>Watch expressions and custom expressions </li></ul></ul><ul><ul><li>Evaluating watch expressions using delegates </li></ul></ul><ul><ul><li>Creating a custom watch expression from a variable </li></ul></ul>
  110. 110. Standard I/O Console <ul><li>There is a console framework: org.eclipse.ui.console </li></ul><ul><ul><li>Provides the Console view that displays all IConsoles </li></ul></ul><ul><ul><li>Has implementations of text stream based consoles that can be extended </li></ul></ul><ul><ul><ul><li>Can attach output streams to the console </li></ul></ul></ul><ul><ul><ul><li>Also has input stream connected to the keyboard </li></ul></ul></ul><ul><li>The debug platform extends this framework and provides a standard I/O console </li></ul><ul><ul><li>Connects standard out and error streams from an IProcess to the console </li></ul></ul><ul><ul><li>Connects the input stream (keyboard) to the standard in of the IProcess </li></ul></ul>
  111. 111. Hooking up an IProcess <ul><li>A debug target usually has an associated system process </li></ul><ul><ul><li>Abstracted by IProcess </li></ul></ul><ul><ul><li>IProcess implementation is provided by the debug platform for java.lang.Process </li></ul></ul><ul><ul><li>An IProcess has an IStreamsProxy providing access to its streams </li></ul></ul>exec(…) java. lang. Process IProcess IStreams Proxy Console
  112. 112. Console Pattern Matching <ul><li>Can contribute <consolePatternMatchListeners> </li></ul><ul><ul><li>To specific consoles (using enablement expressions) </li></ul></ul><ul><ul><li>Specify a regular expression for pattern matching </li></ul></ul><ul><ul><li>Notified of matches, can perform arbitrary actions </li></ul></ul><ul><ul><ul><li>Like, adding an IHyperlink to the console </li></ul></ul></ul>
  113. 113. Variables View <ul><li>Displays variables returned by the selected stack frame </li></ul><ul><li>IStackFrame.getVariables() </li></ul><ul><li>Displays current values of variables, along with children variables </li></ul><ul><li>Variables are retrieved asynchronously </li></ul>
  114. 114. Registers View <ul><li>Similar to Variables View </li></ul><ul><li>Displays register groups returned by selected stack frame </li></ul><ul><li>IStackFrame.getRegisterGroups() </li></ul>
  115. 115. Expressions View <ul><li>Displays expressions returned by the Expression Manager </li></ul><ul><li>When a stack frame is selected, watch expressions are evaluated to determine their value </li></ul><ul><li>Debuggers must provide delegates to perform the evaluation </li></ul><ul><li>More in Expression Management </li></ul>
  116. 116. Detail Pane <ul><li>Source viewer used to display details for the current selection </li></ul><ul><li>Text is provided by a debug model presentation asynchronously </li></ul><ul><ul><li>computeDetail(IValue value, IValueDetailListener listener) </li></ul></ul><ul><ul><li>Java Debugger does a toString() evaluation </li></ul></ul><ul><li>A debug model presentation can specify a SourceViewerConfiguration to install in the details area </li></ul><ul><ul><li>Allows for code assist, formatting, etc. </li></ul></ul>
  117. 117. Variable Columns <ul><li>The variables view can be displayed with columns or as a standard tree </li></ul><ul><li>The standard tree view labels are populated from the debug model presentation </li></ul><ul><ul><li>getText(Object element) </li></ul></ul><ul><li>The platform defines a standard set of columns that can be populated from the standard model: </li></ul><ul><ul><li>name, value, declared type, and actual type </li></ul></ul><ul><li>A debugger can provide its own columns and custom cell editors </li></ul><ul><ul><li>Discussed in the Custom Integration tutorial </li></ul></ul>
  118. 118. Emphasizing Value Changes <ul><li>Variables that change value while stepping are rendered in red </li></ul><ul><ul><li>If columns are shown, the background is yellow instead </li></ul></ul><ul><ul><li>A variable must implement hasValueChanged() for this to work </li></ul></ul><ul><ul><li>Spec says: “returns whether the value of this variable has changed since the last suspend event” </li></ul></ul><ul><li>Implementation in the Java debugger </li></ul><ul><ul><li>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, … </li></ul></ul><ul><ul><li>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. </li></ul></ul><ul><ul><li>When a variable counter == debug counter its value has changed </li></ul></ul>
  119. 119. Logical Structures <ul><li>A logical structure is an alternate presentation of a variable’s value </li></ul><ul><ul><li>Often, it’s more natural to navigate a complex data structure via an alternate semantic presentation of the value, rather than it’s implementation. </li></ul></ul><ul><ul><li>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 </li></ul></ul><ul><li>There are two extension points for contributing logical structures </li></ul><ul><ul><li>The <logicalStructureTypes> extension point is used to contribute one logical structure per variable value </li></ul></ul><ul><ul><li>The <logicalStructureProviders> extension point is used to contribute a delegate that can provide multiple logical structures for a variable value dynamically </li></ul></ul>
  120. 120. Logical Structure Type Extension <ul><li>Provides a single logical structure for per value </li></ul><ul><ul><li>Has a description that is presented in the “Show As >” menu </li></ul></ul><ul><ul><ul><li>For example, “Show As > Array” </li></ul></ul></ul><ul><ul><li>Contributes an ILogicalStructureTypeDelegate to translate value </li></ul></ul><ul><li>public boolean providesLogicalStructure(IValue) </li></ul><ul><li>public IValue getLogicalStructure(IValue) </li></ul><ul><li>public String getDescription(IValue)** </li></ul><ul><li>** (this method is actually defined by ILogicalStuctureTypeDelegate2 ) </li></ul>
  121. 121. Logical Structure Provider <ul><li>Provides logical structure types for a variable value by implementing ILogicalStructureProvider </li></ul><ul><li>public ILogicalStructureType[] getLogicalStructureTypes(IValue) </li></ul><ul><ul><li>Allows for a dynamic set of structures to be provided per value </li></ul></ul><ul><ul><li>For example the Java debugger uses this extension point to allow users to configure logical structures via code snippets </li></ul></ul>
  122. 122. Extensible Logical Structures for Java Debugger
  123. 123. Logical Structures
  124. 124. Value Editing <ul><li>The variables view provides a standard dialog for editing a variable’s value (for variables that support value modification) </li></ul><ul><ul><li>You can also type into the details area and save (Ctrl-S) </li></ul></ul><ul><li>Calls setValue(String expression) on variable </li></ul><ul><li>Custom dialogs can be provided by debuggers using an extension point </li></ul><ul><ul><li>More details in the Custom Integration tutorial </li></ul></ul>
  125. 125. Expression Management <ul><li>Expressions are handled by the Expression Manager </li></ul><ul><ul><li>Expressions are registered with the manager </li></ul></ul><ul><ul><li>The expressions view displays all registered expressions </li></ul></ul><ul><li>IWatchExpression is an expression implementation provided by the platform </li></ul><ul><ul><li>Consists of a text expression and an evaluation context (i.e. stack frame) </li></ul></ul><ul><ul><li>Clients must contribute a delegate that can compute value from expression and context at <org.eclipse.debug.core.watchExpressionDelegates> </li></ul></ul><ul><ul><li>Evaluations are done asynchronously and fire appropriate events </li></ul></ul><ul><ul><li>Result contains a value or error messages </li></ul></ul><ul><li>Clients can implement IExpression to create custom expressions </li></ul>
  126. 126. Creating Watch Expressions <ul><li>The debug platform provides actions to allow user to provide text for a new watch expression. </li></ul><ul><li>Platform also provides an action to create a watch expression from a selected variable </li></ul><ul><ul><li>By default, the expression is the variable’s name </li></ul></ul><ul><ul><li>A debugger can customize this by providing an IWatchExpressionFactoryAdapterExtension registered as an adapter on a variable </li></ul></ul><ul><ul><li>The factory is used to </li></ul></ul><ul><ul><ul><li>Determine if the action should be enabled for a variable </li></ul></ul></ul><ul><ul><ul><li>Create an expression for a variable </li></ul></ul></ul>
  127. 127. Variables View and More Summary <ul><li>Standard I/O Console: </li></ul><ul><li>Wrapper your process with an IProcess to connect streams to console framework </li></ul><ul><li>Contribute a <consolePatternMatchListeners> extension for custom pattern matching </li></ul><ul><li>Variables, Expressions and Registers Views: </li></ul><ul><li>Use the debug model presentation to customize view labels and details </li></ul><ul><li>Contribute a SourceViewerConfiguration for code assist and formatting in the detail pane </li></ul><ul><li>Implement IVariable ’s hasVariableChanged(…) so variables are emphasized red when they change value </li></ul><ul><li>Contribute a <logicalStructureTypes> or <logicalStructureProviders> extension to provide logical structures </li></ul><ul><li>Implement IVariable ’s setValue(…) so variables can be edited </li></ul><ul><li>Expression Management: </li></ul><ul><li>Contribute a <watchExpressionDelegates> extension to evaluate watch expressions </li></ul><ul><li>Provide an IWatchExpressionFactoryAdapterExtension as an adapter on a variable for custom watch expression creation </li></ul>
  128. 128. Legal Notices <ul><li>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. </li></ul><ul><li>IBM and the IBM logo are trademarks or registered trademarks of IBM Corporation, in the United States, other countries or both. </li></ul><ul><li>Rational and the Rational logo are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries or both. </li></ul><ul><li>Java and all Java-based marks, among others, are trademarks or registered trademarks of Sun Microsystems in the United States, other countries or both. </li></ul><ul><li>Eclipse and the Eclipse logo are trademarks of Eclipse Foundation, Inc. </li></ul><ul><li>Other company, product and service names may be trademarks or service marks of others. </li></ul><ul><li>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 &quot;AS IS&quot; 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. </li></ul>