Eclipse Install/Update Packaging Conventions
Revision Date: 11-JUN-2009
Copyright 2009 IBM Corporation and others
Table of Contents
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.