Feature Manifest

Eclipse platform feature manifest

Version 3.0 - Last revised June 22, 2004

The feature manifest format is defined by the following dtd:
<?xml encoding="ISO-8859-1"?>
<!ELEMENT feature (install-handler? | description? | copyright? | license? | url? | includes* | requires? | plugin* | data*)>
<!ATTLIST feature
    id            CDATA #REQUIRED
    version       CDATA #REQUIRED
    label         CDATA #IMPLIED
    provider-name CDATA #IMPLIED
    image         CDATA #IMPLIED
    os            CDATA #IMPLIED
    arch          CDATA #IMPLIED
    ws            CDATA #IMPLIED
    nl            CDATA #IMPLIED
    colocation-affinity
                  CDATA #IMPLIED
    primary       (true | false) "false"
    exclusive     (true | false) "false"
    plugin        CDATA #IMPLIED
    application   CDATA #IMPLIED
>
<!ELEMENT install-handler EMPTY>
<!ATTLIST install-handler
    library       CDATA #IMPLIED
    handler       CDATA #IMPLIED
>
<!ELEMENT description (#PCDATA)>
<!ATTLIST description
    url           CDATA #IMPLIED
>
<!ELEMENT copyright (#PCDATA)>
<!ATTLIST copyright
    url           CDATA #IMPLIED
>
<!ELEMENT license (#PCDATA)>
<!ATTLIST license
    url           CDATA #IMPLIED
>
<!ELEMENT url (update?, discovery*)>
<!ELEMENT update EMPTY>
<!ATTLIST update
    url           CDATA #REQUIRED
    label         CDATA #IMPLIED
>
<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
    type          (web | update) "update"
    url           CDATA #REQUIRED
    label         CDATA #IMPLIED
>
<!ELEMENT includes EMPTY>
<!ATTLIST includes
    id                CDATA #REQUIRED
    version           CDATA #REQUIRED
    name              CDATA #IMPLIED
    optional          (true | false) "false"
    search-location   (root | self | both) "root"
    os                CDATA #IMPLIED
    arch              CDATA #IMPLIED
    ws                CDATA #IMPLIED
    nl                CDATA #IMPLIED
>
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
    plugin        CDATA #IMPLIED
    feature       CDATA #IMPLIED
    version       CDATA #IMPLIED
    match         (perfect | equivalent | compatible | greaterOrEqual) "compatible"
    patch         (true | false) "false"
>
<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
    id            CDATA #REQUIRED
    version       CDATA #REQUIRED
    fragment      (true | false) "false"
    os            CDATA #IMPLIED
    arch          CDATA #IMPLIED
    ws            CDATA #IMPLIED
    nl            CDATA #IMPLIED
    download-size CDATA #IMPLIED
    install-size CDATA #IMPLIED
    unpack        (true | false) "true"
>
<!ELEMENT data EMPTY>
<!ATTLIST data
    id            CDATA #REQUIRED
    os            CDATA #IMPLIED
    arch          CDATA #IMPLIED
    ws            CDATA #IMPLIED
    nl            CDATA #IMPLIED
    download-size CDATA #IMPLIED
    install-size CDATA #IMPLIED
>
The element and attribute definitions are as follows:

<feature> - defines the feature

id - required feature identifier (eg. com.xyz.myfeature)
version - required component version (eg. 1.0.3)
label - optional displayable label (name). Intended to be translated.
provider-name - optional display label identifying the organization providing this component. Intended to be translated.
image - optional image to use when displaying information about the feature. Specified relative to the feature.xml.
os - optional operating system specification. A comma-separated list of os designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this feature should only be installed on one of the specified os systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
ws - optional windowing system specification. A comma-separated list of ws designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this feature should only be installed on one of the specified ws systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
nl - optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this feature should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the feature can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
colocation-affinity - optional reference to another feature identifier used to select the default installation location for this feature. When this feature is being installed as a new feature (no other versions of it are installed), an attempt is made to install this feature in the same installation location as the referenced feature.
primary - optional indication specifying whether this feature can be used as a primary feature. Default if false (not a primary feature).
application - optional identifier of the Eclipse application that is to be used during startup when the declaring feature is the primary feature. The application identifier must represent a valid application registered in the org.eclipse.core.runtime.applications extension point. Default is org.eclipse.ui.ide.workbench.
plugin - optional identifier that represents the id of the plug-in listed in the feature that is used to carry branding information for the feature (images, translations, splash screens in case of primary feature etc.). If not specified, the assumption will be made the attribution plug-in has the same id as the feature.
exclusive - optional flag that, if "true", indicates that the feature cannot be installed in a group with other features.

<install-handler>

library - optional .jar library containing the install handler classes. If specified, the referenced .jar must be contained in the feature archive. It is specified as a path within the feature archive, relative to the feature.xml entry. If not specified, the feature archive itself is used to load the install handler classes. This attribute is only interpreted if class attribute is also specified
handler - optional identifier of the install handler. The value is interpreted depending on the value of the library attribute. If library is specified, the value is interpreted as a fully qualified name of a class contained in the specified library. If library is not specified, the value is is interpreted as an extension identifier of an extension registered in the org.eclipse.update.installHandlers extension point. In either case, the resulting class must implement the IInstallHandler interface. The class is dynamically loaded and called at specific points during feature processing. When the handler is specified as a class, it has visibility to the API classes from the org.eclipse.update.core plug-in, and Eclipse plug-ins required by this plug-in; otherwise, when is specified as extension, it has access to all the classes as the plug-in defining the extension.

<description> - brief component description as simple text. Intended to be translated.

url - optional URL for the full description as HTML. The URL can be specified as absolute of relative. If relative, it is assumed to be relative to (and packaged in) the feature archive. Note, that for NL handling the URL value should be separated to allow alternate URLs to be specified for each national language.

<copyright> - feature copyright as simple text. Intended to be translated.

url - optional URL for the full description as HTML. The URL can be specified as absolute of relative. If relative, it is assumed to be relative to (and packaged in) the feature archive. Note, that for NL handling the URL value should be separated to allow alternate URLs to be specified for each national language.

<license> - feature "click-through" license as simple text. Intended to be translated. It is displayed in a standard dialog with [Accept] [Reject] actions during the download/ installation process. Note, that click-through license must be specified for any feature that will be selected for installation or update using the Eclipse update manager. When using nested features, only the nesting parent (i.e. the feature selected for installation or update) must have click-through license text defined. The license text is required even if the optional url attribute is specified.

url - optional URL for the full description as HTML. The URL can be specified as absolute of relative. If relative, it is assumed to be relative to (and packaged in) the feature archive. Note, that for NL handling the URL value should be separated to allow alternate URLs to be specified for each national language. Note, that the "content" of this URL is not what is presented as the click-through license during installation processing. The click-through license is the actual value of the <license> element (eg. <license>click through text</license>)

<url> - optional URL specifying site(s) contain feature updates, or new features

<update> - URL to go to for updates to this feature

url - actual URL
label - displayable label (name) for the referenced site

<discovery> - URL to go to for new features. In general, a provider can use this element to reference its own site(s), or site(s) of partners that offer complementary features. Eclipse uses this element simply as a way to distribute new site URLs to the clients. Sites that belong to root features (at the top of the hierarchy) typically appear in "Sites to Visit" in Update Manager.

url - actual URL
label - displayable label (name) for the referenced site
type (new in 2.1) - by default, discovery sites are assumed to be update sites ("update"). By setting the value of this attribute to "web", it is possible to indicate to Eclipse that the URL should be treated as a regular Web hyperlink that can be directly displayed in a suitable browser.

<includes> - optional reference to a nested feature that is considered to be part of this feature. Nested features must be located on the same update site as this feature

id - required nested feature identifier. If the feature is a patch (see the <requires> section below), this must be the id of another patch.
version - required nested feature version
optional - it is possible to include a feature as optional when this attribute is "true". Users are allowed to not install optional features, disable them if they are installed, and install them later. A missing optional feature is not treated as an error.
name - if an optional feature is missing, Eclipse cannot render its name properly. This attribute can be used as a 'place holder' to allow Eclipse to render the name of the optional feature when it is not installed.
search-location - an included feature can be updated by patches. By default, search location is "root" which means that URL specified in the "update" element within the "url" element of the parent will be considered. If an included feature has its own "update" element defined, it will be ignored by default. If the parent feature wants to allow the child to be updated from its own location, it can set this attribute to "both" or "self".
os - optional operating system specification. A comma-separated list of os designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this entry should only be installed on one of the specified os systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
ws - optional windowing system specification. A comma-separated list of ws designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this entry should only be installed on one of the specified ws systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
nl - optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this entry should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the entry can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).

<requires> - optional feature dependency information. Is expressed in terms of plug-in dependencies. If specified, is enforced by the installation and update support at the time of installation

<import> - dependency entry. Specification and processing is a subset of the <import> specification in plugin.xml

plugin - identifier of dependent plug-in, if plug-in is used to express dependency
feature (new in 2.1) - identifier of dependent feature, if feature is used to express dependency. Either plugin or feature attribute must be set, but not both. If "patch" is "true", feature attribute must be used.
version - optional plug-in version specification. If "patch" is "true", version must be set.
match - optional matching rule. Valid values and processing are as follows:

if version attribute is not specifies, the match attribute (if specified) is ignored.
perfect - dependent plug-in version must match exactly the specified version. If "patch" is "true", "perfect" is assumed and other values cannot be set.
equivalent - dependent plug-in version must be at least at the version specified, or at a higher service level (major and minor version levels must equal the specified version).
compatible - dependent plug-in version must be at least at the version specified, or at a higher service level or minor level (major version level must equal the specified version).
greaterOrEqual - dependent plug-in version must be at least at the version specified, or at a higher service, minor or major level.

patch - if "true", this constraint declares the enclosing feature to be a patch for the referenced feature. Certain rules must be followed when this attribute is set:

feature attribute must be used to identifier of feature being patched
version attribute must be set
match attribute should not be set and "perfect" value will be assumed.
if other features are <include>'ed, they must also be patches.

A patch is a special feature that carries newer versions of plug-ins for the feature it is patching. It does not replace the feature. A patch can also carry other patches by inclusion.

<plugin> - identifies referenced plug-in

id - required plug-in identifier (from plugin.xml)
version - required plug-in version (from plugin.xml)
fragment - optional specification indicating if this entry is a plug-in fragment. Default is "false"
os - optional operating system specification. A comma-separated list of os designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this entry should only be installed on one of the specified os systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
ws - optional windowing system specification. A comma-separated list of ws designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this entry should only be installed on one of the specified ws systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
nl - optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this entry should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the entry can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
download-size - optional hint supplied by the feature packager, indicating the download size in KBytes of the referenced plug-in archive. If not specified, the download size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)
install-size - optional hint supplied by the feature packager, indicating the install size in KBytes of the referenced plug-in archive. If not specified, the install size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)
unpack (new in 3.0) - optional specification supplied by the feature packager, indicating that plugin is capable of running from a jar, and contents of plug-in jar should not be unpacked into a directory. Default is "true". (Implementation Note: partial plug-ins - delivered in a feature specifying org.eclipse.update.core.DeltaInstallHandler as an install handler should not set unpack to "false")

<data> - identifies non-plugin data that is part of the feature

id - required data identifier in the form of a relative path.
os - optional operating system specification. A comma-separated list of os designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this entry should only be installed on one of the specified os systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
arch - optional machine architecture specification. A comma-separated list of architecture designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this feature should only be installed on one of the specified systems. If this attribute is not specified, the feature can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of feature regardless of this setting).
ws - optional windowing system specification. A comma-separated list of ws designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform). Indicates this entry should only be installed on one of the specified ws systems. If this attribute is not specified, the entry can be installed on all systems (portable implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
nl - optional locale specification. A comma-separated list of locale designators defined by Java. Indicates this entry should only be installed on a system running with a compatible locale (using Java locale-matching rules). If this attribute is not specified, the entry can be installed on all systems (language-neutral implementation). This information is used as a hint by the installation and update support (user can force installation of entry regardless of this setting).
download-size - optional hint supplied by the feature packager, indicating the download size in KBytes of the referenced data archive. If not specified, the download size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)
install-size - optional hint supplied by the feature packager, indicating the install size in KBytes of the referenced data archive. If not specified, the install size is not known (Implementation Note: the implementation needs to distinguish between "not known" and 0 size)

When interacting with the update site, the feature implementation maps the <plugin> and <data> elements into path identifiers used by the site to determine the actual files to download and install. The default feature implementation supplied by Eclipse constructs the path identifiers as follows:

<plugin> element results in a path entry in the form "plugins/<pluginId>_<pluginVersion>.jar" (for example, "plugins/org.eclipse.core.boot_2.0.0.jar")
<data> element results in a path entry in the form "features/<featureId>_<featureVersion>/<dataId>" (for example, "features/com.xyz.tools_1.0.3/examples.zip")
Note, that in general the feature.xml manifest documents should specify UTF-8 encoding. For example
<?xml version="1.0" encoding="UTF-8"?>
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 (i.e. do not employ the plug-in fragment runtime mechanism).