| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html lang="en"> |
| <head> |
| <meta name="copyright" |
| content="Copyright (c) EclipseSource and others 2009, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=ISO-8859-1"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <link REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Publishing p2 metadata</title> |
| </head> |
| <body> |
| <h1>Publishing p2 metadata</h1> |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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 |
| <a href="../../org.eclipse.pde.doc.user/guide/tools/export_wizards/export_features.htm">feature export wizard</a>, |
| <a href="../../org.eclipse.pde.doc.user/guide/tools/export_wizards/export_product.htm">product export wizard</a> and |
| <a href="../../org.eclipse.pde.doc.user/tasks/pde_p2_builds.htm">PDE Build</a> |
| can be used to generate metadata. The remainder of this document explains how the publisher can be used. |
| </p> |
| |
| <p> |
| The <em>publisher</em> 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. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| This document describes how to publish p2 metadata for your software using <b>the publisher</b>. |
| </p> |
| |
| <p> |
| The publisher can be used in two ways: |
| </p> |
| <ol> |
| <li><a href="#headless_applications">Command line applications</a></li> |
| <li><a href="p2_publishingtasks.htm">Ant Tasks</a></li> |
| </ol> |
| |
| <h2><a name="headless_applications">Command Line Applications</a></h2> |
| <p> |
| p2 ships with four command line publisher applications that plug-in developers can run. The applications are contained |
| in <code>org.eclipse.equinox.p2.publisher</code> and <code>org.eclipse.equinox.p2.updatesite</code>. These bundles are |
| part of the Eclipse SDK. The four applications are: |
| </p> |
| |
| <ol> |
| <li><a href="#updatesite_publisher">UpdateSite Publisher</a></li> |
| <li><a href="#features_and_bundles_publisher">Features And Bundles Publisher</a></li> |
| <li><a href="#product_publisher">Product Publisher</a></li> |
| <li><a href="#category_publisher">Category Publisher</a></li> |
| </ol> |
| |
| <h3><a name="updatesite_publisher">UpdateSite Publisher</a></h3> |
| |
| <p> |
| The updatesite publisher application (<code>org.eclipse.equinox.p2.publisher.UpdateSitePublisher</code>) 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: |
| </p> |
| |
| <p> |
| <code>eclipse -application org.eclipse.equinox.p2.publisher.UpdateSitePublisher <publisherArgs></code> |
| </p> |
| |
| <p>Here are the supported command-line options:</p> |
| |
| <dl> |
| <dt><code>-metadataRepository <URI></code></dt> |
| <dd>the URI to the metadata repository where the installable units should be published</dd> |
| <dt><code>-artifactRepository <URI></code></dt> |
| <dd>the URI to the artifact repository where the artifacts should be published</dd> |
| <dt><code>-source <path></code></dt> |
| <dd>the location of the update site</dd> |
| <dt><code>-compress</code></dt> |
| <dd>a flag indicating that the repository should be compressed</dd> |
| <dt><code>-append</code></dt> |
| <dd>flag indicating that repositories will be appended to as opposed to over-written</dd> |
| <dt><code>-publishArtifacts</code></dt> |
| <dd>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 (<code>-source</code>).</dd> |
| </dl> |
| |
| <p>Here is an example of how the updatesite publisher can be used to create a compressed p2 repository from an update site: </p> |
| <pre> |
| 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 |
| </pre> |
| |
| <p> |
| Once you run the publisher, you will see the generated artifact repository index file in <code>artifacts.xml</code> and |
| the generated metadata repository index file in the <code>content.xml</code> (or <code>artifacts.jar</code> and |
| <code>content.jar</code> 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. |
| </p> |
| |
| <h3><a name="features_and_bundles_publisher">Features And Bundles Publisher</a></h3> |
| |
| <p> |
| 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: |
| </p> |
| |
| <p> |
| <code>eclipse -application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher <publisherArgs></code> |
| </p> |
| |
| <p>Here are command-line options:</p> |
| <dl> |
| <dt><code>-metadataRepository <URI></code></dt> |
| <dd>the URI to the metadata repository where the installable units should be published</dd> |
| <dt><code>-artifactRepository <URI></code></dt> |
| <dd>the URI to the artifact repository where the artifacts should be published</dd> |
| <dt><code>-source <path></code></dt> |
| <dd>the location of the update site</dd> |
| <dt><code>-bundles <path></code></dt> |
| <dd>the location of the bundles</dd> |
| <dt><code>-features <path></code></dt> |
| <dd>the location of the features</dd> |
| <dt><code>-compress</code></dt> |
| <dd>a flag indicating that the repository should be compressed</dd> |
| <dt><code>-append</code></dt> |
| <dd>flag indicating that repositories will be appended to as opposed to over-written</dd> |
| <dt><code>-publishArtifacts</code></dt> |
| <dd>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 (<code>-source</code>).</dd> |
| </dl> |
| |
| <p> |
| The features and bundles publisher application can be invoked using the <code>-source</code> 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 <code>-bundles</code> and <code>-features</code> options. |
| </p> |
| |
| <p>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: </p> |
| <pre> |
| 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 |
| </pre> |
| |
| <h3><a name="product_publisher">Product Publisher</a></h3> |
| <p> |
| The product publisher application (<code>org.eclipse.equinox.p2.publisher.ProductPublisher</code>) 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: |
| </p> |
| |
| <p> |
| <code>eclipse -application org.eclipse.equinox.p2.publisher.ProductPublisher <publisherArgs></code> |
| </p> |
| |
| <p>Here are the supported command-line options:</p> |
| <dl> |
| <dt><code>-metadataRepository <URI></code></dt> |
| <dd>the URI to the metadata repository where the installable units should be published</dd> |
| <dt><code>-artifactRepository <URI></code></dt> |
| <dd>the URI to the artifact repository where the artifacts should be published</dd> |
| <dt><code>-productFile <path></code></dt> |
| <dd>the location of the product file</dd> |
| <dt><code>-executables <path></code></dt> |
| <dd>the location of the executables feature</dd> |
| <dt><code>-flavor <String></code></dt> |
| <dd>the flavor used for the configuration units (if unsure, using tooling)</dd> |
| <dt><code>-compress</code></dt> |
| <dd>a flag indicating that the repository should be compressed</dd> |
| <dt><code>-append</code></dt> |
| <dd>flag indicating that repositories will be appended to as opposed to over-written</dd> |
| <dt><code>-configs <spec></code></dt> |
| <dd>a set of environment properties for the <tt>os</tt>, <tt>ws</tt> and <tt>arch</tt> 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, <tt>"-configs ANY"</tt> or <tt>"-configs ANY.ANY.ANY"</tt> should be used.</dd> |
| </dl> |
| |
| <p>Here is an example of how the product publisher can be used to create a p2 repository from a .product file:</p> |
| |
| <pre> |
| 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 |
| </pre> |
| |
| <h3><a name="category_publisher">Category Publisher</a></h3> |
| <p> |
| 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: |
| </p> |
| |
| <p> |
| <code>eclipse -application org.eclipse.equinox.p2.publisher.CategoryPublisher <publisherArgs></code> |
| </p> |
| |
| <p>Here is an example of how the product publisher can be used to categorize a p2 repository from a category.xml file: </p> |
| |
| <pre> |
| eclipse -application -application org.eclipse.equinox.p2.publisher.CategoryPublisher |
| -metadataRepository file:/<some location>/repository |
| -categoryDefinition file:/<some location>/category.xml |
| -compress |
| </pre> |
| <p> |
| Categories are always appended to a repository. |
| </p> |
| |
| <h2>Updated Documentation</h2> |
| <p> |
| Up-to-date information on the p2 publisher can be found on the |
| <a href="http://wiki.eclipse.org/Equinox/p2/Publisher">Eclipse p2 wiki</a>. |
| </p> |
| </body> |
| </html> |