Packaging Eclipse Components

Eclipse components are delivered as archive files. Each archive contains a collection of features and plug-ins. Typically the archives contain all the functions that a particular component has to offer. It is often the case that consumers either need more than one component and/or only need parts of some components. Without assistance, consumers would have to manually fetch the archives containing the superset of the functionality they need and then manually extract the required features and plug-ins. This can be a laborious and error prone process.

Fortunately, PDE contains a batch oriented mechanism, the packager, which can help. In short, the packager takes as input a list of archives containing features and a list of interesting features. It then fetches the zips, extracts the features (and their plug-ins) and repackages them into an output zip.

Quick Start

Below is a set of basic steps to get started with the packager. It is suggested that you build *nix packages on a *nix machine to ensure that file permissions are preserved.

Create a packaging configuration directory and copy the template files (packager.properties, packaging.properties, and customTargets.xml) from org.eclipse.pde.build/templates/packager here.
Edit the copied packager.properties files and set the following properties:
- baseDirectory : the directory in which the actual packaging work will take place.
- featureList : a comma separated list of feature ids that you wish to include in your archive.
- componentFilter : A comma separated list of components in which your features can be found. Specifying this will avoid unnecessary downloads. Use * if you don't know the components. (See the componentName in the Packager Map File Format below).
- contentFilter : A comma separated list of content types you are interested in. Common content types are runtime or sdk. This is used to optimize the downloading of the archives. Leave this blank to not filter on content type. (See the contentDescription in the Packager Map File Format below).
- config : The configurations to package. This is an "&" separated list of comma separated triples of operating system, windowing system and architecture (eg win32,win32,x86 & linux,gtk,ppc)
Get packager map files. The following properties control downloading the map files:
- localMaps : Set this property if you have map files locally, put the map files in ${downloadDirectory} (by default this is ${baseDirectory}/toPackage). Comment out this property to automatically download the map file.
- packagerMapURL : The URL from which to download the map file.
The packager script will concatenate all *.map files found in ${downloadDirectory}. To download more than one map file, or to fetch them from CVS edit the customTargets.xml file and change the getMapFiles target.

Run the packager using the following command:

java -jar <eclipse install>/plugins/org.eclipse.equinox.launcher_<version>.jar -application org.eclipse.ant.core.antRunner 
    -buildfile <<eclipse install>/plugins/org.eclipse.pde.build_<version>/scripts/package.xml> 
    -DpackagingInfo=<path to your packaging configuration directory>

Packager Map File Format

The packager map files are used to describe the various archives, their content and where they can be downloaded from. They are similar to the map files used in the build process to fetch bundles from repositories. The format of a packager map file entry is as follows:

archiveName = url | [configList] | [directory] | contentDescription | componentName

archiveName : This is the name of the archive
url : This is the url where the archive can be found. The concatenation of url and archiveName should point to the archive to download.
configList : This is an "&" separated list of configs that this archive contains. (eg: win32,win32,x86 & linux,gtk,x86). If no value is given the archive is considered to be platform independent.
directory : The directory where the content of the archive should be extracted relative to a standard eclipse installation. When no value is specified it means that the archive contains an eclipse installation directory at its root.
contentDescription : The content flags indicating the type of content in this archive. Normally this is something like runtime, sdk, source, doc, etc.
componentName : The canonical name of the component this archive is for. For example eclipse, jdt, cdt, gef, emf, etc.

Note that configList and directory are optional, it is important that the appropriate number "|" separators are still used.
Examples:

eclipse-SDK-3.1-win32.zip=https://download.eclipse.org/downloads/drops/R-3.1-200506271435/ | win32,win32,x86 | | sdk | eclipse
eclipse-PDE-3.1.zip=https://download.eclipse.org/downloads/drops/R-3.1-200506271435/ | | | runtime | pde

Packager Configuration Properties

The following properties can be set in the packager configuration packager.properties file:

baseDirectory	The directory in which all the packaging will take place
workingDirectory	The directory in which the scripts will be generated. The value in the template is `${baseDirectory}/workingPlace`
downloadDirectory	The folder to which the archives will be downloaded. The value in the template is `${baseDirectory}/toPackage`
tempDirectory	The folder that the archives will be extracted to. The value in the template is `${baseDirectory}/temp`
featurePaths	The name of the root of the archives downloaded. The value in the template is `eclipse`.
featureList	A comma separated list of feature ids that you wish to repackage.
componentFilter	A comma separated list of the components from which the features in featureList can be found. This filters the available archives and allows the packager to optimize the set of files downloaded.
contentFilter	A comma separated list of content types to fetch. This filters the set of available archives and allows the packager to optimize the set of files downloaded.
config	An "&" separated list of configs (comma separated triples of operating system, windowing system, architecture) to repackage. (eg: `win32, win32, x86 & linux, gtk, x86`)
archivesFormat	The formats of the archives. An "&" separated list of config - format. (eg: `win32, win32, x86 - antZip & linux, gtk, ppc - tar`). If no archive format is specified for a given config, the default format is antZip.
zipargs	Extra arguments to be passed to zip
unzipargs	Extra arguments to be passed to unzip
archivePrefix	The prefix of the resulting archive(s)
collectingFolder	The name of the root folder of the resulting archive.
buildId	Controls the build id in the default name of the archive.
buildType	Type of the build, used in naming the build output. Typically one of I, N, M, S, ...
buildLabel	Label for the build. The template value is `${buildType}.${buildId}`
archiveNamePrefix	Control the name of the resulting archive. The default value of this is `${buildId}`
packagingProperties	A relative path to the file containing the properties packaging root files.. By default this points to packaging.properties.
deltaPack	Whether or not to generate a delta pack. This will exclude platform independent pieces and will group all configs into one archive.
unzipOrder	a comma separated list of archive name prefixes setting the order in which archives should be extracted.

Packaging Root Files

In the packager configuration packager.properties file, the property packagingProperties points to a property file which specifies the root files that need to be packaged. By default this is the file packaging.properties.

This property file should contain the properties specifying the required root files. See the Feature specific properties page for details on the root properties.