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 function 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 from 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 MapFile Format
below).
-
contentFilter : A comma
separated list of content type 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
downdloading 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 independant.
-
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 "&" seperated 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 independant 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.
