Building features
PDE Build comes with infrastructure to automate the build of features.
Most of the setup necessary
for such a build can be done through a few modifications to the
template build.properties provided
in PDE build. The following section focuses on setting up a simple
build assuming that all plug-ins
and features (both to-build and pre-built) referenced from the feature
being built are already
locally available on disk.
Basic Setup
The first step in setting up a build is to create the directory in
which the build will take
place. This directory will be referred to as the build directory
and will contain the
plug-ins and features to build as well as all the generated artifacts.
Next, copy your plug-ins and
features respectively into "plugins" and "features" subdirectories.
The feature folder is expected to contain the feature being built.
The second step in setting up a build is to copy the template
build.properties file from
org.eclipse.pde.build/templates/headless-build to a new directory which
will be the build
configuration directory (also referred to as the configuration
directory). Edit the copied build.properties file and set the
following properties:
- baseLocation: the location of an
eclipse install containing all the pre-built features and plug-ins in
features/ and plugins/ subdirectories.
- baseos: indicate the os of the
eclipse specified by baseLocation.
- basews: indicate the ws of the
eclipse specified by baseLocation.
- basearch: indicate the arch of the
eclipse specified by baseLocation.
- buildDirectory:
the directory the build will take place in. Set this to the full
path of the build directory created previously.
- configs: list the
configurations for which you want your feature to be built. You can
uncomment the configuration(s) provided (be careful of the line
continuations). If the feature you are building is platform
independent, this property does not need to be set or can be set
to *,*,*.
- archivePrefix:
the name of the directory in which your feature will be unzipped on disk.
Controlling what will be built: allElements.xml
Copy the allElements.xml file from
org.eclipse.pde.build/templates/headless-build to your configuration
directory. This is the file that tells PDE which feature
you are building. This
file contains two kinds of targets: the allElementsDelegator
which specifies the feature being built, and
the assemble targets which are called to assemble individual
configurations. The
allElementsDelegator for a feature named org.foo.Feature
is:
<target name="allElementsDelegator">
<ant antfile="${genericTargets}" target="${target}">
<property name="type" value="feature" />
<property name="id" value="org.foo.Feature" />
</ant>
</target>
The assemble targets allow you to control the name of the final archive
on a per configuration
basis. You should have one target for each configuration you are
building. For example,
when building
org.foo.Feature
for windows (when configs is set to win32, win32, x86) you should have the following target:
<!--Target for assembling os=win32, ws=win32, arch=x86 -->
<target name="assemble.org.foo.Feature.win32.win32.x86">
<ant antfile="${assembleScriptName}" dir="${buildDirectory}/">
</target>
When building a platform independent configuration (when configs is not set or is set to *,*,*), you should a target like the following:
<!--The platform independent assemble target-->
<target name="assemble.org.foo.Feature">
<ant antfile="${assembleScriptName}" dir="${buildDirectory}"/>
</target>
Running the build
To run the build you will use the org.elipse.ant.core.antRunner
application. When invoking eclipse
with this application to perform a build you need to set two arguments
on the command line:
-buildfile=</path/to/build.xml>
: This is
the path to the build.xml provided by pde build. It is located in
the org.eclipse.pde.build/scripts directory. This is the build
file that drives the whole build process.
-Dbuilder=</path/to/configuration folder>
:
This is the path to the build configuration folder.
Run the antRunner application using the following command:
java -jar
<eclipseInstall>/startup.jar
-application org.eclipse.ant.core.antRunner -buildfile
<<eclipseInstall>/plugins/org.eclipse.pde.build_<version>/scripts/build.xml>
-Dbuilder=<path to the build configuration folder>
Once the build is complete, you can get the result in the build
directory in the folder named I.TestBuild (this name can be configured
by setting the buildLabel property).
Advanced scenarios
If you require more customization of the build, ie
fetching from a repository, see the Advanced
PDE Build topics for
more information.