Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
org.eclipse.cdt.core.CommandLauncher extension-point was added post-CDT6 (CDT6.1 / CDT7). It allows users to customise, at Project or Workspace scope, how external Processes are launched and run.
The functionality was proposed and implemented in bug 279818
Many places in CDT need to run external tools. cdt.core provides a mechanism for contributing such Process creation
CommandLaunchers and UI is provided for allowing users to configure them.
This extension point makes the act of Process creation orthogonal to the type and site of process launch. Contributors, and users, can therefore provide one place for configuring and selecting how their external commands are run. Whether they want to run their processes locally, wrap their commands in a sub-shell / script, or perform a more esoteric run (on a remote machine, say) the API is flexible enough to allow this.
The places in CDT which previously used the cdt.core's
ProcessFactory, can use
CommandLauncherFactory without needing to know how the user has configured their workspace.
CommandLaunchers can specify the types of Processes they're capable of launching, and users can configure a chosen CommandLauncher per-Workspace or per-Project.
processTypeA type of process we wish to run e.g. Run Launch, Debug Launch, Build. See
org.eclipse.cdt.core.CommandLauncherFactoryfor supported processTypes.
CommandLauncherA class extending org.eclipse.cdt.core.CommandLauncher. Provides an #execute(...) method which returns
java.lang.Processfor a given execution.
CommandLauncherDialogA contributed dialog which allows configuring advanced preferences on the CommandLauncher
CommandLauncherFactoryA factory for creating CommandLaunchers based on the process type currently being launched. Uses user preferences for selecting the appropriate CommandLauncher, and provides utility methods for getting and setting Advanced preferences on the launcher.
Custom vs. Process_type_allAt the Workspace / Project scope, users can configure whether they want a single command launcher type or whether they want to specify different CommandLanchers for different process types.
The CommandLauncher extension point allows contribution a class which extends
The base class provides functionality for obtaining context on the
Process to be created. As well as the Command String, the Command Launcher has access to the following context:
- IProject - Project the process is being created for
- ProcessType - The type of process being created
- Object - generic context object provided by the user
There is also API on the base class:
getPreference(String key) for fetching preferences persisted by the CommandLauncher's Advanced dialog, or by a user of the API
This extension point allows contributing an Advanced... dialog for configuring your Command Launcher. The dialog should extend AbstraceCommandLaucnherDialog which provides the utility methods:
getInitialValue(String key, String defaultValue) for getting Initial values of Preferences and
fPrefStore for persisting preferences.
CommandLauncherFactory in cdt.core is the central arbitrator of CommandLaunchers. CommandLaunchers are created with:
createCommandLauncher(IProject project, String processType, Object context)
The built-in ProcessTypes are defined in the CommandLauncherFactory class, including:
cdt.all, cdt.launch.debug, cdt.launch.run ... The Factory stores the mapping from processType => CommandLauncherType using scoped preferences.
The factory is also responsible for persisting the Advanced preferences of the CommandLaunchers, as well as providing the right set of scoped preferences at the right time (i.e. workspace / Project & cdt.all vs. custom per-processType).
Examples & Tests
WrappedCommandLauncher & WrappedCommandLauncherDialog provide a concreate implementation of a contributed CommandLauncher.
Tests for the contributed functionality are in CommandLauncherFactoryTests in the cdt.core testsuite.