# 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:

- Version 3.0