Publishing p2 metadata

The p2 metadata contains useful information about the elements that can be installed. These elements are called Installable Units (IUs). Among other things, the IUs describe dependencies, properties and configuration information.

There are three different ways p2 repositories can be created. 1) By using the export wizard, 2) using PDE Build, and 3) using the publisher. The Plug-in Development Environment Guide explains how the feature export wizard, product export wizard and PDE Build can be used to generate metadata. The remainder of this document explains how the publisher can be used.

The publisher is the means by which deployable entities get added to repositories. For example, the publisher can be used to create an IU from an OSGi Bundle or Eclipse Feature. The publisher consists of an extensible set of publishing actions, applications and Ant tasks that allow users to generate p2 repositories from a number of different sources.

In order to be backwards-compatible, p2 is able to install things from old-style update sites and extension locations by generating metadata for these things on-the-fly, but this of course is not the optimal situation. Ideally, plug-in developers should create p2 metadata when they produce their bundles, features, and products.

This document describes how to publish p2 metadata for your software using the publisher.

The publisher can be used in two ways:

  1. Command line applications
  2. Ant Tasks

Command Line Applications

p2 ships with four command line publisher applications that plug-in developers can run. The applications are contained in org.eclipse.equinox.p2.publisher and org.eclipse.equinox.p2.updatesite. These bundles are part of the Eclipse SDK. The four applications are:

  1. UpdateSite Publisher
  2. Features And Bundles Publisher
  3. Product Publisher
  4. Category Publisher

UpdateSite Publisher

The updatesite publisher application (org.eclipse.equinox.p2.publisher.UpdateSitePublisher) is a command line application that is capable of generating metadata (p2 repositories) from an update site containing a site.xml, bundles and features. The updatesite publisher can be invoked using the generic Eclipse launcher format as follows:

eclipse -application org.eclipse.equinox.p2.publisher.UpdateSitePublisher <publisherArgs>

Here are the supported command-line options:

-metadataRepository <URI>
the URI to the metadata repository where the installable units should be published
-artifactRepository <URI>
the URI to the artifact repository where the artifacts should be published
-source <path>
the location of the update site
-compress
a flag indicating that the repository should be compressed
-append
flag indicating that repositories will be appended to as opposed to over-written
-publishArtifacts
flag indicating that the artifacts should be published (copied) to the repository. When this flag is not set, the actual bytes underlying the artifact will not be copied, but the repository index will be created. When this option is not specified, it is recommended to set the artifactRepository to be in the same location as the source (-source).

Here is an example of how the updatesite publisher can be used to create a compressed p2 repository from an update site: 

eclipse -application org.eclipse.equinox.p2.publisher.UpdateSitePublisher
 -metadataRepository file:/<some location>/repository
 -artifactRepository file:/<some location>/repository
 -source /<location with a site.xml>
 -configs gtk.linux.x86
 -compress
 -publishArtifacts

Once you run the publisher, you will see the generated artifact repository index file in artifacts.xml and the generated metadata repository index file in the content.xml (or artifacts.jar and content.jar if you used the -compress option). There is nothing forcing you to have the metadata and artifact repositories co-located, but you can do this if you wish to.

Features And Bundles Publisher

The features and bundles publisher application (org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher) is a command line application that is capable of generating metadata (p2 repositories) from pre-built Eclipse bundles and features. The features and bundle publisher can be invoked using the generic Eclipse launcher format as follows:

eclipse -application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher <publisherArgs>

Here are command-line options:

-metadataRepository <URI>
the URI to the metadata repository where the installable units should be published
-artifactRepository <URI>
the URI to the artifact repository where the artifacts should be published
-source <path>
the location of the update site
-bundles <path>
the location of the bundles
-features <path>
the location of the features
-compress
a flag indicating that the repository should be compressed
-append
flag indicating that repositories will be appended to as opposed to over-written
-publishArtifacts
flag indicating that the artifacts should be published (copied) to the repository. When this flag is not set, the actual bytes underlying the artifact will not be copied, but the repository index will be created. When this option is not specified, it is recommended to set the artifactRepository to be in the same location as the source (-source).

The features and bundles publisher application can be invoked using the -source option by pointing at a directory that contains two sub-directories (features and plug-ins). The publisher can also be invoked by pointing at the bundles and features separately and using the -bundles and -features options.

Here is an example of how the features and bundles publisher can be used to create a compressed p2 repository from a collection of bundles and features: 

eclipse -application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher
   -metadataRepository file:/<some location>/repository
   -artifactRepository file:/<some location>/repository
   -source /<location with a plugin and feature directory>
   -configs gtk.linux.x86
   -compress
   -publishArtifacts

Product Publisher

The product publisher application (org.eclipse.equinox.p2.publisher.ProductPublisher) is a command line application that is capable of generating metadata (p2 repositories) from a .product file. The product publisher does not generate metadata for the bundles and features that make up the product. The product publisher can be invoked using the generic Eclipse launcher format as follows:

eclipse -application org.eclipse.equinox.p2.publisher.ProductPublisher <publisherArgs>

Here are the supported command-line options:

-metadataRepository <URI>
the URI to the metadata repository where the installable units should be published
-artifactRepository <URI>
the URI to the artifact repository where the artifacts should be published
-productFile <path>
the location of the product file
-executables <path>
the location of the executables feature
-flavor <String>
the flavor used for the configuration units (if unsure, using tooling)
-compress
a flag indicating that the repository should be compressed
-append
flag indicating that repositories will be appended to as opposed to over-written
-configs <spec>
a set of environment properties for the os, ws and arch parameters of the system which the product supports and can be provisioned on; can specify more than one platform in a comma-separated list of such triplets; if the product can support any environment, "-configs ANY" or "-configs ANY.ANY.ANY" should be used.

Here is an example of how the product publisher can be used to create a p2 repository from a .product file:

eclipse -application org.eclipse.equinox.p2.publisher.ProductPublisher
   -metadataRepository file:/<some location>/repository
   -artifactRepository file:/<some location>/repository
   -productFile /<location>/<filename>.product
   -append
   -executables /<deltapack parent>/delta/eclipse/features/org.eclipse.equinox.executable_3.3.200.v20090426-1530-7M-Fm-FI3UouOdcoUJz-7oc
   -flavor tooling
   -configs gtk.linux.x86

Category Publisher

The category publisher application (org.eclipse.equinox.p2.publisher.CategoryPublisher) is a command line application that is capable of categorizing a set of Installable Units in a given repository. The categorization is driven from a category file. The category publisher can be invoked using the generic Eclipse launcher format as follows:

eclipse -application org.eclipse.equinox.p2.publisher.CategoryPublisher <publisherArgs>

Here is an example of how the product publisher can be used to categorize a p2 repository from a category.xml file: 

eclipse -application -application org.eclipse.equinox.p2.publisher.CategoryPublisher
   -metadataRepository file:/<some location>/repository
   -categoryDefinition file:/<some location>/category.xml
   -compress

Categories are always appended to a repository.

Updated Documentation

Up-to-date information on the p2 publisher can be found on the Eclipse p2 wiki.