Eclipse platform plug-in manifest

Version 3.0 - Last revised June 24, 2004

This is an archived version of the document. The current version can be found here.

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)
JavaClassName := ComposedToken
PlugInId := ComposedToken
PlugInPrereq := PlugInId | 'export' PlugInId
ExtensionId := SimpleToken
ExtensionPointId := SimpleToken
ExtensionPointReference := ExtensionPointID | (PlugInId '.' ExtensionPointId)

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"?>
<!ELEMENT plugin (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST plugin
  name                CDATA #REQUIRED
  id                  CDATA #REQUIRED
  version             CDATA #REQUIRED 
  provider-name       CDATA #IMPLIED
  class               CDATA #IMPLIED 
>

The <plugin> element defines the body of the manifest. It optionally contains definitions for the plug-in runtime, definitions of other plug-ins required by this one, 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). <plugin> attributes are as follows:

name - user displayable (translatable) name for the plug-in
id - unique identifier for the plug-in.
- To minimize potential for naming collisions, the identifier should be derived from the internet domain id of the supplying provider (reversing the domain name tokens and appending additional name tokens separated by dot [.]). For example, provider ibm.com could define plug-in identifier com.ibm.db2
- [production rule: PlugInId]
version - plug-in version number. See org.eclipse.core.runtime.PluginVersionIdentifier for details. Plug-in version format is major.minor.service.qualifier. Change in the major component is interpreted as an incompatible version change. Change in the minor component is interpreted as a compatible version change. Change in the service component is interpreted as cumulative service applied to the minor version. Change in the qualifier component is interpreted as different source code control version of the same component.
provider-name - user-displayable name of the provider supplying the plug-in.
class - name of the plug-in class for this plug-in. The class must be a subclass of org.eclipse.core.runtime.Plugin.

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 only a run-time definition and 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 runtime or 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 <requires> section of the manifest declares any dependencies on other plug-ins.

<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
 plugin               CDATA #REQUIRED
 version              CDATA #IMPLIED
 match                (perfect | equivalent | compatible | greaterOrEqual) "compatible"
 export               (true | false) "false"
 optional             (true | false) "false"
>

Each dependency is specified using an <import> element. It contains the following attributes:

plugin - identifier of the required plug-in
version - optional version specification
match - version matching rule. Ignored if version attribute is not specified. Determines whether the dependency is satisfied only with a plug-in that has this exact specified version, with a plug-in that has a service or qualifier more recent than this one, with any compatible version (including a more recent minor version of the plug-in) or with any more recent version of this plug-in
export - specifies whether the dependent plug-in classes are made visible (are (re)exported) to users of this plug-in. By default, dependent classes are not exported (are not made visible)
optional - specifies whether or not this dependency will be strictly enforced. If set to <true> and this dependency cannot be satisfied, the dependency will be ignored

The <runtime> section of the manifest contains a definition of one or more libraries that make up the plug-in runtime. The referenced libraries are used by the platform execution mechanisms (the plug-in class loader) to load and execute the correct code required by the plug-in.

<!ELEMENT runtime (library+)>
<!ELEMENT library (export*, packages?)>
<!ATTLIST library
  name               CDATA #REQUIRED
  type               (code | resource) "code"
>
<!ELEMENT export EMPTY>
<!ATTLIST export
  name               CDATA #REQUIRED
>
<!ELEMENT packages EMPTY>
<!ATTLIST packages
  prefixes           CDATA #REQUIRED
>

The <runtime> element has no attributes.

The <library> elements collectively define the plug-in runtime. At least one <library> must be specified. Each <library> element has the following attributes:

name - string reference to a library file or directory containing classes (relative to the plug-in install directory). Directory references must contain trailing file separator.
type - specifies whether this library contains executable code (<code>) or just resources. If the library is of type <code> accessing anything in this library will cause activation of the plug-in. Accessing a <resource> will not cause plug-in activation (a potential for significant performance improvement). It should be noted that specifying a library of type <code> allows it to contain both code and resources. But specifying a library of type <resource> assumes it will only be used for resources.

Each <library> element can specify which portion of the library should be exported. The export rules are specified as a set of export masks. By default (no export rules specified), the library is considered to be private. Each export mask is specified using the name attribute, which can have the following values:

* - indicates all contents of library are exported (public)
package.name.* - indicates all classes in the specified package are exported. The matching rules are the same as in the Java import statement.
package.name.ClassName - fully qualified java class name

Eclipse 2.1 plug-ins only: Each library can also specify the package prefixes. These are used to enhance the classloading performance for the plug-in and/or fragment. If the <packages> element is not specified, then by default the classloading enhancements are not used. The <packages> element has the following attribute:

prefixes - a comma-separated list of package prefixes for the runtime library

The platform's 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 - simple id token, unique within this plug-in. The token cannot contain dot (.) or whitespace.
- [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. The identifier is specified as a simple token unique within the definition of the declaring plug-in. When used globally, the extension identifier is qualified by the plug-in identifier
- [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 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"?> 
<!ELEMENT fragment (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST fragment
  name                CDATA #REQUIRED
  id                  CDATA #REQUIRED
  version             CDATA #REQUIRED
  provider-name       CDATA #IMPLIED
  plugin-id           CDATA #REQUIRED
  plugin-version      CDATA #REQUIRED
  match               (perfect | equivalent | compatible | greaterOrEqual) "compatible"
>

Each fragment must be associated with a specific plug-in. The associated plug-in is identified with <plugin-id>, <plugin-version> and optionally, <match>. Note that if this specification matches more than one plug-in, the matching plug-in with the highest version number will be used.

The <requires>, <runtime>, <extension-point>, and <extension> components of a fragment will be logically added to the matching plug-in.

<fragment> attributes are as follows:

name - user displayable (translatable) name for the fragment
id - unique identifier for the fragment.
- To minimize potential for naming collisions, the identifier should be derived from the id of the associated plug-in in addition to something which identifies the scope of this fragment. For example, org.eclipse.core.runtime.nl1 could define a natural language fragment for the org.eclipse.core.runtime plug-in
- [production rule: PlugInId]
version - fragment version number. See org.eclipse.core.runtime.PluginVersionIdentifier for details. Fragment version format is the same as plug-in version format.
provider-name - user-displayable name of the provider supplying the fragment.
plugin-id - matches the id of the associated plug-in
plugin-version - matches the version of the associated plug-in
match - the matching rule used to find an associated plug-in using <plugin-id> and <plugin-version>. See the definition of <match> in the <requires> clause for complete details.