Generating Ant scripts

Ant is a simple open-source scripting engine that is capable of running scripts written in XML format. Ant is ideal for executing tasks usually found in automated builds. 

The variables set in the plug-in, fragment or feature build.properties will be used to generate scripts for Ant.  PDE generates Ant scripts for creating individual plug-in and fragment build files and one overall script for building the feature JAR. This "main" script is also responsible for running individual script files in the right order (defined by the plug-in dependency chain). Each build file has the same name (build.xml) and is created as a sibling of the manifest files in the corresponding projects.

Since Ant scripts use the replacement variables in build.properties, you can typically use them "as is", without modifying the generated scripts. If you do modify them, you must not recreate the scripts every time you want to rebuild the component.

To create scripts, you can simply select Create Ant Build File while a suitable manifest file (plugin.xml, fragment.xml or feature.xml) is selected in the Navigator or Package Explorer views. The command will generate the build script. After selecting Run Ant... from the pop-up menu while the newly generated script file is selected, the following wizard will open:

The standard Ant wizard allows customization in two ways: by providing the execution arguments and by selecting one or more build targets.

Properties

Ant arguments are typically used to provide property values that override default values and control the build process. Arguments are set using "-Dproperty=value". The following properties are recognized:

• bootclasspath - if set, it replaces the default boot classpath. Used when compiling cross-platform plug-ins (e.g. building a UI plug-in for Windows using Linux)

• build.result.folder - where the temporary files for the update JAR creation should be placed. These files are usually the plug-in library JARs.
• plugin.destination - where plug-in and fragment update JARs should be put. These JARs represent entire plug-ins and fragments in a format suitable for publishing on an Install/Update server and referencing by a feature. The typical layout of an Update site is to have all the plug-in and fragment JARs in one place and all the features in another. This argument is useful for placing plug-ins and fragment directly into the desired directory (or the staging place on the local machine before pushing the features onto the remote server).
• feature.destination - where feature update JARs should be put.

To adapt the behavior of the compiler, the following properties are recognized:

• javacFailOnError - stop the build when an error occurs when set to true. Default is false.
• javacDebugInfo - compile source with debug information when set to true. Default is true.
• javacVerbose - produce verbose output when set to true. Default is true.
• javacSource - value of the -source command-line switch.
• javacTarget - generate class files for specific VM version.
• compilerArg - additional command line arguments for the compiler.

Targets

When executing feature build scripts, the following targets are used to call individual targets of plug-ins or fragments. In order to specify what target to execute, the property target should be set (e.g. -Dtarget=refresh). One of the all.* targets serves as an iterator, whereas the actual target to execute is specified via the property target.

• all.plugins - for all listed plug-ins
• all.fragments - for all listed fragments
• all.children - for all listed plug-ins and fragments
• build.jars - build JARs for all feature children;
• build.sources - build source for all feature children;
• build.update.jar - generate a feature JAR in the format used by the install/update mechanism. The above mentioned property feature.destination can be used to define where to put the JAR;
• zip.distribution - creates a zip file with the feature and its plug-ins and fragments in an SDK-like structure but does not include source code;
• zip.sources - creates a zip file with the feature and its plug-ins and fragments in an SDK-like structure which only includes the source;
• clean - delete everything produced by running any of the target;
• refresh - performs a "Refresh" action in the current project, thus making the newly generated resources visible in the Navigator or Package Explorer.
• zip.plugin - creates a zip file with the binary and source contents of a plug-in with the following structure:

  id_version/
      contents

  where 'id' is the plug-in unique identifier and 'version' is the plug-in version. This zip file can be directly unzipped into the Eclipse installation directory as a form of a quick manual deployment.