Feature and Plug-in custom build steps

New in 3.2 is the ability for a feature or plug-in to contribute custom ant targets to its own build.  These custom steps can be used for things like instrumenting byte-code after compilation, indexing help files for documentation, or copying extra files into the bundle. 

To use custom targets, a feature or plug-in must define the property customBuildCallbacks in its build.properties file; the value of this property is the location of an xml file, relative to the root of the feature/plug-in, containing the custom targets. If the xml file is located elsewhere, use the property customBuildCallbacks.buildpath to set the directory to use.

Templates named customBuildCallbacks.xml containing the supported custom targets are provided in org.eclipse.pde.build/templates/plugins and  org.eclipse.pde.build/templates/features.  These templates can be copied into your feature/plug-in and modified as needed.

The custom targets will be invoked using the subant task; by default, failonerror is set to false. To change this set the property customBuildCallbacks.failonerror to true. Similarly, the inheritall parameter defaults to false. Set the property customBuildCallbacks.inheritall to change this.

Plug-ins

The generated build.xml that builds a plug-in contains several targets that perform specific tasks.  PDE Build allows the plug-in to provide custom pre and post targets that will be called before and after specific tasks.  In addition to any ant properties that may already be defined, each custom target may also be passed a couple of specific properties.  The following targets support custom callbacks:

• build.jars:  The build.jars target will invoke in turn each of the compilation targets that will be built for this bundle.  It supports pre.build.jars and post.build.jars targets which are called before and after all the compilation targets are called.  Both the pre and post targets are provided with the property build.result.folder which is the folder to which the results of the build will be copied.
• Compilation Targets:  The build.xml defines a compilation target for each jar being built (eg @dot for the bundle itself, or library.jar).  Each compilation target supports 3 custom callbacks:
  • pre.<compilation target>:  Called before source files are compiled.  It is provided with the following properties:
    • target.folder:  The folder where the compiled class files will be placed
    • source.folder<N>:  The source folder(s) containing the source to be compiled.  (e.g. source.folder1, source.folder2, etc).
    • <compilation target>.classpath:  A reference to the ant path structure containing the classpath that will be used in the compilation.  (e.g. @dot.classpath, library.jar.classpath). The reference to the classpath should be used with a refid.
      Example:

      <classpath refid="library.jar.classpath"/>
      <property name="mypath" refid="library.jar.classpath" />
      

  • post.compile.<compilation target>:  Called after the source is compiled, but before the class files are jared or copied into the build result folder.  It is provided with the same properties as the pre.<compilation target> target.
  • post.<compilation target>:  Called at the end of the compilation target after the results are copied to the build result folder.  It is provided with the following properties:
    • jar.Location:  The jar or folder containing the compilation results.
    • <compilation target>.classpath:  A reference to the ant path structure containing the classpath that was used in the compilation.
• build.sources:  This target builds the source zips for each of the compilation targets.  It supports pre.build.sources and post.build.sources targets.  Both of these targets are provided with the property build.result.folder which is the folder to which the source zip files will be copied.
• gather.bin.parts:  This target copies the build results (i.e. the jars and any other files being included in the bundle) to the final destination directory.  It is also the target where the version qualifiers are replaced in the manifest file (see Version Qualifiers). It supports pre.gather.bin.parts and post.gather.bin.parts targets.  Two properties are provided to the pre and post targets:
  • build.result.folder:  the folder containing the results of the build
  • target.folder:  the destination folder to which the build results and bundle contents are being copied.
• gather.sources: This target gathers the source zips for the bundle.  It supports pre.gather.sources and post.gather.sources targets.  Both the pre and post targets are provided with the target.folder property which is the folder that the sources are being copied to.
  
• gather.logs:  This target collects the log files from the build.  It supports pre.gather.logs and post.gather.logs.  Both the pre and post targets are provided with the destination.temp.folder which is the temporary folder that the logs files are being copied to.
  
• clean:  This target performs a clean, it supports pre.clean and post.clean targets.  The pre and post targets have the following properties:
  • plugin.destination:  The folder that the final bundle was copied to.
    
  • build.result.folder:  The folder that the results of the build were copied to
  • temp.folder:  The temporary folder where the results were staged before being copied to the final destination.
    

Features

The generated build.xml for features only supports custom build callbacks for the gather.bin.parts target.  This target will invoke the gather.bin.parts target of all the included features and plug-ins.  It supports pre.gather.bin.parts and post.gather.bin.parts.  Both of these targets are provided with the following properties:

• destination.temp.folder:  The directory to which the plug-ins will be copied.
• feature.directory:  The directory to which the files for this feature will be copied.