Eclipse Install/Update Packaging Conventions

Revision Date: 11-JUN-2009
Copyright 2009 IBM Corporation and others

Introduction
       Concepts
       Provisioning Framework
Packaging Conventions
       Feature Archive
       Plug-In Archive
       Packaging NL
           Translated Feature Information
           Translated Plug-In Information
       Security Considerations
Software Repositories
       Default Repository Layout
       Controlling Access
Eclipse Install
       Default Install Layout
       Unmanaged Plug-Ins

Introduction

This document outlines the support for managing the delivery of function within the Eclipse platform. For complete details, see the section Packaging and delivering Eclipse-based products in the Eclipse help system. Also refer to the Eclipse Foundation Update Manager Agreement for legal information governing the use of the Eclipse update manager function.

Concepts

Plug-in

Eclipse developers build plug-ins, also known as bundles in OSGi terminology. Plug-ins are the base units of execution recognized by the Equinox runtime environment. In general, plug-ins are not exposed to users that select function during installation or update. The reason is that plug-in boundaries are established by developers for development reasons (like function reuse) and present the wrong level of granularity in terms of what the user sees as the unit of function.

While plug-ins are being developed (i.e. are frequently being changed), their internal file structure will reflect what is convenient to the developer. This will generally depend on the particular development tool being used. Most commonly, at development time plug-ins are a simple directory tree in the file system, including source, binaries, and other related development and deployment related files. During development the developer does not pay particular attention to plug-in versioning information, because the plug-in is continually changing.

However, when the plug-in is ready to be packaged, it needs to be converted to a form suitable for packaging and installation. Typically it means creation of the runtime .jar(s) and removing any development-time files (source, exposed .class files, etc). It also means updating the plug-in/bundle manifest (MANIFEST.MF) with the formal plug-in version and reflecting the version in the plug-in directory name (see "Concurrent Plug-In Version Support" for details).

Plug-in Fragment

Plug-in Fragments (or simply Fragments) allow independent packaging of certain aspects of the base plug-in. This includes (but may not be limited to) translated resources for the plug-in, OS-specific or windowing-system-specific code. At runtime, fragments are logically merged into the base plug-in. From a packaging point of view, the install and update support does not really differentiate between plug-ins and their related fragments.

Feature

A feature is an installation packaging mechanism used to define a group of versioned plug-ins and/or plug-in fragments plus non-plug-in files that is used to deliver some user function. A feature can also include or require other features. Features are exposed to users as part of the packaging and installation process, because they represent a unit of function selection. Features also represent a unit of installation. Features carry a version identifier.

Features are packaged as a feature archive, referencing the required plug-ins, plug-in fragments and optional non-plug-in files. The feature archives are placed on an update server for download and installation by the Eclipse update manager, or they can be used as the input into a formal packaging process using one of the "traditional" installer technologies. The format of the feature archive is described later.

Product

Products are a branded and packaged collection of features and plug-ins. Products define non-reusable aspects of an Eclipse-based application: splash screen, About dialog content, icons, default preference settings, etc.

Software Repository

Software repositories store collections of installable content (plug-ins, features, products, and other installable entities), in a format suitable for consumption by the Eclipse platform's provisioning system. Repositories are also sometimes referred to as update sites or update servers.

Provisioning Framework

The Eclipse platform uses a provisioning framework called p2 developed by the Eclipse Equinox project. This framework supports an open ended set of repository formats, and provides many more generic and powerful core concepts than outlined here. The scope of this document is just to define the "default" or canonical packaging format used by Eclipse projects.

Packaging Conventions

Feature packages consist of several related files:

exactly one jar containing the feature manifest and related files. This one is referred to as the "feature archive"
zero or more jars containing the feature plug-ins. These are referred to as the "plug-in archives"

Feature Archive

The feature packaging information is placed into a separate Java .jar. Standard Java jar facilities are used for constructing feature archives. Feature archives reference separately packaged plug-in archives (see next section) and non-plug-in files.

Features are identified using a structured identifier based on the provider internet domain name. For example, organization eclipse.org may produce feature org.eclipse.javatooling. The character set used for feature identifiers is as specified for plug-in identifiers (see reference information describing the plug-in manifest).

The recommended convention for naming the feature archives is
<id>_<version>.jar

Where <id> is the feature identifier and <version> is the full version identifier contained in the respective feature.xml. Note that this is a recommended convention that minimizes chance of collisions, but is not required by the Eclipse architecture. For example, the following are valid feature archive names

org.eclipse.javatooling_1.0.3.jar
org.eclipse.pde_2.0.jar
my_feature.jar

Internally, each feature archive is packaged relative to its feature directory (but not including the directory path element). The archive has the following structure

feature.xml
feature<_locale>.properties (see "Translated Feature Information")
other feature files and subdirectories (TBD)
META-INF/
Java jar manifest and security files

The feature manifest file (feature.xml) format is documented here. In general, feature authors don't need to know the details of the feature manifest format. The Plug-in Development Environment (PDE) in the Eclipse SDK provides graphical authoring tools for defining and editing feature manifests.

Translatable text contained in the feature.xml can be separated into feature<_locale>.properties files using Java property bundle conventions. Note that the translated strings are used at installation time (ie. do not employ the plug-in fragment runtime mechanism).

Plug-In Archive

Plug-ins and plug-in fragments are individually packaged as separate Java .jars. Standard Java jar facilities are used for constructing plug-in archives. There is no distinction made between a plug-in archive containing a plug-in and one containing a plug-in fragment.

The recommended convention for naming the plug-in archives is
<id>_<version>.jar

Where <id> is the plug-in or fragment identifier and <version> is the full version identifier contained in the respective plug-in or fragment's MANIFEST.MF. Note that this is a recommended convention that minimizes chance of collisions, but is not required by the Eclipse architecture. For example, the following are valid plug-in archive names

org.eclipse.platform_1.0.3.jar
org.eclipse.ui.nl_2.0.jar
my_plugin.jar

Internally, each plug-in archive packages all the relevant plug-in or fragment files relative to its plug-in or fragment directory (but not including the directory path element). The archive has the following structure

META-INF/
MANIFEST.MF - bundle manifest file other plug-in or feature files and subdirectories

Packaging NL

In Eclipse, translated plug-in information is packaged either together with the base plug-in, or as a plug-in fragment. At runtime, Eclipse locates the translations for the required locale. The use of fragments allows translations to be added to the runtime without the need to repackage the base plug-ins.

This mechanism cannot be used for translating the actual packaging information that is part of the installation xml files. Consequently the standard Java translation conventions are used for the packaging information, and all necessary translations must be available at the time the feature is packaged.

Translated Feature Information

Note: This section describes the conventions used for translating the information contained within the feature manifest. It allows for the update client to select the correctly localized strings from the update server. This section specifically does not describe localization of individual plug-ins.

Several of the attributes within the feature manifest are strings intended for display through user interfaces. To facilitate translation, these attribute values use the convention defined for translatable attributes of plugin.xml. Strings beginning with % up to the first space are treated as resource identifier keys (without the %) and looked up in a properties file. For example:

label="%cfg Tool Feature for Linux"

results in a resource lookup in the correct property file with key "cfg". If no property files are supplied, or the key is not found the default string value (following the %key) is used.

The property files are named as feature_<locale>.properties using the Java resource bundle naming conventions. Within the feature archive .jar they are placed in the same directory as their corresponding feature.xml file.

Translated Plug-In Information

No change from 1.0. Translated plug-in information should be packaged as plug-in fragments.

Security Considerations

The general approach is to use base Java jar signing for the feature and plug-in archive .jars.

Features are verified as follows:

download and verify the feature archive (use base Java jar verification)
for each plug-in archive

verify the archive jar content (use base Java jar verification)
verify plug-in id and version from <plugin> entry in feature manifest matches downloaded plugin.xml

for each non-plugin file

call install handler to verify file

In general, when processing signed jars, the user will be prompted for each unrecognised certificate. The response choices will include aborting the installation (originator is not trusted), continuing the installation (originator is trusted for this installation).

Software Repositories

The default Eclipse software repository is any URL-accessible location (such as a remote server or local file system location). The default implementation assumes a fixed-layout server. The content of the repository (in terms of available features and plug-ins) is described in index files (content.jar and artifacts.jar). These files are generated either using command line tools provided by Equinox p2, or by using repository editing tools in the Eclipse Plug-in Development Environment (PDE). The repository can also defined categories for its content, which provide navigational aide to end users installing software from that repository.

Default Repository Layout

<site root>/
    content.jar
    artifacts.jar
    features/
        feature archives   (eg. org.eclipse.javatools_1.0.1.jar)
    plugins/
        plug-in archives
    binary/
        binary artifact archives    (eg. org.eclipse.platform_root_3.5.0)

Controlling Access

The default Eclipse site implementation provides support for https access with basic user authentication (user id and password).

Eclipse Install

Default Install Layout

A typical Eclipse application install has the following layout. Note a branded application will typically replace files and directories containing the word "eclipse" with their own branded application name.

eclipse/
    configuration/
    features/
       <featureId>_<version>/
         feature.xml
          other feature files
    plugins/
        <pluginORfragmentId>_<version>.jar
    p2/
    dropins/
    eclipse.exe
    eclipse.ini

Unmanaged Plug-Ins

Eclipse supports a concept of "unmanaged" plug-ins. These are plug-ins that were directly installed into the Eclipse dropins folder without being part of a feature (eg. developer unzipping plug-in archive directly into the Eclipse file tree).

The Eclipse provisioning system recognizes these plugins during startup and loads the plug-in information into the runtime registry following the standard plug-in binding rules. The update support also recognizes the presence of this new plug-in, but since this plug-in is not part of any feature it cannot be updated using the update support (hence "unmanaged").

Unmanaged plug-ins are not displayed as part of the installation and update UI.