CDT/Archive/designs/workingSets

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.

This document proposes an enhanced (considerably re-worked, actually) dialog for Working Set Configurations. I would like to contribute a patch for the 6.0 release, before M7.

Working Set Configurations

CDT 5.0 provides support for working-set configurations. These provide a means to easily change the active build configurations of the C/C++ projects in a working set to some consistent selection. The current UI has a number of deficiencies of usability and function, and is not extensible to handle rich build-configuration models such as may be defined by custom project natures (usually derived from the C nature).

Current state of the art

The current working-set configuration support contributes a Configs for Working set action to the Build Configurations sub-menu of the Project menu. Invoking this action brings up the following dialog:

This dialog has several functional and usability problems:

• redundant use of the words "config set" in the buttons (and truncation of the word "configuration")
• the Update config set button is required to make changes to configuration selections "stick." Without it, changing a configuration set, selecting another, then returning to the first loses the changes. Even pressing the OK button doesn't persist pending changes
• the -- CURRENT -- configuration set looks like a real configuration set, but it is just a proxy for the line-up of active configurations for the projects. Its relationship to user-defined configuration sets is confusing, especially as it is editable but not persistable
• the Save, Build and Exit button is very confusing. What does it build? Why does it close the dialog? What does it save?
• the serialization of configuration sets is in a plain-text format with spaces to delimit fields. This breaks when working sets, projects, and build configurations have spaces in their names.
• the dialog only handles the basic CDT notion of a project build configuration. It doesn't provide any API to extend it for derived project types, which may define multiple orthogonal dimensions (e.g., debug/release and target platform dimensions). Moreover, some of these dimensions of configuration may permit multiple selections per project

Proposed new UI

The menu action would be renamed to Manage Working Sets... (note the ellipsis indicating a dialog. I would have liked Manage Working Set Configurations..., but it seems to be too long; GNOME, at least, truncates it) and the dialog reworked to look like this:

To address specifically the problems with the current dialog:

• the word "configuration" is used in its entirety and the buttons use standard labeling convention
• changes to project configuration selections "stick" in the dialog without needing to press an update button. The OK button closes the dialog and persists the changes to the preference store. The Cancel button closes without saving
• the labels in the Working set configurations pane clearly indicate which working set is active.
  • A working-set configuration is active if and only if for all of the projects in the working set, their active configurations are as specified by the working set configuration
  • If the the currently active configurations of the projects in a working set do not actually correspond to any of the presets shown in the dialog, then a special configuration is presented (with an italic font) so that the user can see what the current settings are. This special configuration cannot be modified, as it reflects exactly the reality of the workspace. When some other configuration is activated (via the Set Active button, see below), then this special configuration is no longer shown
• the Set Active button (so labeled for consistency with other buttons and menus in CDT) applies the selected working-set configuration to the projects in the workspace. There is a Build button to build a particular configuration without setting it active. When the user presses OK to save changes to the configurations, if any configuration was applied that changed any project's active configuration setting in the workspace, and they were not subsequently built via the Build button, then the user is prompted to build the affected projects (even if Build Automatically is enabled, because it does not trigger a build on project configuration changes)
• serialization will use an XML-formatted string (using IMemento) instead of plain text with space and form-feed delimiters. For backward compatibility, the old format can be read by the new dialog
• the dialog will expose an API on the working-set configuration model that custom project natures can contribute to and extend to implement custom configuration selections. This API is described below and would be internal/provisional, as we are now past API Freeze

Building Working Set Configurations

Showing Working Sets in the Project Explorer

Many people find it convenient to toggle the Project Explorer view to show working sets as top-level elements. This makes for particularly convenient management of build configurations for working sets. In this mode, context menu actions for setting and building configurations of the working sets are provided, as well as a property page for managing the working-set's configurations.

The context menu contributions for working sets look like:

This should be self-explanatory. These menu actions are available only on working sets that include at least one CDT project (implemented by a new property-tester in the expressions framework).

The property page looks like:

This provides the same capabilities as the Manage Working Set Configurations dialog (see above), but scoped to the selected working set.

Recently used working sets

The Eclipse workbench keeps track of recently used working sets. In the CDT context, a working set is "used" when its configurations are edited and/or set active.

For access to building the project configurations specified by a working set configuration, especially when not showing working sets in the Project Explorer, the configurations for the recent working sets are presented in the Build Configurations sub-menu of the Project menu:

Here, we see three recent working sets (in order from most to least recently used) with sub-menus permitting selection of a configuration to build or to set active in the workspace. For working sets that do not define any configurations, they do not show a sub-menu, but can be selected to build whatever configurations are current for the contained projects (an example is the Unmanaged Stuff item).

For the common case of CDT projects that are built by the MBS builder (even if they don't generate makefiles and use an external make tool), the project configurations specified in the working set configuration can be built without having to set them active. In case a project nature does not support building non-active configurations, the working set's select configuration for the project will first be applied, then the project built.

Data Model and Extensibility

The dialog and the menu are driven by a common data model, which implements the IPersistable protocol for saving workbench settings between sessions. The model also follows the example of the Launch Configurations model and others in the platform, providing a read-only view with working copies for modification. The working set configuration model calls these snapshots in order to avoid repetition of the term "working" in names, especially as the semantics are different.

Data model

The data model comprises the following interfaces:

• IWorkingSetConfigurationElement extends IPersistable
  • the base interface, basically specifying only the protocol for saving itself to an IMemento and loading itself from a memento
• IWorkingSetProxy extends IWorkingSetConfigurationElement
  • represents a working set. The name uses the term "proxy" to avoid confusion with the "real" IWorkingSet API
  • this is the top-level node that contains working set configurations. Thus, this element decorates a working set, adding the configurations property to it
• IWorkingSetConfiguration extends IWorkingSetConfigurationElement
  • owned by an IWorkingSetProxy
  • defines a named configuration, which is a line-up of configuration selections for each project in the working set
  • includes operations such as activate() that applies the contained project configurations to the workspace, and build() that builds the selected project configurations on-the-fly (without, if possible, applying them)
• IWorkingSetProjectConfiguration extends IWorkingSetConfigurationElement
  • owned by an IWorkingSetConfiguration
  • specifies the configuration settings for a particular project member of a working set. These settings are at least the ICConfigurationDescription that is set as active for the project. The implementation of the IWorkingSetProjectConfiguration is plugged in according to project natures, providing the extensibility support for additional project build metadata (more about this, below).
    • as in the past, only actual IProject members of a working set are considered. Thus, there is no support for working sets containing only folders or files
  • provides the project-level activate() and build() operations

Access to the configuration data

The data model is maintained by a WorkingSetConfigurationManager. It is responsible for:

• loading the configurations from the workspace metadata (for compatibility, it is seeded from the old string-based preference storage)
• providing access to read-only views of the configurations to clients
  • clients typically retrieve the IWorkingSetProxy for a particular working set, by name
  • the prototypical client is the dynamic "build working set configuration" menu pictured above
• providing mutable snapshots (working copies) of the configurations to clients
  • clients retrieve a snapshot of the workspace at the time of the request. It takes the form of a WorkspaceSnapshot, encapsulating the configuration information for every CDT project, frozen as at the time the snapshot was taken, together with the editable working copies of the working set configurations
  • the prototypical client is the dialog pictured above

The WorkspaceSnapshot, in providing a frozen view of the CDT configuration of every project, makes it easy for implementors of the IWorkingSetProjectConfiguration interface to access their nature-specific configuration data and to compare the current working copy against this original state. This facility is used, for example, by the dialog to determine whether all of the project configurations specified by a working set configuration are currently "active" or not, and which projects have changed and thus need a re-build. The workspace snapshot tracks project configurations using ProjectStates, which can be plugged in by nature providers to implement their specific tests for whether a project needs to be built.

Extensibility

A new extension point is defined, org.eclipse.cdt.ui.workingSetConfigurations, by which the providers of custom project natures (usually extending the core CDT nature) can plug in support for their extended build configuration metadata. This extension point registers implementations of an interface IWorkingSetProjectConfigurationFactory against specific project natures. This factory creates, for the provider's projects:

• an implementation of the IWorkingSetProjectConfiguration interface. It can define, in addition to the standard "active configuration" setting, any other build metadata required by the project. Usually, this is information that is maintained separately from the ICConfigurationDescriptions, for example because it cross-cuts the CDT configuration concept
• an implementation of the IWorkingSetProjectConfigurationController interface. This interface is used by the dialog to determine editing rules for the Project configurations pane, including:
  • providing contents and labels for the tree elements under the project node. By default, these are the ICConfigurationDescriptions. Implementors can provide more structure
  • checking and unchecking items in the tree: are check marks mutually exclusive? In what scope?
  • notifying of changes in the "active" state of the project configuration specification
• a custom ProjectState implementation for the workspace snapshot

The basic fitness of this extensibility scheme is demonstrated by two out-of-the-box implementations:

• the org.eclipse.cdt.ui plug-in provides rudimentary support for projects of C and C++ nature. The configuration of a project consists solely of selecting which build configuration to activate, and building a particular project configuration in the context of a working set configuration activates it and then builds the project
• the org.eclipse.cdt.managedbuilder.ui plug-in provides support for the MBS builder nature. It extends the default project configuration implementation with the ability to build a particular configuration on-the-fly, without first activating it

The intention, this late in the CDT 6.0 release cycle (i.e., M7), is to leave all of this new API, including the extension point, as internal.

References

For traceability, this proposal is cross-referenced to bugzilla:

• Bug 272416