Equinox/p2/Publisher

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

The Publisher is the means by which deployable entities get added to repositories. It 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.

Publisher Actions

The publisher applications and Ant tasks each execute a set of publisher actions. This section describes the behaviour of some of these actions.

BundlesAction

The BundlesAction generates the p2 metadata for OSGi bundles.

Optional runtime dependencies (i.e. an resolution:=optional directive in Require-Bundle or ImportPackage headers) are interpreted in the following way:

In Indigo and earlier, an optional greedy dependency was generated, i.e. the optionally required bundle or package was installed whenever possible.
Since Juno M1, an optional non-greedy dependency is generated, i.e. the optional run-time dependency will not cause any additional installation. At runtime, the optional requirement will only be satisfied, if there was some other, mandatory requirement to the provider, e.g. through an already installed feature.

If the old behaviour is desired, i.e. an optional dependency shall be satisfied during installation whenever possible, the dependency can be annotated with an additional directive: resolution:=optional;x-installation:=greedy.

Note: Optional greedy dependencies should be avoided, because they don't really give the users of your bundle the choice whether they want the optional content installed or not (see bug 247099). Instead, you should offer additional features, e.g. "MyTool integration with XYZ", which have mandatory requirements to the optional content and hence cause the installation if the user chooses to install the feature.

ProductAction

The ProductAction translates a PDE product configuration to an IU, which, when installed with the p2 director, results in an Eclipse or RCP application installation. By including various other actions, the product action also generates a bunch of technical IUs which tell p2 to create an Eclipse layout when installing.

File format extensions: The product action supports the following extensions to the PDE product configuration format:

By setting the attribute type="mixed" in the product element, the product content is defined through both features and bundles listed in the product. (Introduced in Juno M1/bug 325622; official support in PDE requested in bug 325614)

Headless Applications

The Publisher consists of a number of headless (no GUI) Eclipse Applications that can be used to generate metadata from a variety of sources. Examples of such applications include:

FeaturesAndBundles Publisher: Generates metadata from a set of features and bundles
Product Publisher: Generates metadata from a .product file
Category Publisher: Generates categories for an existing repository
UpdateSite Publisher: Generates metadata from an UpdateSite
Install Publisher: Generates metadata from an existing Eclipse install

UpdateSite Publisher Application

The UpdateSite Publisher Application (org.eclipse.equinox.p2.publisher.UpdateSitePublisher) is a headless application that is capable of generating metadata (p2 repositories) from an update site containing a site.xml, bundles and features. The application can be invoked as follows:

java -jar <targetProductFolder>/plugins/org.eclipse.equinox.launcher_*.jar -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

Features And Bundles Publisher Application

The Features and Bundles Publisher Application (org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher) is a headless application that is capable of generating metadata (p2 repositories) from pre-built Eclipse bundles and features. The application can be invoked as follows:

java -jar <targetProductFolder>/plugins/org.eclipse.equinox.launcher_*.jar -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

In this example, the plugins in /<location with a plugin and feature directory>/plugins and features in /<location with a plugin and feature directory>/features will be published in the file:/<some location>/repository repository. The artifacts will also be published, and the repositories (artifacts.xml and content.xml) compressed.

Product Publisher

The Product Publisher Application (org.eclipse.equinox.p2.publisher.ProductPublisher) is a headless application that is capable of generating product configuration metadata. The product publisher does not publish the bundles or features that constitute the product. The application can be invoked as follows:

-console -consolelog -application org.eclipse.equinox.p2.publisher.ProductPublisher -metadataRepository file:/home/irbull/Desktop/temp/mail1 -artifactRepository file:/home/irbull/Desktop/temp/mail1 -productFile /home/irbull/workspaces/p2/mail/mail.product -append -publishArtifacts -executables /home/irbull/eclipse/delta/eclipse/features/org.eclipse.equinox.executable_3.3.200.v20090426-1530-7M-Fm-FI3UouOdcoUJz-7oc -flavor tooling -configs gtk.linux.x86 -pluginVersionsAdvice finalPluginVersions.properties -featureVersionsAdvice finalFeaturesVersions.properties

Note: There are currently a few oustanding (but workable) issues with this application:

You must list any bundles to start on the configuration tab.
Any features / bundles should be specified with "Exact" versions (no qualifiers) or 0.0.0 for latest
The executables feature must be specified
Flavor must be specified (if unsure, use tooling)
Unchecking "Include native launchers" has no effect

Note: "-configs <spec>" specifies the environment properties, supported by this product. If the product is not platform-specific, "-configs ANY" or "-configs ANY.ANY.ANY" (all variants of the "ANY" string literal with small or capital letters can be used) should be passed as an option. One immediate effect in this case, for example, is that the start configuration of bundles, specified in the product definition, will be applied on provisioning on any platform.

Category Publisher

The Category Publisher Application (org.eclipse.equinox.p2.publisher.CategoryPublisher) is a headless application that is capable of categorizing a set of Installable Units in a given repository. The categorization is driven from a category file. The application can be invoked as follows:

-console -consolelog -application org.eclipse.equinox.p2.publisher.CategoryPublisher -metadataRepository file:/<repo location>/repository -categoryDefinition file:/home/irbull/workspaces/p2/mail/category.xml -categoryQualifier -compress

This application will use the categories defined in category.xml to categorize the metadata in file:/<repo location>/repository with the categories defined in category.xml. This command will compress the repository. PDE offers an editor for creating the category.xml file; See File -> New -> Plug-in Development -> Category Definition.

Parameters

Third column specifies which application support the parameter (U=UpdateSite Publisher, FAB=FeaturesAndBundles Publisher, P=Product Publisher, C=Category Publisher).

-pluginVersionsAdvice <file>	specifies a file from which plugin version advice should be read	?
-featureVersionsAdvice <file>	specifies a file from which feature version advice should be read	?
-metadataRepository <url>	location of the metadata repository to write	all
-artifactRepository <url>	location of the artifact repository to write	all
-source <dir(?)>	<location with a site.xml (U) or with features and plugins dirs (FAB) >	U
-configs <specs>	a triplet of environment properties for os, ws and arch, or ANY to support all platforms	U, FAB, P
-compress	create compressed jars rather than plain xml	all?
-publishArtifacts	option is unclear, artifacts are always published?	U, FAB, P ?
-append	append artifacts to an existing repository	?
-executables <dir>	The location of the executables feature. This is the feature that is used for branding and publishing the executable	P
-flavor <spec>	"if unsure, use tooling"	P ?
-categoryDefinition <url>	specifies a file containing category definitions	C
-categoryQualifier	specifies the id of the category	C
-contextMetadata	specifies context metadata (e.g. repository used as basis for category publisher)	C, ?
-reusePack200Files	if the -publishArtifacts option is also set: include .pack.gz files	FAB, ??

Ant Tasks

The publisher consists of two ant tasks for creating metadata. The first ant task (p2.publish.featuresAndBundles) is used to create metadata from pre-build bundles and features, while the second task (p2.publish.product) is used to create metadata from a .product file.

Default Attributes

The p2.publish.* ant tasks outlined below all support the following attributes:

metadataRepository A URL specifying the metadata repository to publish to.

artifactRepository A URL specifying the artifact repository to publish to.

repository Sets both metadataRepository and artifactRepository.

metadataRepositoryName When creating a new metadata repository, sets the name.

artifactRepositoryName When creating a new artifact repository, sets the name.

repositoryName Sets both metadataRepositoryName and artifactRepositoryName.

append Whether to append to the repository. (Default is "true")

compress When creating a new repository, whether or not to compress the metadata. (Default is "false")

publishArtifacts Whether or not to publish the artifacts. (Default is "true")

reusePackedFiles Whether or not to include discovered Pack200 files in the repository. (Default is "false")

<contextRepository>

Nested elements specifying context repositories, supports the following attributes:

`location`	A URL specifying the location of the repository.
`artifact`	"true" or "false": whether or not there is an artifact repository at this location.
`metadata`	"true" or "false": whether or not there is a metadata repository at this location.

If a given context repository contains metadata for one of the features or bundles that are being published, then that metadata will be re-used instead of generating new metadata.

Features and Bundles Publisher Task

The Features and Bundles Publisher Task (p2.publish.featuresAndBundles) is an ant task that is capable of generating metadata (p2 repositories) from pre-build Eclipse bundles and features. Here is an example of how the ant task can be used:

  <p2.publish.featuresAndBundles
    metadataRepository="file:/repository/location"
    artifactRepository="file:/repository/location"
    publishArtifacts="true"
    compress="true"
    source="/bundles/and/features/location/">

In addition to the default arguments, the feature and bundles task supports the following:

`source`	A folder containing plugins and features subfolders to publish.
`<features>`	A nested fileset element specifying the locations of binary features to publish.
`<bundles>`	A nested fileset element specifying the locations of binary plug-ins to publish.

Product Publisher Task

The Product Publisher Task (p2.publish.product) is an ant task that is capable of generating product configuration metadata. The product publisher does not publish the bundles or features that constitute the product. Here is an example of how the ant task can be used:

  <p2.publish.product
    metadataRepository="file:/repository/location"
    artifactRepository="file:/repository/location"
    publishArtifacts="true"
    compress="true"
    flavor="tooling"
    executables="/delta/pack/location/eclipse/features/org.eclipse.equinox.executable_3.3.200.v20090507-7M-Fm-FI3UouOdgtbIvrva"
    productFile="/product/file/location/sample.product">
        <config ws="gtk" os="linux" arch="x86" />
  </p2.publish.product>

In addition to the default arguments, the product publishing task supports the following:

`flavor`	Set the flavor for the p2 metadata, default is "tooling". Products should consider using a unique flavor if they have special requirements for bundle start levels.
`productFile`	The location of the .product file describing the product.
`executables`	The location of the executables feature. This is the feature that is used for branding and publishing the executable
`<config>`	Nested elements specifying configurations supported by this product. Config elements specify ws, os & arch: `<config ws="gtk" os="linux" arch="x86" />` Use `<config ws="ANY" os="ANY" arch="ANY"/>` if the product can support any platform.
`<advice>`	Nested elements specifying specifying additional advice to use when creating the product. Currently the accepted kinds of advice are "featureVersions" and "pluginVersions". `<advice kind="featureVersions" file="finalFeaturesVersions.properties" /> <advice kind="pluginVersions" file="finalPluginsVersions.properties" />` PDE/Build will generate these version properties files when the builder sets the property <a href="pde_version_qualifiers.htm#final_versions">`generateVersionsLists`"</a>.

PDE Build

PDE/Build has built in support for publishing p2 metadata using the p2 Publisher.

The new publisher integration gathers your features and bundles from source and publishes them directly to a p2 repository. To use the new functionality, the builder should define the property:

p2.gathering = true

Setting this property will change the build in a significant manner:

Feature builds produce a single p2 repository that is a group of all the configurations being built.
Product builds produce a properly installed fully enabled p2 product. (And optionally the corresponding repository.)

During the build, all metadata and artifacts will be published into a build repository defined by the property p2.build.repo. The default location for this repository is ${buildDirectory}/buildRepo.

Once all the metadata and artifacts are published into this repository, the final assemble and packaging scripts will mirror and/or install from this repository into the locations that will become the archives produced by the build. This final mirroring and installation can be skipped using skipMirroring and skipDirector properties, in which case the build results would all just be in the build repository.

Feature Builds

Defining the new property: p2.gathering = true will cause a few changes for feature builds. In particular, the build will (optionally) produce a single p2 repository which is a group of all the platforms. (By default, PDE/Build outputs a p2 repository as part of the feature build.)

The following is a list of related properties:

`p2.gathering`	Set to `true` to turn on p2 publisher based builds.
`p2.build.repo`	The local build time p2 repository, default is `${buildDirectory}/buildRepo`. Results will be mirrored from here to the final archive location.
`groupConfigurations`	`p2.gathering=true` has the implicit effect of setting `groupConfigurations=true`. To control the <a href="pde_controlling_output.htm">output format</a> of the archive use the `group.group.group` configuration.
`p2.metadata.repo p2.artifact.repo`	These properties were associated with `generate.p2.metadata` and have no affect on feature builds when `p2.gathering=true` because the default behaviour in this case is to create a p2 repository. (However, these properties do affect <a href="pde_p2_productbuilds.htm">product builds</a>).
`p2.metadata.repo.name p2.artifact.repo.name`	Optional, these properties will be used to name the final feature repository.
`p2.compress`	Set to `true` to compress the final feature repository xml into a jar.
`p2.context.repos`	Define context repositories.
`repoBaseLocation`	A folder containing repositories to transform using p2.repo2runnable.
`transformedRepoLocation`	The folder containing the output of p2_repo2runnable.
`p2.category.site`	A URL to a site.xml file used to define categories.
`p2.category.definition`	A URL to a category.xml file used to define categories.
`p2.category.prefix`	Define a prefix to ensure unique ids for category IUs generated from site/category files that don't use unique names.
`skipMirroring`	Skip the mirroring step, no final archive is created. Build results are found in `${p2.build.repo}`.

Product Builds

Defining the new property: p2.gathering = true will cause a few changes for product builds. In particular, the build will produce a properly installed, fully p2 enabled, product. A p2 repository can also be (optionally) produced as an output of the build. (By default, PDE/Build does not output a p2 repository as part of the product build.)

The following is a list of related properties.

`p2.gathering`	Set to `true` to turn on p2 publisher based builds.
`p2.build.repo`	The local build time p2 repository, default is `${buildDirectory}/buildRepo`. Results will be mirrored from here to the final archive location.
`p2.metadata.repo p2.artifact.repo`	By default for product builds, the final archives are the installed products and metadata and artifacts are left in the `${p2.build.repo}`. If `p2.metadata.repo` and `p2.artifact.repo` are defined, then the artifacts and metadata for the product will be mirrored from the build repository.
`p2.metadata.repo.name p2.artifact.repo.name`	Optional, these properties will be used to name the final repository when `p2.metadata.repo` and `p2.artifact.repo` are used.
`p2.compress`	Set to `true` to compress the final repository xml into a jar.
`p2.flavor`	The flavor of the product, used as a qualifier on the configuration metadata for the product. If unsure, use tooling.
`p2.product.qualifier`	The qualifier to use when replacing "1.0.0.qualifier" in a product's version. If not set, the qualifier will be based on `forceContextQualifier` or the timestamp.
`p2.context.repos`	Define context repositories.
`repoBaseLocation`	A folder containing repositories to transform using p2.repo2runnable.
`transformedRepoLocation`	The folder containing the output of p2_repo2runnable.
`p2.category.site`	A URL to a site.xml file used to define categories.
`p2.category.definition`	A URL to a category.xml file used to define categories.
`p2.category.prefix`	Define a prefix to ensure unique ids for category IUs generated from site/category files that don't use unique names.
`skipMirroring`	Skip the final mirroring from `${p2.build.repo}` to `${p2.metadata.repo}`.
`skipDirector`	Skip the call to the director. No installed products will be produced. If `p2.metadata.repo` and `p2.artifact.repo` are defined, those repositories will contain the product metadata and artifacts, otherwise `${p2.build.repo}` will contain the results.
`p2.director.log`	Location of a log file to log the results of the director call.
`p2.director.profile`	The name to use for the p2 profile created by the director. Generally it is a good idea to name this something related to your product. Default is "profile".
`p2.director.extraArgs`	Extra arguments to pass to the directory. Default is "`-profileProperties org.eclipse.update.install.features=true`".

Extensible API

The p2 Publisher can invoked programatically using its extensible API. (The publisher API is currently provisional and subject to change)

The publisher is structured as a series of actions and advice. The publisher can be invoked as follows:

 IPublisherInfo publisherInfo = ...;
 IPublisherAction[] actions = ...;
 Publisher publisher = new Publisher( publisherInfo );
 publisher.publish( actions, progressMonitor );

Publisher Info

The publisher info provides a context to use when publishing. The publisher info object describes such things as:

The metadata repository where the IUs should be published
The artifact repository where the artifacts should be published
Artifact publishing options (overwrite existing artifacts, etc...)

Publisher Actions

There are a number of pre-defined actions for publishing well known constructs. The following table describes some of the available actions.

BundlesAction	Publish IUs for all of the bundles in a given set of locations or described by a set of bundle descriptions.
FeaturesAction	Publish IUs for all of the features in the given set of locations.
SiteXMLAction	ction which processes a site.xml and generates categories.

In addition to the provided actions, additional actions can be created by extending AbstractPublisherAction.

Example

The following example shows a custom publisher that publishes bundles.

 package org.example.publisher;
 
 import java.io.File;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.util.Collections;
 
 import org.eclipse.core.runtime.NullProgressMonitor;
 import org.eclipse.equinox.app.IApplication;
 import org.eclipse.equinox.app.IApplicationContext;
 import org.eclipse.equinox.internal.p2.artifact.repository.ArtifactRepositoryManager;
 import org.eclipse.equinox.internal.p2.metadata.repository.MetadataRepositoryManager;
 import org.eclipse.equinox.internal.provisional.p2.artifact.repository.IArtifactRepository;
 import org.eclipse.equinox.internal.provisional.p2.core.ProvisionException;
 import org.eclipse.equinox.internal.provisional.p2.metadata.repository.IMetadataRepository;
 import org.eclipse.equinox.internal.provisional.spi.p2.artifact.repository.SimpleArtifactRepositoryFactory;
 import org.eclipse.equinox.internal.provisional.spi.p2.metadata.repository.SimpleMetadataRepositoryFactory;
 import org.eclipse.equinox.p2.publisher.IPublisherAction;
 import org.eclipse.equinox.p2.publisher.IPublisherInfo;
 import org.eclipse.equinox.p2.publisher.Publisher;
 import org.eclipse.equinox.p2.publisher.PublisherInfo;
 import org.eclipse.equinox.p2.publisher.eclipse.BundlesAction;
 
 /**
  * This simple publisher example demonstrates how to use the publisher
  * API to publish a directory of bundles.
  * @throws URISyntaxException 
  * @throws ProvisionException 
  */
 public class PublisherExample implements IApplication {  
 
	public Object start(IApplicationContext context) throws Exception {
		IPublisherInfo info = createPublisherInfo();
		IPublisherAction[] actions = createActions();
		Publisher publisher = new Publisher(info);
		publisher.publish(actions, new NullProgressMonitor());
		return null;
	}
 
	public void stop() {
 
	}
 
	public static IPublisherInfo createPublisherInfo() throws ProvisionException, URISyntaxException {
		PublisherInfo result = new PublisherInfo();
 
		// Create the metadata repository.  This will fail if a repository already exists here
		IMetadataRepository metadataRepository = new SimpleMetadataRepositoryFactory().create(new URI("file:/location to/repository"), "Sample Metadata Repository", MetadataRepositoryManager.TYPE_SIMPLE_REPOSITORY, Collections.EMPTY_MAP);
 
		// Create the artifact repository.  This will fail if a repository already exists here
		IArtifactRepository artifactRepository = new SimpleArtifactRepositoryFactory().create(new URI("file:/location to/repository"), "Sample Artifact Repository", ArtifactRepositoryManager.TYPE_SIMPLE_REPOSITORY, Collections.EMPTY_MAP);
 
		result.setMetadataRepository(metadataRepository);
		result.setArtifactRepository(artifactRepository);
		result.setArtifactOptions(IPublisherInfo.A_PUBLISH | IPublisherInfo.A_INDEX);
		return result;
	}
 
 
	public static IPublisherAction[] createActions() {
		IPublisherAction[] result = new IPublisherAction[1];
		File[] bundleLocations = new File[1];
		bundleLocations[0] =  new File("/location to bundles/");
		BundlesAction bundlesAction = new BundlesAction(bundleLocations);
		result[0] = bundlesAction;
		return result;
	}
 }

Getting Involved

There are a number of ways to get involved with the development of The Publisher. In particular:

Experiment with and give feedback on the publisher's provisional API
Ensure the publisher Java Docs are accurate (and provide feedback / patches where needed)
Experiment with the publisher's ANT tasks and headless applications
Review the list of outstanding publisher bugs Open Publisher Bugs

The publisher developer discusses take place on the p2-dev list

Category:

Equinox p2

Retrieved from "https://wiki.eclipse.org/index.php?title=Equinox/p2/Publisher&oldid=420870"

Breadcrumbs

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Contents

Publisher Actions

BundlesAction

ProductAction

Headless Applications

UpdateSite Publisher Application

Features And Bundles Publisher Application

Product Publisher

Category Publisher

Parameters

Ant Tasks

Default Attributes

Features and Bundles Publisher Task

Product Publisher Task

PDE Build

Feature Builds

Product Builds

Extensible API

Publisher Info

Publisher Actions

Example

Getting Involved