Debugging requires communicating with an entity being debugged (debuggee or debug target). Communication provides the debugger with control and introspection of the debuggee. Quite often the debuggee is running in a separate process, possibly on a remote machine or device. The debuggee may already be executing (for example, a server), or it might need to be started (for example, a local Java application). Launching is the process of starting and/or establishing communication with the debuggee. The debug platform provides facilities to assist developers with common launching tasks.
The debug platform doesn't know how to launch anything by itself. It needs answers to the following questions:
To answer these questions, the debug platform provides an extension point: org.eclipse.debug.core.launchConfigurationTypes
. For example, in the upcoming exercise a launcher is created to ping an internet address. So we would answer the questions as follows:
name = "Ping" id = "ping.launchType"
run
ILaunchConfiruationDelegate
to execute a command line of the form "ping <address>
" For each launch configuration type extension, the platform provides an implementation of ILaunchConfigurationType
, available from the ILaunchManager
.
Some aspects of a launch are configurable. For example, when debugging a Java application, one specifies a main class , program arguments, and VM arguments. The debug platform provides ILaunchConfiguration
's to persist attributes of a launch such that they can be edited and re-launched in the future. Launch configurations are created from their associated type. The platform provides atomic editing of launch configurations via a working copy model. An ILaunchConfigurationWorkingCopy
is obtained from its original configuration, which provides an API for setting attributes as key/value pairs. Modifications are committed to the original launch configuration when doSave()
is called. As the attributes of a launch are domain specific, each launch configuration type is responsible for defining its configurable attributes. Generally this is done by documenting a set attribute keys and their permitted values (for example, IJavaLaunchConfigurationConstants
).
The debug platform doesn't know how to launch anything by itself. It delegates to implementations provided by each launch type extension. However, launch delegate implementations should subclass the abstract LaunchConfigurationDelegate
class provided by the platform. This class provides useful function common to launch delegates - such as building relevant projects and warning the user of compilation errors in the workspace prior to launching.
The actual launch is performed by the launch(...)
method. The delegate is responsible for reading attributes from a launch configuration and creating and adding one or more IProcess
'es and/or IDebugTarget
's to an ILaunch
object (we'll learn about debug targets in a later section). A launch object is just a container of processes and/or debug targets and is visible as a root element in the Debug view.
The debug platform abstracts a system processes as an IProcess
and provides an implementation that wrappers a java.lang.Process
(use the DebugPlugin.newProcess(...)
factory method to create a process). A process provides access to its I/O streams which are displayed in a console. Clients can provide custom implementations of a process if required - for example, to provide access to I/O streams from a remote process.
Launch configurations can be created and edited programmatically. As well, the platform provides a dialog to allow users to create and modify launch configurations. The dialog displays all available launch configuration types in a tree with all existing launch configurations as children. When a configuration is selected a set of tabs is shown allowing users to see and modify launch parameters.
The org.eclipse.debug.ui.launchConfigurationTabGroups
extension is used to contribute a set of tabs for a particular type of launch configuration. The extension point contributes an implementation of ILaunchConfigurationTabGroup
which is responsible for instantiating the tabs to be displayed for a launch configuration. Implementations should subclass the AbstractLaunchConfigurationTabGroup
class provided by the platform. Tab group implementations are usually quite simple - for example, the Java Application tab group is a class with one method.
Most of the work goes on inside the ILaunchConfigurationTab
's. Again, the platform provides an AbstractLaunchConfigurationTab
that should be extended. Each tab creates controls and is notified to display attributes from a launch configuration, write values back to a launch configuration (working copy), and validate current settings.
This exercise demonstrates a launcher that executes the familiar "ping" command. Users specify an address to ping using the launch configuration dialog. From the Welcome Samples
Page (Help -> Welcome -> Samples) Import the Ping sample into your workspace. Hint: to quickly find the
locations in the code that need to be completed, search for the text
"Exercise 3", or look for it in
the Tasks
view. Note: Tasks in the plugin.xml file do now show
up
automatically in the task view, only the tasks in the java files will
be there. You must complete the following:
PingLaunchDelegate
PingTab