Difference between revisions of "Tycho/p2iu.xml"

Revision as of 23:30, 25 February 2015

The p2iu.xm file can be used to author IUs directly in XML in a format close to the one used by p2. It advangeously replaces the p2.inf ([1]) that always forced you to author complete IUs in a properties file. As such it makes it easier to author IUs that deliver any file, deliver configuration, or use advanced functionalities of patches. In short nothing stands between you and all the abilities of p2 :).

Format overview

The simplest p2iu.xml file that can be written is the following. Of course such a file does not do much but it shows the main required tags.

  <?xml version='1.0' encoding='UTF-8'?>
  <unit id='org.tycho.demo.rootfiles' version='1.0.0' singleton='false'/>

In addition to the identification done through the id and version tags, a p2iu.xml has three main sections:

• capabilities, which give the opportunity to the iu to describe the capabilities it provides
• requires, which allow for the IU to express requirements on other IUs.
• touchpoint / touchpointData, which allow to control which actions should be executed at different phases of the installation / uninstallation process

Other sections such as update, properties, meta-requirements, that you usually find in normal p2 ius are also supported.

Version expansion

Tycho allows some wildcard versions to be used in the following places:

• In capabilities, when a version ends with qualifier (e.g. 1.2.3.qualifier), the qualifier will be replaced by the build qualifier (e.g. 1.2.3.v20150225)
• In requirements, 0.0.0 will be replaced by the version of the IU matching the requirement. Note that the requirement can denote an IU being built or already existing. In a version ending with qualifier (e.g. 1.2.3.qualifier), the qualifier will be replaced by the qualifier of the IU matching the requirement. Note that the expansion of versions in requirements is only supported for requirements in the org.eclipse.equinox.p2.iu namespace.

IU delivering root files

This p2iu.xml presents a complete IU that delivers root files in the installation folder of an application. This specific IU also requires the installation of a second IU that delivers specific files on windows. You can find the complete example at [[2]]

  <?xml version='1.0' encoding='UTF-8'?>
  <unit id='org.tycho.demo.rootfiles' version='1.0.0' singleton='false'>
    <properties>
      <property name='org.eclipse.equinox.p2.name' value='Root files for my product'/>
    </properties>
    <requires>
        <required namespace='org.eclipse.equinox.p2.iu' name='org.tycho.demo.rootfiles.win' range='1.0.0.qualifier'>
	  <filter>
          (&(osgi.arch=x86_64)(osgi.os=win32)(osgi.ws=win32))
          </filter>
        </required>
    </requires>
    <touchpoint id='org.eclipse.equinox.p2.native' version='1.0.0'/>
    <touchpointData>
      <instructions>
        <instruction key='install'>
          unzip(source:@artifact, target:${installFolder});
        </instruction>
        <instruction key='uninstall'>
          cleanupzip(source:@artifact, target:${installFolder});
        </instruction>
      </instructions>
    </touchpointData>
  </unit>

Copying XML snippet from a content.xml

Though it is currently possible to copy an IU contained in a content.xml into a p2iu.xml file, know that this is a "happy coincidence" and may not be true forever. When performing such a copy, you need to be aware of a couple of things:

• You must rename the IU, and remove any undesired capabilities. In most cases it is probably sufficient to completely remove the capabilities section
• You must remove the artifacts section
• Be sure to cleanup the requires section in order to avoid any extraneous content
• Be sure to review the touchpoint instructions