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.
Difference between revisions of "CDT/Archive/cdt-core/designs/CommandLauncher"
(Initial save) |
(More detail) |
||
| Line 1: | Line 1: | ||
| − | + | = Introduction = | |
The <code>org.eclipse.cdt.core.CommandLauncher</code> extension-point was added post-CDT6 (CDT6.1 / CDT7). The functionality was proposed and implemented in {{bug|279818}} | The <code>org.eclipse.cdt.core.CommandLauncher</code> extension-point was added post-CDT6 (CDT6.1 / CDT7). The functionality was proposed and implemented in {{bug|279818}} | ||
| − | + | == Motivation == | |
| − | Many places in CDT need to run external tools. [[CDT/cdt-core | cdt.core]] provides a mechanism for contributing such <code>CommandLauncher</code>s and UI is provided for allowing users to configure | + | Many places in CDT need to run external tools. [[CDT/cdt-core | cdt.core]] provides a mechanism for contributing such Process creation <code>CommandLauncher</code>s and UI is provided for allowing users to configure them. |
| − | CDT.core provides API for discovering and creating | + | CDT.core provides API for discovering and creating an appropriate CommandLauncher for a process type. |
| − | + | 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 (via a Remote CommandLauncher, say) the API is flexible enough to allow this. | |
| − | + | The places in CDT which previously used the cdt.core's <code>Spawner</code> or <code>ProcessFactory</code>, can use <code>CommandLauncherFactory</code> without needing to know how the user has configured their workspace. | |
| − | * <code>CommandLauncher</code> A class extending org.eclipse.cdt.core.CommandLauncher. Provides an #execute(...) method which returns <code>java.lang.Process</code> for a given execution. | + | CommandLaunchers can specify the types of Processes they're capable of launching, and users can configure a chosen CommandLauncher per-Workspace or per-Project. |
| + | |||
| + | == Terminology == | ||
| + | |||
| + | * <code>processType</code> A type of process we wish to run e.g. Run Launch, Debug Launch, Build. See <code>org.eclipse.cdt.core.CommandLauncherFactory</code> for supported processTypes. | ||
| + | |||
| + | * <code>CommandLauncher</code> A class extending org.eclipse.cdt.core.CommandLauncher. Provides an #execute(...) method which returns <code>java.lang.Process</code> for a given execution. | ||
* <code>CommandLauncherDialog</code> A contributed dialog which allows configuring advanced preferences on the CommandLauncher | * <code>CommandLauncherDialog</code> A contributed dialog which allows configuring advanced preferences on the CommandLauncher | ||
| Line 19: | Line 25: | ||
* <code>CommandLauncherFactory</code> A 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. | * <code>CommandLauncherFactory</code> A 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. | ||
| − | + | = Integrating = | |
| − | + | == Extension Points == | |
| − | + | === org.eclipse.cdt.core.CommandLauncher === | |
The CommandLauncher extension point allows contribution a class which extends <code>org.eclipse.cdt.core.CommandLauncher</code>. See <code>org.eclipse.cdt.internal.core.WrappedCommandLauncer</code> | The CommandLauncher extension point allows contribution a class which extends <code>org.eclipse.cdt.core.CommandLauncher</code>. See <code>org.eclipse.cdt.internal.core.WrappedCommandLauncer</code> | ||
| + | |||
| + | The base class provides functionality for obtaining context on the <code>process<code> 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: <code>getPreference(String key)</code> for fetching preferences persisted by the CommandLauncher's Advanced dialog, or by a user of the API | |
| + | |||
| + | === org.eclipse.cdt.ui.CommandLauncherDialog === | ||
| + | |||
| + | This extension point allows contributing an '''Advanced...''' dialog for configuring your Command Launcher. The dialog should extend AbstraceCommandLaucnherDialog which provides the utility methods: <code>getInitialValue(String key, String defaultValue)</code> for getting Initial values of Preferences and <code>fPrefStore</code> for persisting preferences. | ||
| + | [[Image:CommandLauncherUI.png]] | ||
| + | == API == | ||
| + | |||
| + | === CommandLauncherFactory === | ||
| + | |||
| + | The <code>CommandLauncherFactory</code> in cdt.core is the central arbitrator of CommandLaunchers. CommandLaunchers are created with: | ||
| + | |||
| + | <code>createCommandLauncher(IProject project, String processType, Object context)</code> | ||
| + | |||
| + | The built-in ProcessTypes are defined in the CommandLauncherFactory class, including: <code>cdt.all, cdt.launch.debug, cdt.launch.run ...</code> The Factory stores the mapping from processType => CommandLauncherType using scoped preferences. | ||
| + | |||
| + | = 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. | |
Revision as of 17:16, 23 June 2009
Contents
Introduction
The org.eclipse.cdt.core.CommandLauncher extension-point was added post-CDT6 (CDT6.1 / CDT7). The functionality was proposed and implemented in bug 279818
Motivation
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.
CDT.core provides API for discovering and creating an appropriate CommandLauncher for a process type.
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 (via a Remote CommandLauncher, say) the API is flexible enough to allow this.
The places in CDT which previously used the cdt.core's Spawner or 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.
Terminology
-
processTypeA type of process we wish to run e.g. Run Launch, Debug Launch, Build. Seeorg.eclipse.cdt.core.CommandLauncherFactoryfor supported processTypes.
-
CommandLauncherA class extending org.eclipse.cdt.core.CommandLauncher. Provides an #execute(...) method which returnsjava.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.
Integrating
Extension Points
org.eclipse.cdt.core.CommandLauncher
The CommandLauncher extension point allows contribution a class which extends org.eclipse.cdt.core.CommandLauncher. See org.eclipse.cdt.internal.core.WrappedCommandLauncer
The base class provides functionality for obtaining context on the process<code> 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: <code>getPreference(String key) for fetching preferences persisted by the CommandLauncher's Advanced dialog, or by a user of the API
org.eclipse.cdt.ui.CommandLauncherDialog
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.
API
CommandLauncherFactory
The 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.
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.