Customizing a Headless Build
There are multiple methods for customizing a headless build:
The exact format of the contents of these files all depend on each other. Therefore, when using customTargets, allElements or customAssembly customizations, it is recommended to ensure that the templates used for these files all come from the same version of PDE/Build. New versions of PDE/Build are backward compatible with old versions of these customization scripts.
Template versions of these scripts are available in the org.eclipse.pde.build plug-in under the templates/headless-build folder. To use the customization, simply copy the template into your build configuration directory and edit the appropriate targets.
The customTargets.xml script is for top level customization of the build process. It provides ant targets that are called between the major phases of the build. There are pre and post targets available around each of the following build steps:
- Process p2 repositories
- Get Map files
- Fetch source
- Generate build scripts
- Process and run the build scripts
- Assemble the compiled plug-ins and features
- Package pre-compiled binary plug-ins and features
To use the customTargets.xml script, simply copy it from the PDE/Build templates directory into your build configuration directory and edit the appropriate ant targets. The script will be automatically detected and used by the headless build.
The customTargets.xml script also provides delegation to the allElements.xml script for each of the build phases.
allElements.xml
The allElements.xml script is a kind of delegation script that is used to run the various build steps on a given element (usually a feature). As with the customTargets.xml, to use these customization steps, copy the template from PDE/Build into your build configuration directory. In Eclipse 3.4, the target element that will be built can be specified in the top level build configuration build.properties file using the properties topLevelElementType and topLevelElementId. The elementType should be set to feature and the elementId should be set to the feature-id you wish to build.
<target name="allElementsDelegator">
<ant antfile="${genericTargets}" target="${target}">
<property name="type" value="${topLevelElementType}" />
<property name="id" value="${topLevelElementId}" />
</ant>
</target>
The allElements.xml also provides targets used during the assembly and packaging phase of the build. The defaultAssemble target will be called to assemble the archives for all platforms. If desired, custom targets can be defined for individual platforms.
To use a custom target for a given platform, define a property "assemble.<element-id>[.<config>] and a corresponding target. The property tells PDE/Build to use this custom target instead of the default target. This custom target can then be used to give the archive a custom name or perform pre or post processing on the archive.
Example:
<property name="assemble.org.foo.feature.id.linux.gtk.x86" value="true" />
<target name="assemble.org.foo.feature.id.linux.gtk.x86">
<property name="archiveName" value="acme-RCP-${buildId}-linux.gtk.x86.tar.gz" />
<-- custom pre assemble steps for linux.gtk.x86-->
<ant antfile="${assembleScriptName}" dir="${buildDirectory}"/>
<-- custom post assemble steps for linux.gtk.x86-->
</target>
customAssembly.xml
The customAssembly.xml script is new in 3.4. It provides customization points that will be called during the assembly and packaging phases of the build. As with customTargets.xml and allElements.xml, to use these customization, copy the template from PDE/Build into your build configuration directory.
The assemble and packaging scripts generated by PDE/Build perform the following actions:
- Call the gather.bin.parts target in the generated build.xml for all features and plug-ins being built.
- Jar up (and optionally sign) any plug-ins and features that are not shipped as folders
- Copy the final results into a staging area and create the final archive
The assemble scripts deal with collecting the features and plug-ins that were compiled during the build and the package scripts deal with collecting any pre-compiled binary features and plug-ins. The customAssembly.xml script provides the following targets before or after each of the above steps:
- gather.bin.parts: Called after each invocation of the gather.bin.parts target on the individual plug-ins and features.
- post.gather.bin.parts: Called after invoking the gather.bin.parts targets for all plug-ins and features. Results exist as folders and have not yet been jarred.
- pre.jarsigning: Called just prior to signing a jar.
- post.jarup: Called after all plug-ins and features have been jarred (and potentially signed).
- pre.archive: Called just before the archive file is built
