Eclipse-based Products and Extensions

Last modified 22:30 Sunday April 28, 2002

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.

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
    platform.cfg           install info (computed at install time)
    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. Strictly speaking, a product could have more than one primary feature; the selection of which primary feature gets control is done via the -feature command line option to  eclipse.exe. A typical product has just one eligible 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
• a dominant primary feature must be selected for each run
• 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 primary features, nor a copy of the Eclipse platform, n or 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 effects felt in 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