|
|
|
|
Eclipse platform feature manifest
Version 3.0 - Last revised June 3, 2009
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
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).
- colocation-affinity - (deprecated) 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 - (deprecated) 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>
-
Note: The install-handler element is deprecated. Install handlers
are still supported using a compatibility mechanism, but they should be avoided.
- 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 (deprecated) - by default, discovery sites are assumed to be update sites
("update"). Setting the value of this attribute to "web"
indicates 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
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 (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
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 (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
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'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).
- 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 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).
|
|
|