Ant: The Definitive Guide

Running Ant

We are going to assume that Ant is installed properly. If you have any doubts on this point, now is the time to read Chapter 2 and get everything up and running.

Examples

To execute the tasks in the default target, compile, type the following command from the directory containing our sample build.xml file:

 ant

Ant will open the default buildfile, which is build.xml, and execute that buildfile’s default target (which in our case is compile). You should see the following output, assuming your directory is called antbook:

Buildfile: build.xml

prepare:
    [mkdir] Created dir: C:\antbook\build
    [mkdir] Created dir: C:\antbook\build\classes
    [mkdir] Created dir: C:\antbook\build\lib

compile:
    [javac] Compiling 3 source files to C:\antbook\build\classes

BUILD SUCCESSFUL

Total time: 5 seconds

As Ant runs, it displays the name of each target executed. As our example output shows, Ant executes prepare followed by compile. This is because compile is the default target, which has a dependency on the prepare target. Ant prints the name of each task within brackets, along with other messages unique to each task.

Tip

In our sample output, [javac] is the name of the Ant task, not necessarily the name of the Java compiler. If you are using IBM’s Jikes, for instance, [javac] is still displayed because that is the Ant task that is running Jikes behind the scenes.

When you invoke Ant without specifying a buildfile name, Ant searches for a file named build.xml in the current working directory. You aren’t limited to this default; you can use any name you like for the buildfile. For example, if we call our buildfile proj.xml, we must type this command, instead:

ant -buildfile proj.xml

We can also explicitly specify one or more targets to run. We can type ant clean to remove all generated code, for instance. If our buildfile is called proj.xml, and we want to execute the clean target, we type ant -buildfile proj.xml clean. Our output would look something like this:

Buildfile: proj.xml

clean:
   [delete] Deleting directory C:\antbook\build

BUILD SUCCESSFUL

Total time: 2 seconds

We can also execute several targets with a single command:

ant clean jar

This invokes the clean target followed by the jar target. Because of the target dependencies in our example buildfile, Ant executes the following targets in order: clean, prepare, compile, jar. The all target takes advantage of these dependencies, allowing us to clean and rebuild everything by typing ant all:

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

all is dependent on clean and jar. jar, in turn, is dependent on compile, and compile is dependent on prepare. The simple command ant all ends up executing all our targets, and in the proper order.

Getting Help

You may have noticed that some of our targets include the description attribute, while others do not. This is because Ant distinguishes between main targets and subtargets. Targets containing descriptions are main targets, and those without are considered subtargets. Other than documentation differences, main targets and subtargets behave identically. Typing ant -projecthelp from our project base directory produces the following output:

Buildfile: build.xml
Default target:

 compile  Compiles all source code.

Main targets:

 all      Cleans, compiles, then builds the JAR file.
 clean    Removes all generated files.
 compile  Compiles all source code.
 jar      Generates oreilly.jar in the 'dist' directory.

Subtargets:

 prepare


BUILD SUCCESSFUL

Total time: 2 seconds

This project help feature is particularly useful for large projects containing dozens of targets, provided you take the time to add meaningful descriptions.

For a summary of the Ant command-line syntax, type ant -help. You will see a brief description of Ant’s command-line arguments, which we cover next.