Apache Ant Demystified - Parts 1 and 2

As things stand, this build file isn't very useful. In fact, it's not even valid because we haven't defined any targets. A target is a set of tasks that you want to be executed. You can tell Ant which target(s) you want to be executed and, when no target is given, the project's default target is used. Let's make our build file do something useful and add a target:

<?xml version="1.0" encoding="UTF-8"?>  
<project name="helloworld" default="compile" basedir=".">  
 <description>  
   Build file for the Hello World application.  
 </description>  
 
 <target name="compile" description="Compile all sources.">  
   <mkdir dir="classes" />  
   <javac srcdir="src" destdir="classes" />  
 </target>  
</project>

Here, we've nested a target tag within the project tag and set its name and description attributes. Again, the description gets output if the user of the build file requests help on it. We'll see how to do that later. Two tasks are nested within the target tag: mkdir and javac. Ant comes with more built-in tasks than you can shake a stick at; see the online manual to get an idea. If these aren't enough, you can always extend Ant with optional tasks that others have written. If that's still not enough for you, not only are you pretty demanding, but you can always write your own Ant tasks using Java (naturally).

The mkdir task, as its name suggests, makes a directory. In this case, it makes the classes output directory into which our compiled Java classes will go. Remember that this happens relative to the location specified using the basedir attribute of the project tag. So, using the example from earlier, our mkdir task would create a classes directory directly under C:\SitePoint Tutorials\Ant.

Most Ant build files will use the javac task at some point. As you might have guessed, it's a wrapper around javac.exe -- the Java compiler. In this case, we're using the srcdir attribute to tell it to find Java source code under the src directory, and to output the compiled classes to the classes directory.

Important: Ant is a harsh mistress; if you don't create the classes directory first, the javac task will fail when it attempts to output some files there. That's why we had to use the mkdir task first.

That's it! We've defined our first target and used two built-in Ant tasks. If you have some simple Java source code that doesn't depend on any other libraries on the classpath -- I'm talking about a "Hello World" level of sophistication here -- and that source code is located in the src directory, then this build file will compile the classes into the classes directory. The only part of Ant that's left to learn is how to run the build file! Well, not quite. But let's see how to do it anyway.

Using Ant

As I said earlier, many modern Java IDEs have integrated support for Ant, but before exploring on your own whether yours does, let's learn how to run Ant the way nature intended: from the command line.

Open a Command Prompt at the directory in which your build.xml file is saved. Now type ant –projecthelp, followed by Enter. Ant should display the following information:

Buildfile: build.xml  
 
 Build file for the Hello World application.  
 
Main targets:  
 
compile Compiles all sources.  
Default target: compile

Ant tells us the name of the build file, the project description, and provides a list of the targets within the build file together with their descriptions. Note that if you don't supply a description for a target, then that target won't get listed at all as part of the project help. So unless you're able to look at the source of the build file, you won't even know the target is there.

Ant also tells us what the default target is. In this case, it's the compile target. Notice that we didn't have to tell Ant what our build file was called. Ant is hard-wired to look for a build file named build.xml in whichever directory you happen to be in when you type the ant command. That doesn't mean that you have to call all your build files build.xml; it's just a convenient feature. If you use another name, you should use the –f command line switch to tell Ant what your build file is called. For example, ant –f build_me.xml.

Now, type ant and press Enter. You should see something similiar to the following:

Buildfile: build.xml  
 
compile:  
 [mkdir] Created dir: C:\SitePoint Tutorials\Ant\classes  
 [javac] Compiling 1 source file to C:\SitePoint Tutorials\Ant\classes  
 
BUILD SUCCESSFUL  
Total time: 2 seconds

The above code shows that Ant found build.xml and executed its default target of compile. If you inspect that classes directory, you should find some 100% pure Java in there. Congratulations! You've successfully used Ant to compile some Java code! Ant displays in square brackets the name of each task as it executes, and also helpfully tells us how long the build took. This is a neat feature when your builds take hours and you want to bore people at parties by talking about how insanely complicated your project is.

One last thing to try for now: type ant again and press Enter. You'll see this output:

Buildfile: build.xml  
 
compile:  
 
BUILD SUCCESSFUL  
Total time: 1 second

In this case, Ant didn't do anything! It's intelligent enough to realise that the code was already compiled and didn't need to be compiled again. Ant practises build avoidance. This means that it checks the timestamps of files to determine whether they've changed or not, and only compiles files that have changed, thus reducing build times, often drastically on large projects.