# The platform.xml file

### Since:

3.0

### Description:

The primary update manager configuration information is maintained by the platform.xml file located in the configuration directory (usually, eclipse/configuration/org.eclipse.update/platform.xml). This file format is internal and can change any time, but, in practice, it should not change much, if at all.

As some people would like to take advantage of shipping an eclipse based product with a pre-defined installation configuration, this document provides some syntax and semantics info for this configuration file.

Given that the platform.xml originated from the old platform.cfg and installConfig*.xml file, there are still some deprecated elements/attributes that will not be mentioned in this doc, as well as some relatively convoluted way of specifying the configuration info. If platform.xml is to become API, then some re-work is needed (both syntax and semantics).

### Configuration Markup:

<!ELEMENT extension EMPTY>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

<!ELEMENT config EMPTY>

<!ATTLIST config

version CDATA #IMPLIED

date CDATA #IMPLIED

transient (true | false) "false"

shared_ur CDATA #IMPLIED>

describes the current install configuration.

- version - this attribute may be used to indentify the version of the configuration specification
- date - this is an internal attribute that is generated by the update configurator code. If you manually create or modify the platform.xml file then remove this attribute, and let the update code add it when it first runs. In this scenario, update will not try to reconcile the platform.xml with what is on the disk, it takes the platform.xml as is, and slaps the date attribute.
- transient - a transient configuration is not modified by the update code, it is just read and used to configure the plugins to run. Its main point is to avoid doing any reconciliation with what's on the disk. This flag is a bit of a hack for PDE to run self hosting without having features in the workspace, and it is better if it is left set to false.
- shared_ur - points to the shared configuration location. This is particularly useful on unix/linux, when the admin sets up a shared installation and each user's configuration consists of the shared installation data (as pointed at by this attribute) and any local changes.

<!ELEMENT site EMPTY>

<!ATTLIST site

url CDATA #REQUIRED

enabled (true | false)

updateable (true | false)

policy (USER-EXCLUDE|USER-INCLUDE|MANAGED-ONLY)

linkfile CDATA #IMPLIED

list CDATA #IMPLIED>

defines an installation location, which is a location that contains features and plugins.

- url - location of this installation site. The url is absolute, but there is a special url for the base location (where eclipse.exe is located), of the form platform:/base/
- enabled - a boolean value that defines whether the plugins and features from this location will be considered at runtime.
- updateable - defines whether any update/install/enable/uninstall/etc. operations can be performed on features on this site.
- policy - defines the way the "list" attribute is interpreted:
  USER-EXCLUDE: all the plugins from the site are run, except those listed in the "list" attribute. This is what's currently used by the update code.
  USER-INCLUDE: only the plugins listed by the "list" attribute are run. This is what PDE generated configurations use.
  MANAGED-ONLY: only plugins from the features define by this site (see the <feature> element) are run (new in 3.1)
- linkfile - if this site has been contributed from a .link file, then this attribute points to that file.
- list - lists the plugins to be included or excluded (see the "policy" attribute) at runtime.

<!ELEMENT feature EMPTY>

<!ATTLIST feature

id CDATA #REQUIRED

version CDATA #REQUIRED

url CDATA #REQUIRED>

defines a feature installed on this site.

- id - the feature id
- version - the feature version
- url - the feature location, relative to the site. By default, the url is of the form features/some_feature_id_version.

#### Example:

    <?xml version="1.0" encoding="UTF-8"?>
    <config date="1119300698390" transient="false" version="3.0">
      <site enabled="true" policy="USER-EXCLUDE" updateable="true" url="platform:/base/">
        <feature id="org.eclipse.platform" url="features/org.eclipse.platform_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.platform.source" url="features/org.eclipse.platform.source_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.rcp" url="features/org.eclipse.rcp_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.jdt" url="features/org.eclipse.jdt_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.jdt.source" url="features/org.eclipse.jdt.source_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.pde" url="features/org.eclipse.pde_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.sdk" url="features/org.eclipse.sdk_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.pde.source" url="features/org.eclipse.pde.source_3.1.0/" version="3.1.0">
        </feature>
        <feature id="org.eclipse.rcp.source" url="features/org.eclipse.rcp.source_3.1.0/" version="3.1.0">
        </feature>
      </site>
      <site enabled="true" policy="USER-EXCLUDE" updateable="true" url="file:/d:/extensions/org.eclipse.core.tools/eclipse/">
      </site>
    </config>