Eclipse platform plug-in manifest

Version 3.0 - Last revised June 24, 2004

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:

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:

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:

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:

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:

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:

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:

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:

Legal notices.