CDT/cdt-debug-dsf-gdb-extensibility

How to extend DSF-GDB

An example of how to extend DSF-GDB can be found in org.eclipse.cdt.examples.dsf.gdb.

Thanks to DSF, DSF-GDB can easily be extended by replacing/adding/removing different services. To do this one can create a custom service factory by:

1. sub-class the DSF-GDB service you want to modify. As of CDT 8.8, CDT provides a GDB<service>_HEAD class for each DSF-GDB service. Users can extend the proper such class to automatically extend the top-most version of such service (e.g., GDBProcesses_HEAD, GDBRunControl_NS_HEAD), or create your entirely new version (by subclassing AbstractDsfService).
2. sub-class org.eclipse.cdt.dsf.gdb.launching.GdbLaunchDelegate and override GdbLaunchDelegate#newServiceFactory().
3. sub-class the appropriate service factory such as org.eclipse.cdt.dsf.gdb.service.GdbDebugServicesFactory or org.eclipse.cdt.dsf.gdb.service.GdbDebugServicesFactoryNS (for GDB non-stop debugging) and override any services' creation method to instantiate your own version of the service. Other versions of GDB can also be handled in those services' creation methods.
4. Finally, make sure your customized "GDB launch delegate" class gets instantiated by extending the org.eclipse.debug.core.launchDelegates extension point.

In some cases where small changes are required to MI commands, overriding the entire service may be unnecessary. Instead, one can extend DSF-GDB's command factory. To do this, one still requires a new services factory, but only to be able to specify the new command factory:

1. sub-class any MI command class and its output class to add your changes. These are found in org.eclipse.cdt.dsf.mi.service.command.commands and org.eclipse.cdt.dsf.mi.service.command.output
2. sub-class org.eclipse.cdt.dsf.mi.service.command.CommandFactory and override/add your necessary changes.
3. sub-class org.eclipse.cdt.dsf.gdb.launching.GdbLaunchDelegate and override GdbLaunchDelegate#newServiceFactory().
4. sub-class org.eclipse.cdt.dsf.gdb.service.GdbDebugServicesFactory and override GdbDebugServicesFactory#createCommandControl() to pass in your own command factory.

Once you have the above framework in place, overriding other DSF-GDB services/commands becomes extremely quick.

Notes

Quick notes that were posted in this email:

• *VMNode classes fill the data of the view using the DSF services.
  • updatePropertiesInSessionThread() is for labels
  • updateElementsInSessionThread() is for actual element (each thread for example)
  • You can start debugging those methods and follow them into the DSF service calls
• Classes extending IDsfService and AbstractDsfService are the different DSF services CDT provides. They deal with getting the data from GDB.
  • You can look at the interface of a service, e.g., IProcesses/IMIProcesses/IGDBProcesses for the different things the service provides.
  • You can then debug the call in question, to see why it is not finding the right information from GDB.
• When looking at DSF services, take the time to figure out the hierarchy and which class is used for which version of GDB. You don't want to modify one class only to realize it is not used for that GDB version :)
• GdbLaunchDelegate is the DSF-GDB delegate associated with every CDT launch configuration type. This is the entry point of every launch.
  • You can either define a new configuration type, or you can add a new delegate to the exiting config types to use your own.
• GdbDebugServicesFactory is used to instantiate the different DSF services based on GDB versions. It can be useful to set breakpoints there to make sure you are using the right service version, or your own service implementation. Don't forget to update this class if you are overriding a service.
• FinalLaunchSequence is used to configure GDB the way you need for your type of session. As Jason said, this is tricky to extend, but we've put in some effort to make it easier than before...
• Be careful to focus on the MI command classes found in org.eclipse.cdt.dsf.mi.service.command. They have the exact same names as the CDI ones (because DSF was not part of CDT at the start). We do not use the ones in org.eclipse.cdt.debug.mi for DSF.
• If you use an in-house GDB things may require some tweaks. If that GDB answers differently to some commands, you will have to compensate by overriding the relevant MI* commands.
• You can use CommandFactory to change some details about an MI command, but if that is not enough, you will need to change the DSF service itself to use a different MI command (or use it in a different way)
• If you see a view with a title in italic, it often means there is a missing rm.done() call, probably in a DSF service implementation you changed. In that case the view does not get all the info it is waiting for and 'hangs'.

Requested improvements

This section lists the different use cases that the community would like to see addressed to allow for easier extensibility of DSF-GDB.

• Allow FinalLaunchSequence to be easily overridden (completed in bug 321084)
• Allow to easily add a new service (completed in bug 326951 and bug 338769)
• Allow to override the use of -exec-run vs -exec-continue at startup (completed in bug 319257)
• Allow to extend the view model (completed in bug 462623)
• Allow to easily replace adapters (completed in bug 462623)
• Provide top class for DSF-GDB services to allow better extensibility (completed in bug 469763)