Fetching from Repositories

The infrastructure offered by PDE Build provides steps to fetch the source code and pre-built plug-ins from a repository as part of the build process (see the eclipse.fetch task and the properties to control fetching). Two possibilities are available: let PDE build automatically fetch the source, or fetch the source code manually.

First step to automation, the map file

Given the identifier of a feature or a plug-in that needs to be built, the build infrastructure is able to fetch from a repository all the included features and plug-ins.

In order to know where to get things from, PDE uses map files. A map file is a java property file which maps feature and plug-in ids to a location and a tag in a repository. The format of map files is open and but the key part is fixed by PDE Build:

<elementType>@<elementID>[,<elementVersion>] = <repo specific content>

where elementType is one of bundle, feature, plugin or fragment, and elementId and elementVersion give the specifics of the element.

Map file entry for CVS

The format of a map file entry to fetch content from CVS is the following:
<key> = CVS, [,args]
where args is a comma-separated list of key/value pairs described below: Example:
plugin@com.ibm.icu,3.6.1=CVS,tag=v200704191630,cvsRoot=:pserver:anonymous@dev.eclipse.org:/cvsroot/tools,path=org.eclipse.orbit/com.ibm.icu/bin,prebuilt=true

Old style Map Entries
In Eclipse 3.2 and earlier, the map file format for CVS was:
<elementType>@<elementID> = CVS, <TAG>, <CVSROOT>[,<PASSWORD>[,<PATH>[,<CVSPASSFILE>]]]
If any of the optional arguments aren't specified, then the commas are still required to delimit any following arguments. This format should be considered deprecated and the key/value format is prefered.

Map file entry for Ant GET

The format of a map file entry to fetch content from any URL supported by Ant GET is the following:

<key> = GET, <url> [,args]
where url is the url to retrieve the data from and args is an optional comma-separated list of key/value pairs described below: Example:
plugin@com.ibm.icu,3.4.5=GET,http://download.eclipse.org/tools/orbit/downloads/drops/S200705301823/bundles/com.ibm.icu_3.4.5.jar, unpack=true

Map file entry for a p2 fetch

A new extension has been added to PDE/Build that enables users to fetch artifacts from p2 repositories. You can now add an entry to your map file for build input and PDE/Build will retrieve the artifact and include it in the build. The map file entry needs to include the id and version of the installable unit (IU), and the URI of the repository where the IU can be found. The metadata and artifact repositories are assumed to be co-located.

The format of a map file entry to fetch content via p2 is as follows:

<elementType>@<elementID> = p2IU, id=<id>, version=<version>, repository=<repository>
Fetching features with p2

In the Helios release, features can be fetched with p2 by specifying the Installable Unit representing the feature jar. See the feature metadata page for details on the structure of p2 metadata for features.

Examples:
plugin@my.bundle.id,1.0.0=p2IU,id=my.bundle.id,version=1.0.0,repository=http://example.eclipse.org/repo
feature@my.feature.id = p2IU,id=my.feature.id.feature.jar, version=1.0.0,repository=http://example.eclipse.org/repo

Map file entry for other repositories

PDE Build provides an extension point where fetch script generators for different repositories can be plugged in. When your eclipse install contains a bundle that provides a script generator extension for a different type of repository, you can use that repository by specifying it in your map file entries and adhering to the format specified by the extension provider.

Setting up for CVS source fetching

To set up fetching your source from CVS, you should do the following:

Getting the map files from CVS

Map files are usually stored in a repository. PDE Build offers default infrastructure to get those map files from a CVS repository. To enable this function change the following properties in your configuration's build.properties from your configuration directory: Fetching the map files from CVS occurs during the Pre-Build phase of the build.  Scripts to fetch all the features and plug-ins included in the feature you are building will be generated and run during the fetch phase of the build. 

Automatic fetching from other repositories

If  you are automatically fetching your map files from the repository, you will need to copy the customTarget.xml file from org.eclipse.pde.build/templates/headless-build into your configuration directory.  The target  getMapFiles is used to fetch the map files, this should be modified to fetch from your repository.

Getting source code manually

You can write custom fetch targets to retrieve your plug-ins and features which can be invoked from the preSetup or postSetup targets in the customTargets.xml file.  Features and plug-ins should be fetched to ${buildDirectory}/features and ${buildDirectory}/plugins respectively.