Chapter 16. The Apache Ant Build Files

Table of Contents

16.1. The Abuild-ant.properties File
16.2. Directory Structure For Java Builds
16.3. The Abuild-ant.xml File

Warning

Note that abuild's Java support is considered alpha as of version 1.0. Version 1.1 of abuild may include a Java solution that is not backward compatible with the solution in version 1.0.

There are two different Java build files: Abuild-ant.properties for property-driven builds, and Abuild-ant.xml for build.xml-driven builds.

Note

The goal is and always has been to have property-driven builds be the standard method for building Java code with abuild. By the time of the first abuild release, abuild's property-based ant framework was still not definitely able to handle everything that we might want for the Java Enterprise Environment and full Eclipse build integration. Since Apache Ant is already relatively declarative in nature and is not really designed to be a system with which one would create a general framework, it is less suitable than GNU Make for being the basis of a general-purpose build framework such as what we would want for an abuild backend. At the same time, Apache Ant appears to be the best option for Java as it is already very portable, flexible, written in Java, and widely supported. Introduction of build.xml-based Java build support in abuild is a compromise as it leaves more to the developer than would be desirable, but it allows for greater flexibility in experimenting with alternative Java build approaches. This mechanism for building Java code may disappear in a future major release of abuild, so developers are encouraged to use it only if the property-driven approach is not able to satisfy their requirements.

16.1. The Abuild-ant.properties File

The Abuild-ant.properties file is the build configuration file for Java build items. It serves the same function for Java build items as Abuild.mk serves for platform-independent and C/C++ build items.

Below is a list of supported properties. You can also see this list by running abuild properties-help (or, equivalently, abuild rules-help) from any Java build item.

abuild.application-xml

The name of the application.xml to put into an EAR file. This must be set (along with abuild.ear-name) for an EAR file to be generated.

abuild.ear-name

The name of the EAR file, including the .ear suffix, to be generated. This must be set for an EAR file to be generated. EAR files contain any archive files in the abuild.classpath property. They do not contain JAR files in the abuild.classpath.external property.

abuild.hook-build-items

A comma-separated list of build items from which hooks should be loaded. For details about using hooks, see Chapter 19, Java Hooks and Code Generators.

abuild.jar-name

The name of the JAR file, including the .jar or other archive suffix, to be created by this build item. This must be set in order for a JAR file to be generated.

abuild.java-source-version

If specified, the value of this property will be used for the source attribute of the javac task. Otherwise, the value will come from the abuild.java-target-version if set or from the Java environment used to run ant if not.

abuild.java-target-version

If specified, the value of this property will be used for the target attribute of the javac task. If abuild.java-source-version is not set and this property is, then this property's value will also be used to set the source attribute of the javac task.

abuild.junit.testsuite

This property contains the name of the class that implements this build item's junit test suite. It must be set in order for the test target to attempt to run a junit test suite.

abuild.local-buildfile

The name of a local build file, specified relative to the build item's directory, that will be imported by ant. It may contain additional properties that can't be specified in a property file, resource collections, or even additional targets. If you are using this too often, please consider whether a build item hooks file should be used instead, or whether there is some functionality that is missing from the core abuild ant framework code.

abuild.main-class

The name of a class, if any, that implements main. Setting this property causes the Main-Class attribute to be set in the manifest file. It also influences generation of the wrapper script if abuild.wrapper-name is set.

abuild.use-ant-runtime

If set, ant runtime libraries will be included in the compilation classpath. This can be useful for compiling custom ant tasks.

abuild.use-local-hooks

If this and abuild.local-buildfile are both set, abuild will attempt to run hooks from the local build file as well as from any hook build items.

abuild.war-name

The name of the WAR file, including the .war suffix, to be generated. This must be set for a WAR file to be generated. WAR files contain any JAR files in the abuild.classpath property. They do not contain JAR files in the abuild.classpath.external property.

abuild.war-type

The type of the WAR file, which must be either client or server. This property determines where items in abuild.classpath are copied. For client WAR files, classpath JAR files are copied into the root of the WAR file where the are accessible to clients' browsers. For server WAR files, they are copied into the WEB-INF/lib directory of the WAR file.

abuild.web-xml

The name of the web.xml to put into a WAR file. This must be set (along with abuild.war-name) for a WAR file to be generated.

abuild.wrapper-name

If this property and abuild.main-class are both set, a script by this name will be generated that will invoke the Java runtime environment to invoke this main. The script will include the classpath as determined by abuild. On Windows, the script is usable to invoke the application from a Cygwin environment, and a stand-alone batch file (that does not reference the script or require Cygwin) is generated as well.

Note that at most of one abuild.jar-name, abuild.war-name, or abuild.ear-name may be set for any given build item.