CDT/Archive/cdt-core/designs/CommandLauncher

Note: The contents of this page refer to design documents reflecting work in progress of Eclipse CDT features and for some features that have never been implemented. Therefore they may not refer to the current state of CDT.

Introduction

The 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

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.

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 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

• processType A type of process we wish to run e.g. Run Launch, Debug Launch, Build. See org.eclipse.cdt.core.CommandLauncherFactory for supported processTypes.

• CommandLauncher A class extending org.eclipse.cdt.core.CommandLauncher. Provides an #execute(...) method which returns java.lang.Process for a given execution.

• CommandLauncherDialog A contributed dialog which allows configuring advanced preferences on the CommandLauncher

• CommandLauncherFactory 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.

• Custom vs. Process_type_all At 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.

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 to be created. As well as the Command String, the Command Launcher has access to the following context:

1. IProject - Project the process is being created for
2. ProcessType - The type of process being created
3. 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

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.

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.