Eclipse-based Products and Extensions

Last modified 16:00 Friday December 06, 2002

Change History:

2.0.1
- added: feature.default.plugin.id

Eclipse technology is the foundation of, and provides building blocks for, products aimed at the software development tools market. Commercial software vendors are expected to build, brand, and package products using the Eclipse platform as the nucleus, to sell these products into the development tools marketplace, and to support them once in the field.

The Eclipse platform itself is not a "product" in any of these senses. Eclipse is an open source project that provides raw ingredients without box, label, or price tag. The closest that the Eclipse project gets to a packaged form is the Eclipse SDK, which can be downloaded from eclipse.org, installed, and used as a full-service Java IDE which also happens to include special support for developing Eclipse plug-ins (PDE).

This note describes how the Eclipse platform is designed to be turned into products. The license governing the Eclipse platform gives a software vendor almost complete freedom over how to built a product. So anyone building a product is free to ignore this advice. However, as is often the case with standards, adhering to the same rules as everyone else has its rewards: it fosters greater interoperability between products, and makes it easier for the end user because different products behave in similar ways.

Eclipse plug-ins are intended to packaged and delivered to the customer into one of two forms: either as self-contained Eclipse-based products, or as add-on extensions to Eclipse-based products. We'll first explain what we mean by Eclipse-based product since it is the more basic notion.

Eclipse-based products

An Eclipse-based product is a stand-alone program build with Eclipse. Products are self-contained in that all code and plug-ins needed to get up and running are included; this includes a Java runtime environment (JRE), and the code for the Eclipse platform itself. After installing a product on a computer with a conventional native installer, the user launches the product (via its product executable) and is presented with an Eclipse workbench configured appropriately for the purposes that product was designed to support (be it developing enterprise web servers, developing C++ programs, or developing whatever). Products are intended to be updated, either with a conventional native installer, or with the build-in Eclipse update manager, which is always available to the user from the Eclipse workbench ("Update Manager" on the "Help" menu).

If we looked more closely at how the Eclipse parts of the product are organized, we would see that all plug-ins that go into a product are grouped into features. "Feature" is an Eclipse update manager notion: a feature is the smallest unit of separately downloadable and installable functionality. Features also play a secondary role in how the Eclipse platform runs.

To make things a bit more concrete, the top level structure of an installed Eclipse-based product looks like this (italics indicate product-specific file names):

<install>/ acmeproduct.exe product executable eclipse/ container for installed Eclipse files .eclipseproduct marker for Eclipse product install eclipse.exe Eclipse executable launcher startup.jar Eclipse Java launcher install.ini install info .config/ install info (computed at install time with -initialize option) platform.cfg default platform configuration jre/ Java runtime environment (JRE) features/ installed feature versions com.example.acme.acmefeature_1.0.0/ primary feature for product feature.xml feature manifest file org.eclipse.platform_2.0.0/ feature for Eclipse platform org.eclipse.platform.win32_2.0.0/ feature for Eclipse platform plugins/ installed plug-ins and fragment versions com.example.acme.acmefeature_1.0.0/ product-specific plug-in plugin.xml plug-in manifest file about.ini about info for product acme.gif window icon for product plugin_customization.ini about info for product splash.png product splash screen com.example.acme.myplugin_1.0.0/ product-specific plug-in plugin.xml plug-in manifest file myplugin.jar code for product-specific plug-in org.eclipse.platform_2.0.0/ Eclipse platform plug-in org.eclipse.platform.win32_2.0.0/ Eclipse platform plug-in org.eclipse.core.boot_2.0.0/ Eclipse platform plug-in org.eclipse.core.runtime_2.0.0/ Eclipse platform plug-in org.eclipse.core.resources_2.0.0/ Eclipse platform plug-in org.eclipse.ui_2.0.0/ Eclipse platform plug-in (more org.eclipse.* plug-in directories) links/ links to extensions (see next section) com.example.wiley.anvilfeature.link link to separately-installed extension

Each product should partition its own plug-ins into one or more features. The Eclipse platform itself is partitioned into three major features, Platform, JDT, and PDE. There are also a bunch of lesser features, including documentation, examples, and OS-dependent portions of Platform. The binary distribution of the Eclipse 2.0 release makes each of these features available as a separate zip. This allow a product packager to download and unzip just the pieces needed for a particular product offering.

To the user, an installed product usually shows up on the desktop as a shortcut. Opening the shortcut starts the product. For a simple product that does nothing other than run an Eclipse workbench, the shortcut target is the Eclipse executable launcher (<install>/eclipse/eclipse.exe). For products that have other things to do as well, the shortcut targets the product's own executable (<install>/acmeproduct.exe), which invokes eclipse.exe at some point.

Whenever the Eclipse platform is run, exactly one feature gets to control the overall personality of the Eclipse platform. This is the called the product's primary feature, and it controls highly visible things including the splash screen, window branding images, the about box, the welcome page, the default perspective, and customization of the default settings of plug-in preferences. The typical product has just one eligible primary feature, and it is determined by the "feature.default.id" property of the product's install.ini file. If there are multiple eligible primary features, the -feature command line option to eclipse.exe overrides the choice made in the install.ini. If the property "feature.default.plugin.id" exists, it declares the identifier of the primary plugin. If the property does not exist, the primary plugin must have the exact same identifier as the primary feature.

Summary of characteristics of products:

a product is installed in a single directory tree
a product includes copies of the org.eclipse.* plug-ins that it needs
OS-dependent code for multiple operating environment can sit side-by-side in a product install
a products is installed and uninstalled by a native installer only
more than one product may be installed on the same computer
a product is installed, updated, and uninstalled independently of other Eclipse-based products
a product is updated by a native installer or by the Eclipse update manager
a product can have one or more primary features, and any number of other features
a primary feature determines the Eclipse workbench overall appearance and personality
the default primary feature is specified in the product-specific install.ini file
the update manager can update the features and plug-ins installed with the product
the update manager can install and configure additional features and plug-ins into the product

Extensions to Eclipse-based products

An extension is bundle of Eclipse-based features designed to be installed separately and used with any Eclipse-based product. In contrast to a product, an extension includes neither eligible primary features, nor a copy of the Eclipse platform, nor its own JRE.

The same installed base of files for an extension can be used from several Eclipse-based products. This means an extension only needs to be updated in one place, while having the updated features available to all products linked to that extension.

To keep things concrete, the top level structure of an installed Eclipse-based extension looks like this:

<extension install>/ eclipse/ container for installed Eclipse files .eclipseextension marker for Eclipse extension install features/ installed feature versions com.example.wiley.anvilfeature_1.0.0/ feature for extension feature.xml feature manifest file plugins/ installed plug-ins and fragment versions com.example.wiley.anvilfeature_1.0.0/ extension-specific plug-in plugin.xml plug-in manifest file about.ini about info for feature com.example.wiley.otherplugin_1.0.0/ extension-specific plug-in plugin.xml plug-in manifest file otherplugin.jar code for extension-specific plug-in

Characteristics of extensions:

an extension is installed in a single directory tree (separate from products or other extensions)
an extension does not include a copy of the Eclipse platform plug-ins, a JRE, or an executable
OS-dependent code for multiple operating environment can sit side-by-side in an extension install
an extension is installed and uninstalled by a native installer only
more than one extension may be installed on the same computer
an extension is installed, updated, and uninstalled independently of other Eclipse-based products
an extension is updated by a native installer or by the Eclipse update manager
a product can have one or more features
an extension does not define primary features
to be useful, an extension must be associated with an Eclipse-based product
an extension can be associated with one or more products at the time the extension is installed
an extension can be associated with a product via the update manager
the update manager can update the features and plug-ins installed with the extension
the update manager can install and configure additional features and plug-ins into the extension