ANT Description

The Ant Build File

Ant is driven by a build file that describes the projects, dependencies, and tasks required to build your application. The build file is written in XML and, as such, is in a humanreadable format. The Ant build file normally resides in the project's base build directory or folder. By default, Ant looks for a file called build.xml in the current directory, reads, parses, and then executes the contents. Most builds follow a similar pattern as we've outlined in Figure 16.2:

Figure 16.2. The Ant build process.

Ant will access the source control repository to extract the latest source code, clean or prepare the target folders, compile, and then deploy to some kind of staging area for functional tests. In our example, a step to run a suite of automated unit tests is also included, the output of which we could report via XML to the project Web site.

The build file has many XML elements, but the most important are the project, target, and task elements. Each build will have one project element that, in turn, has many possible targets such as debug, release, and test builds. The target is created by a series of tasks that describe the actions to take. The task, then, is where the actual work takes place. Examples of tasks are operating system–level commands such as make directory or delete file. Perhaps the easiest way to learn about the structure of the build file is by looking at an example file. Listing 16.4 shows the basic layout of the build file: 

Listing 16.4 The Ant Build File Layout

<project name="test" default="all">

    <property name="a.property" value="a value"/>

    <target name="all">

       <javac srcdir=".">

       </javac>

    </target>

</project>

The build file example will compile all the Java source files in the current directory (as denoted by .). All build files require one <project> element and at least one <target> element. Our project is called test, and the default target is all.

Projects

The project tag is the top-level attribute in the build file and describes the project itself. The project tag has three attributes: name, default, and basedir, see Table 16.2.

Table 16.2. Project Tag Attributes

Attribute	Description
name	The name of the project.
default	The default target to use when no target is supplied.
basedir	The base directory from which all path calculations are done. This attribute might be overridden by setting the basedir property beforehand. When this is done, it must be omitted in the project tag. If neither the attribute nor the property has been set, the parent directory of the build file will be used.

Targets

The target tag defines a collection of Ant tasks and can depend on other targets. You might have a target for compiling, for example, and a target for creating a distributable. You can only build a distributable when you have compiled first, so the distribute target depends on the compile target. Ant resolves these dependencies.

It should be noted that Ant's depends attribute only specifies the order in which targets should be executed. Ant tries to execute the targets in the depends attribute in the order they appear (from left to right). A target gets executed only once, even when more than one target depends on it.

A target also has the capability to perform its execution if (or unless) a property has been set. This allows, for example, better control on the building process depending on the state of the system (Java version, operating system, command-line property defines, and so on). To make a target aware of this property, you should add the if (or unless) attribute with the name of the property that the target should react to. For example:

<target name="build-module-A" if="module-A-present"/>

<target name="build-own-fake-module-A" unless="module-A-present"/>

The target will always be executed, if no if or unless attribute is present. The optional description attribute can be used to provide a one-line description of this target, which is printed by the -projecthelp command-line option.

It is a good practice to place your tstamp (timestamp) tasks in a so-called initialization target on which all other targets depend. Make sure that target is always the first one in the depends list of the other targets. Table 16.3 lists the target attribute for us.

Table 16.3. Target Tag Attributes

Attribute	Description
name	The name of the target.
depends	A comma-separated list of names of targets on which this target depends.
if	The name of the property that must be set for this target to execute.
unless	The name of the property that must not be set for this target to execute.
description	A short description of this target's function.

Tasks

A task is a piece of code that can be executed. A task can have multiple attributes or arguments. The value of an attribute might contain references to a property. These references will be resolved before the task is executed.

Tasks have a common structure:

<name attribute1="value1" attribute2="value2" ... />

Where name is the identifier of the task, and where the attribute (as many as you like from 1–N) are paired with a value (from 1–N). As in the previous example, attribute1 is the name of the attribute and value1 is the value associated with attribute1; similarly for attribute2. There is a set of built-in tasks, along with a number of optional tasks; it's also very easy to write your own. All tasks share a task name attribute, and Ant will use the value for the logging of any messages generated by the build.

Tasks can be assigned an id attribute, as well:

<taskname id="taskID" ... />

Where taskname is the name of the task, and taskID is a unique name for this task. You can refer to the corresponding task object in scripts or other tasks via this name.

Properties

A project can have a set of properties. These might be set in the build file by the property task, or might be set outside Ant. A property has a name and a value. Properties can be used in the value of task attributes. This is done by placing the property name between "${" and "}" in the attribute value. For example, if there is a builddir property with the value build, this could be used in an attribute like this: ${builddir}/classes. This is resolved as build/classes.

Ant provides access to all system properties as if they had been defined using a <property> task. For example, ${os.name} expands to the name of the operating system. In addition to the user-defined or system properties, Ant has some built-in properties, which are listed in Table 16.4:

Table 16.4. Project Tag Attributes

Property	Description
basedir	The absolute path of the project's basedir (as set with the basedir attribute of <project>).
ant.file	The absolute path of the build file.
ant.version	The version of Ant.
ant.project.name	The name of the project that is currently executing; it is set in the name attribute of <project>.
ant.java.version	The JVM version Ant detected; currently it can hold the values 1.1, 1.2, 1.3, and 1.4.

Now you should have a good understanding about how to run Ant and the structure of the build file. We'll put it all together in the next section and complete a simple sample build.