Ant tasks for managing repositories

Several p2 tasks accept "source" repositories. Source repositories can be specified in several different ways:

A source attribute directly on the ant task. The value is a URL to a location that contains both a metadata and artifact repository. For example:
<p2.mirror source="https://download.eclipse.org/releases/helios" .... />
A <source> element nested in the ant task. This element is an ant fileset, with additional location and kind attributes.
- location : A URL specifying the location of a repository. If this attribute is set, all fileset based attributes are ignored.
- kind: Either "metadata" or "artifact". If not set, the repository is both metadata and artifacts.
If no location attribute is set, all directories matched by the fileset are added as repositories and all *.zip files are treated as zipped repositories (accessed using a jar: URL). For example:
```
<source kind="metatata" dir="/build/input" includes="*.zip" />
<source location="https://download.eclipse.org/releases/helios" />
```

A <source> element containing a list of repositories. Each nested element is again a fileset with an additional kind attribute. For example:

<source>
   <repository location="https://download.eclipse.org/releases/helios" />
   <repository kind="metadata" file="/build/repos/cdt-master-6.0.0-I200903161435.zip" />
   <repository kind="artifact" dir="/build/repos" includes="*repo" />
</source>

Specifying destination repositories

Several p2 tasks accept "destination" repositories. Destination repositories can be specified in several different ways:

A destination attribute directly on the ant task. The value is a URL to a location for both a metadata and artifact repository.

A <repository> element nested in the ant task. (<destination> may also be used.) This element supports the following attributes:

`location`	A URL to the location of the repository
`kind`	Either "`metadata`" or "`artifact`". Default is both if not specified.
`name`	A name to give the repository if the repository does not already exist.
`append`	Append to a repository that is already there. (Default is "true")
`compressed`	Whether to compress the content/artifact xml into a jar (Default is "true")
`format`	A URL to another repository from which to copy the repository name and other properties.

Specifying Installable Units

Some p2 tasks allow specifying installable units to work with. This is done with nested <iu> elements which support the following attributes:

`id`	The id of the IU to match.
`version`	The version of the IU to match. If not specified, the highest versioned IU is returned. (requires id to be set)
`query`	Matches all IUs satisfying the query. Currently only "property" queries are supported. The format of the query attribute is intended to be "xpath-like". Eg: `<iu query="property[@name='org.eclipse.equinox.p2.type.category']" />` `<iu query="property[@name='my.property.name' @value='specialValue']" />`

Ant Tasks

p2.mirror

This task mirrors artifacts and metadata from the given source repositories to the destination. This task will traverse the source repository and recursively include all IUs that match the requirements of IUs being mirrored (this is called slicing the repository).

This task supports the following attributes and elements:

source Source repositories, as outlined above

destination Destination repositories, as outlined above

<iu> Nested IU elements, as outlined above. The installable units to mirror. If none are specified, all IUs contained in the source repositories are mirrored.

log A file to use for logging the results.

ignoreErrors Whether or not to ignore errors. (Default is false)

raw Copy the exact artifact descriptors from source into the destination instead of initializing new artifact descriptors with properties from the source descriptors. (Default is true)

verbose Turn on verbose logging.

validate Validate that all all source descriptors are present in the destination after mirroring is complete. (Default is false)

references Enables or disables the mirroring of references. (Default value is true).

<comparator>

A nested comparator element for comparing against a baseline repository. If IUs from the source repository already exist in the baseline, then the artifacts will be mirrored from the baseline instead of the source. This element supports the following attributes:

<baseline> A nested element specifying the baseline repository. See destination repositories above.

<exclude>

A nested element specifying artifacts to exclude from the comparison. Contains nested <artifact> elements which support the following attributes:

`id`	The artifact id.
`classifier`	The artifact classifier
`version`	The version to exclude.
`range;`	A range of versions to exclude
`<property>`	Nested <property> elements specifying properties that the artifact descriptor must have.

Example: Exclude all pack.gz artifacts:

    <exclude>

       <artifact>
          <property name="format" value="packed" />
       </artifact>
    </exclude>

Exclude the specified documentation bundles:

    <exclude>

       <artifact id="org.eclipse.jdt.doc.isv" classifier="osgi.bundle" />
       <artifact id="org.eclipse.jdt.doc.usr" classifier="osgi.bundle" />
       <artifact id="org.eclipse.pde.doc.isv" classifier="osgi.bundle" />
    </exclude>

comparator

Id of a comparator to use if the baseline artifacts should be compared against the source artifacts. These are extensions to the org.eclipse.equinox.p2.artifact.repository.artifactComparators extension point. Comparators provided by p2 are:

org.eclipse.equinox.p2.repository.tools.jar.comparator: Compare jars. Class files are disassembled and compared for equivalence, properties and manifest files are compared as such, all other files are compared byte-for-byte.
org.eclipse.equinox.artifact.md5.comparator: Compare the MD5 sums as recorded in the artifact repositories.

comparatorLog A log file for the results of the comparison.

<slicingOptions>

A nested element for specifying how to slice the repositories to bring in additional IUs. This element supports the following attributes:

`followStrict`	Set to true if only strict dependencies should be followed. A strict dependency is defined by a version range only including one version (e.g. [1.0.0.v2009, 1.0.0.v2009]). (Default is false)
`includeOptional`	Whether or not to follow optional requirements. (Default is true).
`includeNonGreedy`	Whether or not to follow non-greedy requirements. (Default is true).
`includeFeatures`	Whether or not to include features. (Default is true).
`platformFilter`	An "os,ws,arch" triplet to set as the platform against which IU LDAP filters will be matched. IUs not matching the filter will not be mirrored.
`filter`	Set additional filter properties. Format is a comma separated list of "key=value" pairs.
`followOnlyFilteredRequirements`	Invert the filters, include only the IUs that don't match.
`latestVersionOnly`	Set to "true" to filter the resulting set of IUs to only included the latest version of each Installable Unit. By default, all versions satisfying dependencies are included.

Examples:

Creating a delta pack repository based on the contents of the platform, rcp, jdt and equinox.executable features:

 <p2.mirror source="file://${buildRepo}">
    <destination kind="metadata" location="file://${deltaTemp}" name="RCP Delta Pack Repo"  />
    <destination kind="artifact" location="file://${deltaTemp}" name="RCP Delta Pack Repo"  />
    <iu id="org.eclipse.platform.feature.group" version="" />

    <iu id="org.eclipse.rcp.feature.group" version="" />
    <iu id="org.eclipse.jdt.feature.group" version="" />
    <iu id="org.eclipse.equinox.executable" version="" />
    <slicingOptions includeOptional="false" includeNonGreedy="false" followStrict="true" followOnlyFilteredRequirements="true" />
 </p2.mirror>

Mirror the org.eclipse.equinox.p2.user.ui feature and other required bundles locally (perhaps in preparation for a build).

 <p2.mirror source="https://download.eclipse.org/releases/helios" destination="${p2Repo}">
    <slicingOptions followStrict="true" />
    <iu id="org.eclipse.equinox.p2.user.ui.feature.group" />
    <iu id="org.eclipse.ecf"/>

    <iu id="org.eclipse.ecf.filetransfer"/>
    <iu id="org.eclipse.ecf.identity"/>
    <iu id="org.eclipse.ecf.provider.filetransfer"/>
    <iu id="org.eclipse.ecf.provider.filetransfer.httpclient"/>
    <iu id="org.eclipse.ecf.provider.filetransfer.httpclient.ssl" />
    <iu id="org.eclipse.ecf.provider.filetransfer.ssl"/>

    <iu id="org.eclipse.ecf.ssl" />
    <iu id="org.apache.commons.codec"/>
    <iu id="org.apache.commons.httpclient"/>
    <iu id="org.apache.ant"/>
    <iu id="org.eclipse.core.runtime.compatibility.registry"/>
 </p2.mirror>

Mirror the results of a build into a public location, and compare against the existing update site to ensure that artifacts haven't changed if their versions haven't been updated.

 <p2.mirror source="file:${buildRepo}" ignoreErrors="true" log="${buildlogs}/mirrorlog.txt">
    <destination compressed="true" name="${p2.repo.name}" location="file:${updateRepo}" append="true" />
    <comparator comparator="org.eclipse.equinox.p2.repository.tools.jar.comparator" comparatorLog="${buildlogs}/comparatorlog.txt">

       <repository location="file:${updateSite}" />
    </comparator>
 </p2.mirror>

p2.repo2runnable

Transform IUs into their installed form and add them to the destination repository. This allows compiling against folder shaped bundles that contain nested jars. This task is the main mechanism by which headless PDE/Builds can reuse metadata.

This task supports the following attributes and elements:

`source`	Source repositories, as outlined above
`desination`	Destination repositories, as outlined above
`failOnError`	Default is true. Set to "false" to ignore errors and complete the operation.
`<iu>`	Nested IU elements, as outlined above. The installable units to transform. If none are specified, all IUs contained in the source repositories are transformed.

p2.process.artifacts

Process a local, file-based artifact repository. This task will (optionally) sign and pack artifacts, as well as update the MD5 sums in the repository to match the actual artifacts on disk (since signing/conditioning will change the MD5 sums). This task will use the jarProcessor, which in turn uses ant's SignJar task which requires the jarsigner command line tool.

This task supports the following attributes and elements:

repositoryPath A URL to an artifact repository to process. This must be a local, file-based repository.

pack Whether or not to create pack.gz artifacts. (Default is false)

normalize Whether or not to do pack200(pack + unpack) conditioning on the artifacts. (Default is false, however sign + pack will imply a normalize.)

<sign>

A nested element to enable signing. This element supports the following attributes:

`alias`	The alias to sign with
`keystore`	The location of the keystore.
`keypass`	Password for the private key (if different).
`storepass`	Password for the key store.
`unsign`	Whether or not to strip any existing signatures before signing. (Default is false)

<feature> Nested elements specifying features IUs to process (see above, the query attribute is not supported here). If no features or plug-ins are specified, the entire repository is processed.

<plugin> Nested elements specifying plugins IUs to process (see above, the query attribute is not supported here). If no features or plug-ins are specified, the entire repository is processed.

p2.remove.iu

Remove Installable Units from the given metadata and artifact repositories. The provided repositories must be modifiable.

This task supports the following attributes and elements:

`<repository>`	Nested elements specifying metadata and artifact repositories to remove Installable Units from. See destination repositories above. A metadata repository is required, the artifact repository is optional.
`<iu>`	Nested IU elements, as outlined above. The installable units to remove. Matching IUs are removed from the metadata repository, and all associated artifacts are removed from the artifact repository (if provided).

p2.composite.repository

Create a composite repository

This task supports the following attributes and elements:

`failOnExists`	Whether we should fail if the repository already exists. (Default is false)
`validate`	A comparator-id. Child repositories claiming to contain the same artifact are compared using the given comparator. These are extensions to the org.eclipse.equinox.p2.artifact.repository.artifactComparators extension point. Comparators provided by p2 are: org.eclipse.equinox.p2.repository.tools.jar.comparator: Compare jars. Class files are disassembled and compared for equivalence, properties and manifest files are compared as such, all other files are compared byte-for-byte. org.eclipse.equinox.artifact.md5.comparator: Compare the MD5 sums as recorded in the artifact repositories.
`<add>`	A nested element containing a list of repositories to add to the composite. See source repositories above.
`<remove>`	A nested element containing a list repositories to remove from the composite. See source repositories above.