equinox
configurations and features

 
Introduction

This document is a draft of ideas related to the organization of installation and configuration information in an Equinox-based Eclipse environment. The ideas are somewhat preliminary and are presented here to elicit discussion and comment.

Last update: 2300 November 13, 2003

Problem Statement

When the classic Eclipse runtime starts up it is presented with a platform configuration which lists a number of features and plugins to consider for execution. This configuration is defined in a file (platform.cfg) in a well-known location(s). The format of the file is defined by the Update/Install team who also contribute the code (to the Boot plugin) which interprets the file.

This approach is limiting in that other install/update mechanisms are forced to manage plugins in terms of Features. Features are actually a delivery/structuring mechansim that is particular to the Eclipse Update/Install mechanism. In addition to their Update/Install uses, they are used in the following ways:

  • primary features identify an application to run, splash screen, default perspective, ...
  • the UI discovers and presents the About information based on features

These uses fulfill valid requirements not dependent on the mechanism for installing and updating plugins. The problem comes in the fact that they are tied to the platform.cfg file and features which are Install/Update concepts.

In the Equinox runtime the loading and running of plugins has been decoupled from the definition of the configuration. In particular, the runtime itself has a list of plugins it has been made aware of and it is the role of an additional element, the configurator, to inform the runtime of new interesting plugins. Current Equinox drops come with an Update Configurator which essentially contains the Update code from Boot. It reads the platform.cfg file and ensures that the runtime is aware of the the plugins listed. However, many different definitions of configurator are possible.

For example, people in the Eclipse community have expressed interest in behaviours covering the flexibility spectrum:

  • managing a fixed set of plugins: This is done by a configurator which contains the hard-coded list.
  • allowing external configuration management: Enterprise configuration management systems such as Tivoli would define configurators which interact with a server to discover what plugins should be available.
Proposals

To address these issues, we propose a number of additions and some changes to the current story.

Generalize the notion of configuration location

Currently users can specify -configuration <platform.cfg> on the command line. This indicates that the Eclipse runtime should use the given platform configuration to discover the plugins and application to run. If this argument is not supplied, a default location (e.g., <eclipse install>/.config/platform.cfg) is used.
The default configuration location and the content of the platform.cfg file are actually defined by the Install/Update code in Boot.

We propose to generalize this an have the runtime define a configuration location (a directory). Various users (e.g., Install/Update) are free to locate their files in this directory as they require. The runtime will use the same algorithm as the current Install/Update code to compute the default location. The -configuration command line argument will take a directory (URL?). For backward compatibility, if the user specifies -configuration <platform.cfg location>, the runtime will derive the configuration location by removing the "platform.cfg". That is, the location will be the parent of the configuration file.

This approach allows other plugins (e.g., user settings, runtime, UI activity/category definitions, ...) to locate information on a per configuration basis and still retain the level of function we have today. Future configurators would also use this area as needed to position their configuration information.

Eliminate the UI's use of features

The UI currently uses features in four different ways:

  1. Product level information
    • product name: the name to use in window title bars (about.ini)
    • application name: the application to run (about.ini)
    • window image: the icon to show in the top left of Eclipse windows. (about.ini)
  2. About information
    • list of all features (configuration)
    • list of plugins/fragments in the features (configuration)
    • about, license, description, icon/image for each feature (about.ini and feature plugin plugin.xml)
  3. System configuration information
    • dumping the system configuration (in the About dialog) dumps a summary of all features, plugins, fragments, ... known to the system.
  4. Welcome pages/Tips and Tricks
    • features contribute Welcome pages and Tips and Tricks links (about.ini)

We propose a refactoring of this information into explicit interfaces which expose the information needed.

interface IWad {  <----- obviously a different name is needed
  public String getIdentifier();
  public String getName();
  public String getVersion();
  public String getImage();
  public String getDescription();
  public Bundle[] getBundles();  <----- need a different return type
}
interface IProduct {
  public String getApplication();
  public String getName();
  public String getImage();
}
interface IWadProvider {
  public String getName();
  public IWad[] getWads();
}
interface IPlatform {
  ...

  /** 
   * Returns all wad providers which have registerd with the platform.
   */
  public IWadProvider[] getWadProviders();


  /** 
   * Returns the product identified by the current configuration as the main
   * product.  null is returned if no product has been identified.
   */
  public IProduct getProduct();


  /**
   * Registers the given object as a wad provider
   */

  pubilc void registerWadProvider(WadProvider provider);
}

Given the above API, products register with the runtime using an extension point (org.eclipse.core.runtime.product). The extension supplies the values detailed in the IProduct interface. The current product is discovered through IPlatform.getProduct().

Wad providers (e.g., the Install/Update configurator) identify themselves to the runtime using IPlatform.registerWadProvider(). Providers are started at a special point in the startup sequence and should register when they are started. The set of all started providers is discovered using IPlatorm.getWadProviders().

Given the set of all providers, an interested party can ask each for the wads it provides. Given these wads, the set of installed plugins/fragments can be discovered. Using these accessing patterns, the UI, for example, can populate the About dialog or the configuration summary can be generated.

config.ini

Currently the install.ini file cues Boot/Runtime as to the primary freature and the default application to run. This information is still needed but should be relative to a configuration not the Eclipse install. Also, the relevant information is what product is being run (rather than primary feature).

This proposal calls for a config.ini file, located in a configuration area, to contain this information. The format and content of this file would be standardized and specified as API allowing Install/Update mechanisms to properly setup configurations.

Pre-defined configurations

Eclipse currently relies on a reconciler to reverse-engineer or construct a platform configuration if none is available (this is what is happening when you see the "Completing the install" splash screen). This is useful function but should not be the default behaviour for first runs.

We propose that Eclipse ship with a pre-defined configuration and that running without a configuration, while tolerated, is treated as a significant error case. Eclipse-based products should also be encouraged to ship with pre-defined configurations.

Identifying base pieces to install/start

As in any system, there are elements on which everything else is based. In the case of Equinox these include:

  • the OSGi framework (org.eclipse.osgi)
  • the runtime bundle (org.eclipse.core.runtime.osgi)
  • the update configurator bundle (org.eclipse.update.configurator)
  • the application runner (org.eclipse.core.runtime.applicationrunner)

Dynaically updating these (except the framework itself) is allowed. Of course, doing so generally results in a system restart because all other plugins (in)directly depend on these.

The mechanism for specifying which versions of these bundles to run is somewhat weak. The current Equinox framework starts and reads a system property (osgi.bundles) which identifies a list of bundles (including version) to install and start. These are the bootstrap bundles. A more general mechanism might have this list defined in the config.ini file (see above).