Eclipse platform feature manifest

Version 4.2 - Last revised May, 2012

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
    os            CDATA #IMPLIED
    arch          CDATA #IMPLIED
    ws            CDATA #IMPLIED
    nl            CDATA #IMPLIED
    plugin        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

    url           CDATA #REQUIRED
    label         CDATA #IMPLIED
>

<!ELEMENT includes EMPTY>
<!ATTLIST includes
    id                CDATA #REQUIRED
    version           CDATA #REQUIRED
    name              CDATA #IMPLIED
    optional          (true | false) "false"
    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"
>

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.
  • os - optional operating system specification. A comma-separated list of operating system 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 window system 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's. 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).
  • 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.
• <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.
    • url - actual URL
    • label - displayable label (name) for the referenced site
• <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.
  • os - optional operating system specification. A comma-separated list of operating system 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 window system 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's. 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 - 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 specified, 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 operating system 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 window system 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's. 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 - 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".

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).