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:
- Generating metadata for a folder containing bundles and features (
-source
argument)
- Generating metadata for a traditional Eclipse update site (
-updateSite
argument)
- 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.