Eclipse platform plug-in manifest
Version 3.2 - Last revised May 9, 2006
The manifest markup definitions below make use of various naming tokens and
identifiers. To eliminate ambiguity, here are some production rules for these [are
referenced in text below]. In general, all identifiers are case-sensitive.
SimpleToken := sequence of characters from ('a-z','A-Z','0-9','_')
ComposedToken := SimpleToken | (SimpleToken '.' ComposedToken)
QualifiedId := ComposedToken '.' SimpleToken
ExtensionId := SimpleToken | QualifiedId
ExtensionPointId := SimpleToken | QualifiedId
ExtensionPointReference := SimpleToken | QualifiedId
The remainder of this section describes the plugin.xml file structure as a series
of DTD fragments. File
plugin.dtd presents the DTD
definition in its entirety.
<?xml encoding="US-ASCII"?>
<?eclipse version="3.2"?>
<!ELEMENT plugin (extension-point*, extension*)>
The <plugin> element defines the body of the manifest. It optionally contains
declarations of any new extension points being introduced by the
plug-in, as well as configuration of functional extensions (configured into
extension points defined by other plug-ins, or introduced by this plug-in).
The XML DTD construction rule
element*
means zero
or more occurrences of the element;
element?
means zero or
one occurrence of the element; and
element+
(used below) means one or more
occurrences of the element. Based on the <plugin> definition above, this
means, for example, that a plug-in containing no
extension point declarations or extension configurations is valid (for example,
common libraries that other plug-ins depend on). Similarly, a plug-in
containing only extension configurations and no extension points of
its own is also valid (for example, configuring classes delivered in other
plug-ins into extension points declared in other plug-ins).
The Eclipse architecture is based on the notion of configurable extension
points. The platform itself predefines a set of extension points that cover the
task of extending the platform and desktop (for example, adding menu actions,
contributing embedded editor). In addition to the predefined extension points,
each supplied plug-in can declare additional extension points. By declaring an
extension point the plug-in is essentially advertising the ability to configure
the plug-in function with externally supplied extensions. For example, the Page
Builder plug-in may declare an extension point for adding new Design Time
Controls (DTCs) into its builder palette. This means that the Page Builder has
defined an architecture for what it means to be a DTC and has implemented the
code that looks for DTC extensions that have been configured into the extension
points.
<!ELEMENT extension-point EMPTY>
<!ATTLIST extension-point
name CDATA #REQUIRED
id CDATA #REQUIRED
schema CDATA #IMPLIED
>
The <extension-point> element has the following attributes:
-
name - user-displayable (translatable) name for the extension point
-
id - Either a simple id token, or a fully qualified id. Simple id should be
used unless there is an actual need to specify a fully qualified id.
- Simple id token should be unique within this plug-in. The simple id token cannot contain dot (.) or
whitespace
- Qualified id should uniquely identify this extension point among all Eclipse extension points
- [production rule: ExtensionPointId]
-
schema - schema
specification for this extension point. The exact details are being
defined as part of the Plug-In Development Environment (PDE). The schema
is currently not used at runtime. The reference is a file name relative to
the plug-in installation location.
Actual extensions are configured into extension points (predefined, or newly declared
in this plug-in) in the <extension> section. The configuration
information is specified as well-formed XML contained between the <extension>
and </extension> tags. The platform does not specify the actual form of
the configuration markup (other than requiring it to be well-formed XML). The
markup is defined by the supplier of the plug-in that declared the extension
point. The platform does not actually interpret the configuration markup. It
simply passes the configuration information to the plug-in as part of the
extension point processing (at the time the extension point logic queries all
of its configured extensions).
<!ELEMENT extension ANY>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
The <extension> element has the following attributes:
-
point - reference to
an extension point being configured. The extension point can be one
defined in this plug-in or another plug-in
- [production rule: ExtensionPointReference]
-
id - optional identifier for this extension point configuration instance. This is used
by extension points that need to uniquely identify (rather than just enumerate) the specific
configured extensions. Can be specified as either a simple id token, or a fully qualified id
- Simple id token should be unique within the definition of the declaring plug-in. The simple id
token cannot contain dot (.) or whitespace.
- Qualified id should uniquely identify this extension among all Eclipse extensions
- [production rule: ExtensionId]
-
name - user-displayable (translatable) name for the extension
Important:
The content of the <extension> element is declared using the ANY rule.
This means that any well-formed XML can be specified within the extension
configuration section (between <extension> and </extension> tags).
Fragments
Fragments are used to increase the scope of a plug-in.
An example would be to incorporate data such as messages or labels in another language.
<?xml encoding="US-ASCII"?>
<?eclipse version="3.2"?>
<!ELEMENT fragment (extension-point*, extension*)>
The <extension-point>, and <extension> components of a fragment will be logically added to the hosting plug-in.
Note on the ExtensionId and ExtensionPointId
Special processing was added to support backward compatibility for ExtensionId and ExtensionPointId
that used to contain dots ('.') prior to the version 3.2. Depending on the version specified in
the <?eclipse version?> tag:
- If the version is below 3.2, then qualified name = PluginID '.' (ExtensionID | ExtensionPointID)
This rule applies only to the ExtensionId and ExtensionPointId that contain dot ('.') character(s).
Older versions of the plug-in manifest can be found here:
