Generating p2 metadata

As of Eclipse 3.5 the metadata generator is depreciated. The publisher should be used instead.

With the "classic" Update Manager, all metadata for features and bundles is self-contained in the features and bundles themselves. In p2 the metadata contains more information and is stored separately in what are called Installable Units (IUs) and Configuration Units (CUs).

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 generate p2 metadata for your software.

The Metadata Generator Application

Since Eclipse 3.4, p2 ships with a metadata generator application that plug-in developers can run. The generator application is contained in the bundle org.eclipse.equinox.p2.metadata.generator. This bundle is part of the Eclipse SDK, and is also available in the p2 Admin UI. The generator can be invoked using the generic Eclipse launcher format as follows:

eclipse -application org.eclipse.equinox.p2.metadata.generator.EclipseGenerator <generatorArgs>

The generator application has three primary modes of operation:

1. Generating metadata for a folder containing bundles and features (-source argument)
2. Generating metadata for a traditional Eclipse update site (-updateSite argument)
3. Generating metadata for an existing Eclipse application that does not contain p2 metadata (-config argument)

Note that you can also generate metadata for your features, bundles, and products through the PDE UI and in headless PDE builds. See the Export Wizards section in the Plug-in Development Environment Guide as well as PDE Build integration with p2 for details.

Once you run the generator, 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.

1. Bundles and Features

If you have a directory with bundles and features and you want to create p2 metadata for them, you can use the p2 metadata generator. Here is an example of using the generator in this scenerio. In this case the features and bundles are located under the D:/myData/ directory and the artifact and metadata repositories are co-located and produced to D:/repository/. In this case the bundles and features are copied (published) to the artifact repository folder (D:/repository/). This repository folder can be published to a server without any further modification.

eclipse
   -application org.eclipse.equinox.p2.metadata.generator.EclipseGenerator
   -source D:/myData/
   -metadataRepository file:D:/repository/
   -metadataRepositoryName "My Update Site"
   -artifactRepository file:D:/repository/
   -artifactRepositoryName "My Artifacts"
   -publishArtifacts
   -publishArtifactRepository
   -compress
   -noDefaultIUs
   -vmargs -Xmx256m

2. Update Manager Site

If you have an update manager site (site index file along with features and plug-ins) and you would like to generate p2 metadata, you can use the metadata generator application. The following example shows how to generate metadata from an pre-existing update site located in D:\ganymedeM5. The output files from the operation will also be placed in the D:\ganymedeM5 folder so clients will be able to point to the same location, regardless of which UI they are using.

eclipse
   -application org.eclipse.equinox.p2.metadata.generator.EclipseGenerator
   -updateSite D:/ganymedeM5/
   -site file:D:/ganymedeM5/site.xml
   -metadataRepository file:D:/ganymedeM5/
   -metadataRepositoryName "Ganymede Update Site"
   -artifactRepository file:D:/ganymedeM5/
   -artifactRepositoryName "Ganymede Artifacts"
   -compress
   -reusePack200Files
   -noDefaultIUs
   -vmargs -Xmx256m

3. Existing Non-p2 Eclipse Application

If you have an existing Eclipse application with plug-ins, features, root files and a configuration, then you can use the -config mode to run the generator.

eclipse
   -application org.eclipse.equinox.p2.metadata.generator.EclipseGenerator
   -config D:/application/
   -metadataRepository file:D:/repository/
   -metadataRepositoryName "My Update Site"
   -artifactRepository file:D:/repository/
   -artifactRepositoryName "My Artifacts"
   -publishArtifacts
   -publishArtifactRepository
   -root my.application
   -rootVersion 1.0.0
   -compress
   -noDefaultIUs
   -vmargs -Xmx256m

Input Arguments

You can invoke the p2 metadata generator in one of these modes:

-source <path>

the path to a folder containing plugins and features folders

-updateSite <path>

the path to a traditional update site

-config <path>

the path of an Eclipse application that is not p2-enabled

Here are other command-line options:

-exe <path>

the location of the application launcher executable

-launcherConfig <path>

the path of the launcher configuration file (e.g. eclipse.ini)

-features <path>

the location of the features folder

-bundles <path>

the location of bundles folder

-base <path>

a base location containing a plugins and features directory

-p2.os <os>

the target operating system for the application

-site <path>

the URL of a site.xml file used to generate categories

Output Arguments

And some more command-line arguments related to the output:

-metadataRepository <url>

the URL to a writable metadata repository that will contain the produced metadata

-metadataRepositoryName <name>

a user-friendly name for the metadata repository

-artifactRepository <url>

the URL to a writable artifact repository that will contain the produced artifacts

-artifactRepositoryName <name>

a user-friendly name for the artifact repository

-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).

-publishArtifactRepository

flag indicating to write out the artifact repository index file

-append

flag indicating that repositories will be appended to as opposed to over-written

-root <name>

When you run the generator application, it will create a root IU which will contain everything that has been generated during this run. This argument is used for setting the name of the root IU.

-rootVersion <version>

The version of the root installable unit

-inplace

causes the metadata and artifact repositories to be written into the source location

-noDefaultIUs

flag to indicate the default configuration units should not be created

-compress

cause the repositories to store their index files in compressed form

-reusePack200Files

Specifying -reusePack200 does not require you to have pack200 files on the server, nor does it cause pack200 files to be created. When this option is specified, the generator looks for pack.gz files and if available it creates an entry for them in the artifact repository index.

Generator Ant Task

The metadata generator is also available as an Ant task. It iscalled p2.generator and it is available in the org.eclipse.equinox.p2.metadata.generator bundle. The arguments passed to the task are the same as listed above.

Updated Documentation

Up-to-date information on the p2 metadata generator application can be found on the Eclipse p2 wiki.