Home » Reference » PDE related tasks & macros

<buildPlugin>

May 26, 2009 by Gerd Wuetherich
Scope: PDE Projects

Description

This macro builds an eclipse plug-in project. It reads the information from the MANIFEST and the build.properties file and builds the plugin according to these settings.

Important: This task is implemented as an Ant macro. To use this task, you have to import the file 'a4e-pde-macros.xml' in your build file.

Arguments

The buildPlugin task provides the following arguments:

Argument Description Required
workspaceDirectory Absolute path of the workspace directory Either 'workspaceDirectory' or 'workspaceId' has to be specified
workspaceId The identifier of a defined workspace (see <workspaceDefinition>) Either 'workspaceDirectory' or 'workspaceId' has to be specified
projectName Name of the eclipse project Either projectName or featureId (and optional featureVersion) has to be set
targetPlatformId The id of the target platform. yes
platformConfigurationId The id of the platform configuration (for cross platform builds). no
destination Name of the directory that will contain the plugin after building (same as the 'Destination directory' in the PDE-Export wizard in Eclipse). The plugin will be built in to <destination>/plugins/<Bundle-SymbolicName>_<Bundle-Version>.jar. yes
packageAsJar If set to true the plugin will be packaged as a jar file. Otherwise it will be an exploded directory. no (default: true)
buildSourceJar If set to true an additional source plugin will be created for the specified plugin project. no (default: true)
defaultCompilerOptionsFile Absolute path to an eclipsed compiler options file that is used as the default compiler options file if no project specific file exists. no
newBundleVersion If the newBundleVersion attribute is set, the resulting bundles has this version instead of the one definied in the plug-in project's manifest. no
clean Indicates that the output folder of the plugin project should be cleaned prior building. no (default: true)
useEcj Enables or disables the use of the ecj compiler as the backend. no, default to true

Lifecycle hooks

To allow the user of ant4eclipse to add additional build steps to the plug-in build, the buildPlugin macro defines the following lifecycle hooks that are implement as macro elements.

Build phase Description Required
validate Validate the project is correct and all necessary information is available. no
initialize Initialize build state, e.g. set properties or create directories. no
generate-sources Generate any source code for inclusion in compilation. no
generate-resources Generate resources for inclusion in the package. no
pre-compile Execute additional steps before compilation. Note: This lifecycle hook is only available if the executed plug-in project is a java project. no
post-compile Post-process the generated files from compilation, for example to do bytecode enhancement on Java classes. Note: This lifecycle hook is only available if the executed plug-in project is a java project. no
pre-package-library Execute additonal steps before packaging a library. no
post-package-library Execute additonal steps after packaging a library. no
prepare-package Copy the final package from the destination to aremote repository or whatever. no
deploy Perform any operations necessary to prepare a package before the actual packaging. no

Scoped properties

The following scoped properties are available within the lifecycle hooks:

Property Description Build phase
buildPlugin.project.name The name of the project All phases
buildPlugin.project.directory Absolute path of the project directory All phases
buildPlugin.<project nature name> true (this property is set for each project nature the project contains) All phases
buildPlugin.boot.classpath The boot class path of the used JRE. pre-compile, post-compile
buildPlugin.classpath.relative.runtime The runtime class path of the JDT project, relative to the workspace location. pre-compile, post-compile
buildPlugin.classpath.absolute.runtime The absolute runtime class path of the JDT project. pre-compile, post-compile
buildPlugin.classpath.relative.compiletime The compile time class path of the JDT project, relative to the workspace location. pre-compile, post-compile
buildPlugin.classpath.absolute.compiletime The absolute compile time class path of the JDT project. pre-compile, post-compile
buildPlugin.default.output.directory The absolute path of the default ouput directory. pre-compile, post-compile
buildPlugin.default.output.directory.name The name of the default ouput directory. pre-compile, post-compile
buildPlugin.source.directories The source directories (only set if the project contains source directories) pre-compile, post-compile

Scoped references

The following scoped references are available:

Reference Description Build phase
buildPlugin.project.directory.path The project directory as an ant path All phases
buildPlugin.boot.classpath.path The boot class path of the used JRE. pre-compile, post-compile
buildPlugin.classpath.relative.runtime.path The runtime class path of the JDT project, relative to the workspace location. pre-compile, post-compile
buildPlugin.classpath.absolute.runtime.path The absolute runtime class path of the JDT project. pre-compile, post-compile
buildPlugin.classpath.relative.compiletime.path The compile time class path of the JDT project, relative to the workspace location. pre-compile, post-compile
buildPlugin.classpath.absolute.compiletime.path The absolute compile time class path of the JDT project. pre-compile, post-compile
buildPlugin.default.output.directory.path The absolute path of the default ouput directory. pre-compile, post-compile
buildPlugin.source.directories.path The source directories (only set if the project contains source directories) pre-compile, post-compile

Example usage

The following example builds the plug-in project with the project name 'example-bundle'. The built bundle will reside in 'd:/plugins/plugins'.

<buildPlugin workspace="${workspace}"
             projectName="example-bundle"
             targetPlatformId="target.platform"
             destination="d:/plugins" />

The next example shows how to add additional build steps to the build process.
<buildPlugin workspace="${workspace}"
             projectName="example-bundle"
             targetPlatformId="target.platform"
             destination="d:/plugins" >
 
  <generate-sources>
    <!-- add additional build steps here... -->
  </generate-sources>
 
  <post-compile>
    <!-- add additional build steps here... -->
  </post-compile>
 
</buildPlugin>