Ant: The Definitive Guide

The Ant Buildfile

Ant buildfiles are written using XML. Example 1-1 shows the complete Ant buildfile for our example. This is simpler than most real-world buildfiles, but does illustrate several core concepts required by nearly every Java project.

Example 1-1. build.xml

<?xml version="1.0"?>

<!-- build.xml - a simple Ant buildfile -->
<project name="Simple Buildfile" default="compile" basedir=".">

  <!-- The directory containing source code -->
  <property name="src.dir" value="src"/>

  <!-- Temporary build directories -->
  <property name="build.dir" value="build"/>
  <property name="build.classes" value="${build.dir}/classes"/>
  <property name="build.lib" value="${build.dir}/lib"/>

  <!-- Target to create the build directories prior to the -->
  <!-- compile target. -->
  <target name="prepare">
    <mkdir dir="${build.dir}"/>
    <mkdir dir="${build.classes}"/>
    <mkdir dir="${build.lib}"/>
  </target>

  <target name="clean" description="Removes all generated files.">
    <delete dir="${build.dir}"/>
  </target>

  <target name="compile" depends="prepare"
          description="Compiles all source code.">
    <javac srcdir="${src.dir}" destdir="${build.classes}"/>
  </target>

  <target name="jar" depends="compile"
          description="Generates oreilly.jar in the 'dist' directory.">
    <!-- Exclude unit tests from the final JAR file -->
    <jar jarfile="${build.lib}/oreilly.jar" 
         basedir="${build.classes}"
         excludes="**/*Test.class"/>
  </target>

  <target name="all" depends="clean,jar"
          description="Cleans, compiles, then builds the JAR file."/>

</project>

XML Considerations

Ant buildfiles are XML files that can be created with any text editor. Keep the following points in mind as you create your own buildfiles:

• The first line is the XML declaration. If present, it must be the very first line in the XML file; no preceding blank lines are allowed. In fact, even a single blank space before <?xml causes the XML parser to fail.

• XML is very picky about capitalization, quotes, and proper tag syntax. If any of these items are incorrect, Ant fails because its underlying XML parser fails.

Here is an example of an error that occurs if the </project> end tag is typed incorrectly as </Project>:

Buildfile: build.xml

BUILD FAILED

C:\antbook\build.xml:41: Expected "</project>" to terminate
element starting on line 4.

Total time: 2 seconds

Buildfile Description

Our buildfile consists of several XML comments, the required <project> element, and many properties, tasks, and targets. The <project> element establishes the working directory for our project: “.”. This is the directory containing the buildfile. It also specifies the default target, which is “compile.” The purpose of the default target will become apparent shortly when we describe how to run Ant.

The property definitions allow us to avoid hardcoding directory names throughout the buildfile. These paths are always relative to the base directory specified by the <project> element. For example, the following tag sets the name of our source directory:

<property name="src.dir" value="src"/>

Next, our buildfile defines several targets. Each target has a name, such as “prepare,” “clean,” or “compile.” Developers interact with these when invoking Ant from the command line. Each target defines zero or more dependencies, along with an optional description attribute. Dependencies specify targets that Ant must execute first, before the target in question is executed. For example, “prepare” must execute before “compile” does. The description attribute provides a human-readable description of a target that Ant will display on command.

Within targets we have tasks, which do the actual work of the build. Ant 1.4.1 ships with over 100 core and optional tasks; you can find all of the tasks described in detail in Chapter 7 and Chapter 8. These tasks perform functions ranging from creating directories to playing music when the build finishes.^[4]

---

^[4] See the sound task in Chapter 8.