runtime users guide


This document details how to run and control the Eclipse 3.0 runtime.
Last Modified: 1700 March 23, 2004

Controlling the runtime

This section has been moved to the Reference section of the ISV doc.


This section has been moved to the Reference section of the ISV doc.


Configurations define a (sub)set of plugins found in an install. Users can then run a configuration on a data set (e.g., workspace). This is easy to see, for example, in a corporate setting where all of the Eclipse-based products might be installed and managed in one large install base. This install would contain potentially thousands of plugins. The Eclipse runtime scales to handle this but the resultant environment is likely not interesting for users. Such shared installations reduce the effort required to manage products as well as providing a centralized point for defining consistent sets of function.

For example, users from, say, accounting should run the "accounting configuration" which identifies only those plugins useful to accountants. Similarly, the developers have their configurations as do the sales team. Further, products typically ship with predefined configuration(s) which define/suit their envisioned usecases.

When the Eclipse runtime is run, agents (plugins, remote entities or humans) can control the set of plugins that the runtime manages. Plugins managed by the runtime are candidates for execution. A candidate must be resolved before any of its code can be run or its presence (e.g., extensions) is made known. The runtime keeps track of the set of managed plugins and associated information in a configuration location. If there is no such location or the location is readonly, the runtime will still run but may not be able to offer all function. For example, it will not be able to remember between sessions which plugins it manages.

In a shared install the plugins themselves are shared as are the predefined configurations but each user may have their own area in which configuration values can be overridden and configuration-specific data can be stored. Eclipse uses the notion of cascading configurations to layer configurations.




To allow for shared installations and



the notion of a configuration area (see Platform.getConfigurationLocation()). For the runtime, the configuration area contains a file called config.ini. This file, if present, contains a set of properties which control the construction and operation of the framework and runtime. For example, it is in this file that an initial set of bundles to load and start is defined.

The runtime does not define how this file is managed, nor does it contain any mechanism for updating the file (i.e., the runtime never writes the file). Rather, this responsibility is left to the entity managing the configuration. In some scenarios the configuration is defined and locked during product build, in other cases a system administrator crafts the configuration and pushes it to machines (or it is shared), in still other situations the end user manages the config.ini (in)directly using a configuration management tool such as the Eclipse Update Manager.

Any of these entities are free to put additional files and information in the configuration area. They should be careful however to consider cases where the configuration area is read-only. While it is not a requirement that plug-ins using the configuration area operate completely or partially when the area is read-only, your plug-in may not be usable in certain situations if it does not. For example, a typical tooling scenario includes a writable configuration area. If your plug-in is targetted at tooling environments, you are probably safe making that assumption. Note however that if somoene tries to use your plug-in in a constrained RCP scenario where there is no writable storage, they will likely be disappointed.



Running out of jars

running out of jars

The Console

using the console

Setting up your workspace

Users with existing workspaces should not encounter problems opening them with the Equinox runtme. However, since the runtime plug-in structure has changed, there some updating of classpaths may be required. In particular, developers setting up a runtime workspace (i.e., a workspace containing plug-ins) will need to either:

Both of these can be accomplished using the PDE Tools->Update classpath project context menu.

The following projects are needed (in addition to the normal set) :

If you have an existing runtime workspace containing one of the following pre-existing plug-ins, it must be updated to accurately match their new contents

Note that these plug-ins are only required if your plug-in uses the old runtime API. If you have adopted the new API (see Updating your code) then these projects/plug-ins are not needed.

There should be no need to modify the launch configurations as the runtime is self-discovering.


Should you encounter any problems while using the Equinox runtime, you are encouraged to either log a bug report in the Equinox Bugzilla database or make a posting to the Core mailing list or the Platform newsgroup.