| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <title>Eclipse Install/Update Packaging Conventions</title> |
| </head> |
| <body> |
| |
| <h1>Eclipse Install/Update Packaging Conventions</h1> |
| <font size="-1">Revision Date: 11-JUN-2009</font><br> |
| <font size="-1">Copyright 2009 IBM Corporation and others</font> |
| |
| <h3> <font size="+2">Table of Contents</font></h3> |
| <a href="#Introduction">Introduction</a> <br> |
| <a href="#Concepts">Concepts</a><br> |
| <a href="#Framework">Provisioning Framework</a> |
| <br> |
| <a href="#Packaging_Conventions">Packaging Conventions</a> |
| <br> |
| <a |
| href="#Feature_Archive">Feature Archive</a> <br> |
| <a |
| href="#Plug-In_Archive">Plug-In Archive</a> <br> |
| <a |
| href="#Packaging_NL">Packaging NL</a> <br> |
| |
| <a href="#Translated_Feature_Information"> Translated Feature Information</a> |
| <br> |
| |
| <a href="#Translated_Plug-In_Information"> Translated Plug-In Information</a> |
| <br> |
| <a |
| href="#Security_Considerations">Security Considerations</a> <br> |
| <a href="#Repository">Software Repositories</a> <br> |
| <a |
| href="#Default_Repo_Layout">Default Repository Layout</a> <br> |
| <a |
| href="#Controlling_Access">Controlling Access</a> <br> |
| <a href="#Eclipse_Install">Eclipse Install</a> <br> |
| <a |
| href="#Default_Install_Layout">Default Install Layout</a> <br> |
| <a |
| href="#Unmanaged_Plugins">Unmanaged Plug-Ins</a> <br> |
| |
| <h2> <a name="Introduction"></a> Introduction</h2> |
| This document outlines the support for managing the delivery of function |
| within the Eclipse platform. For complete details, see the section |
| <a href="http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/guide/product.htm"> |
| Packaging and delivering Eclipse-based products</a> in the Eclipse help system. Also refer to the <a |
| href="http://www.eclipse.org/legal/updatemanager.php"> Eclipse Foundation Update |
| Manager Agreement</a> for legal information governing the |
| use of the Eclipse update manager function. |
| </ul> |
| |
| <h3> <a name="Concepts"></a> Concepts</h3> |
| <dl> |
| <dt><b>Plug-in</b></dt> |
| <dd> |
| Eclipse developers build <em>plug-ins</em>, also known as <em>bundles</em> |
| 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. |
| |
| <p>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. </p> |
| |
| <p>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). |
| </dd> |
| <dt><b>Plug-in Fragment</b></dt> |
| <dd> |
| 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. |
| </dd> |
| <dt><b>Feature</b></dt> |
| <dd> |
| 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.</p> |
| |
| <p>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. </p> |
| </dd> |
| <dt><b>Product</b></dt> |
| <dd> |
| 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.</p> |
| </dd> |
| <dt><b>Software Repository</b></dt> |
| <dd> |
| 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 <em>update sites</em> or <em>update servers</em>.</p> |
| </dd> |
| </dl> |
| <h3> <a name="Framework"></a> Provisioning Framework</h3> |
| 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. |
| |
| <h2> <a name="Packaging_Conventions"></a> Packaging Conventions</h2> |
| Feature packages consist of several related files: |
| |
| <ul> |
| <li> exactly one jar containing the feature manifest and related files. |
| This one is referred to as the "<b>feature archive</b>"</li> |
| <li> zero or more jars containing the feature plug-ins. These |
| are referred to as the "<b>plug-in archives</b>"</li> |
| </ul> |
| |
| <h3> <a name="Feature_Archive"></a> Feature Archive</h3> |
| 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. |
| <p>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). </p> |
| |
| <p>The recommended convention for naming the feature archives is <br> |
| <tt><id>_<version>.jar</tt> </p> |
| |
| <p>Where <tt><id></tt> is the feature identifier and <tt><version></tt> |
| 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 </p> |
| |
| <p><tt>org.eclipse.javatooling_1.0.3.jar</tt> <br> |
| <tt>org.eclipse.pde_2.0.jar</tt> <br> |
| <tt>my_feature.jar</tt> </p> |
| |
| <p>Internally, each feature archive is packaged relative to its feature directory |
| (but not including the directory path element). The archive has the |
| following structure </p> |
| |
| <p><tt>feature.xml</tt> <br> |
| <tt>feature<_locale>.properties (see "Translated Feature |
| Information")</tt> <br> |
| <tt>other feature files and subdirectories (TBD)</tt> <br> |
| <tt>META-INF/</tt> <br> |
| <tt> Java jar manifest and security files</tt> |
| </p> |
| |
| <p>The feature manifest file (feature.xml) format is documented |
| <a href="http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html">here</a>. |
| 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.</p> |
| |
| <p>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). </p> |
| |
| <h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3> |
| 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. |
| |
| <p>The recommended convention for naming the plug-in archives is <br> |
| <tt><id>_<version>.jar</tt> </p> |
| |
| <p>Where <tt><id></tt> is the plug-in or fragment identifier and <tt> |
| <version></tt> 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 </p> |
| |
| <p><tt>org.eclipse.platform_1.0.3.jar</tt> <br> |
| <tt>org.eclipse.ui.nl_2.0.jar</tt> <br> |
| <tt>my_plugin.jar</tt> </p> |
| |
| <p>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 </p> |
| |
| <p><tt>META-INF/</tt> <br> |
| <tt> MANIFEST.MF - bundle manifest file</tt> |
| <tt>other plug-in or feature files and subdirectories</tt> <br> |
| </p> |
| |
| <h3> <a name="Packaging_NL"></a> Packaging NL</h3> |
| 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. |
| <p>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. </p> |
| |
| <h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4> |
| <b>Note:</b> 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. |
| <p>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: </p> |
| |
| <p><tt>label="%cfg Tool Feature for Linux"</tt> </p> |
| |
| <p>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. </p> |
| |
| <p>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. </p> |
| |
| <h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4> |
| No change from 1.0. Translated plug-in information should be |
| packaged as plug-in fragments. |
| |
| <h3> <a name="Security_Considerations"></a> Security Considerations</h3> |
| The general approach is to use base Java jar signing for the |
| feature and plug-in archive .jars. |
| <p>Features are verified as follows: </p> |
| <ul> |
| <li> download and verify the feature archive (use base Java jar verification)</li> |
| <li> for each plug-in archive</li> |
| <ul> |
| <li> verify the archive jar content (use base Java jar verification)</li> |
| <li> verify plug-in id and version from <tt><plugin></tt> |
| entry in feature manifest matches downloaded plugin.xml</li> |
| </ul> |
| <li> for each non-plugin file</li> |
| <ul> |
| <li> call install handler to verify file</li> |
| </ul> |
| </ul> |
| 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). |
| |
| <h2> <a name="Repository"></a>Software Repositories</h2> |
| 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 (<i>content.jar</i> and <i>artifacts.jar</i>). 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. |
| |
| <h3> <a name="Default_Repo_Layout"></a> Default Repository Layout</h3> |
| <tt><site root>/</tt> <br> |
| <tt> content.jar</tt> <br> |
| <tt> artifacts.jar</tt> <br> |
| <tt> features/</tt> <br> |
| <tt> feature archives |
| (eg. org.eclipse.javatools_1.0.1.jar)</tt> <br> |
| <tt> plugins/</tt> <br> |
| <tt> plug-in archives </tt><br> |
| <tt> binary/</tt> <br> |
| <tt> binary artifact archives |
| (eg. org.eclipse.platform_root_3.5.0)</tt> |
| <h3> <a name="Controlling_Access"></a> Controlling Access</h3> |
| The default Eclipse site implementation provides support for https access with basic user authentication (user id and password). |
| |
| <h2> <a name="Eclipse_Install"></a> Eclipse Install</h2> |
| |
| <h3> <a name="Default_Install_Layout"></a> Default Install Layout</h3> |
| 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. |
| <p> |
| <tt>eclipse/</tt> <br> |
| <tt> configuration/</tt><br> |
| <tt> features/</tt><br> |
| <tt> <featureId>_<version>/</tt> <br> |
| <tt> feature.xml</tt> <br> |
| <tt> other feature files</tt> <br> |
| <tt> plugins/</tt> <br> |
| <tt> <pluginORfragmentId>_<version>.jar</tt><br> |
| <tt> p2/</tt> <br> |
| <tt> dropins/</tt> <br> |
| <tt> eclipse.exe</tt> <br> |
| <tt> eclipse.ini</tt> <br> |
| </p> |
| <h3> <a name="Unmanaged_Plugins"></a>Unmanaged Plug-Ins</h3> |
| Eclipse supports a concept of "unmanaged" plug-ins. These are |
| plug-ins that were directly installed into the Eclipse <i>dropins</i> folder without |
| being part of a feature (eg. developer unzipping plug-in archive directly |
| into the Eclipse file tree). |
| <p>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").</p> |
| |
| <p>Unmanaged plug-ins are not displayed as part of the installation and update UI. </p> |
| |
| </body> |
| </html> |
