Apache Ant Demystified - Parts 1 and 2

One of the principles of good software engineering is the daily build. If you build your software every day then it acts as a barometer, showing the state of the project. If something's broken, it gets noticed faster, so it gets fixed faster. The daily build becomes the heartbeat of the project. These are the reasons why Microsoft builds the five gigabytes of Windows source code every day, even though it takes twelve hours -- on very powerful and expensive servers -- to do so.

As you might imagine, in order to be able to perform daily builds, the build process has to be automatic and repeatable. It's no good to rely on some harangued colleague typing a complicated command in a Command Prompt window to invoke the Java compiler with a classpath as long as this article. What's needed is Another Neat Tool in the developer's armoury. What's needed is Apache Ant.

Part 1 of this tutorial starts below.

Part 2 of the tutorial starts here.

About Ant

Ant is an open-source Java-based build tool from the Apache Software Foundation. It's rapidly become the de-facto build tool for J2EE projects, so for developers, it's certainly worth becoming familiar with the basics of Ant, at the very least. Many modern Java development environments also feature Ant support.

Ant uses build files, which are simply XML files that tell the Ant program what to do. And because Ant is a Java program, it's a cross-platform tool; you can move your build files from one operating system to another unchanged, providing you haven't used any platform-specific features.

Although Ant is a build tool, don't think that it's only good for compiling Java code. Its name is apt; think of all the heavy loads a line of ants can carry on their backs. Ant is a veritable Swiss army knife of functionality. For example, it's entirely feasible to use Ant to get the latest code from your source code repository, compile that code, run the unit tests and generate a report with the results, generate the Javadoc documentation, package the code into a J2EE application, deploy that application to an application server ...and then send yourself an email when that's all done. Phew! Ant can do all of that in response to a single command from you if you want it to. Not bad, eh? Make no mistake: being able to write and maintain Ant build files is a very useful skill for any Java developer to possess.

Obtain and Install Ant

Ant can be downloaded from the Downloads page of the Apache Ant Website. Like all Apache downloads, it's available in both binary (pre-compiled) and source code form. I recommend that you download the binary distribution, at least to start with.

Locate the file that you downloaded, which will be named something like apache-ant-1.6.2-bin.zip. At the time of writing, 1.6.2 is the latest version of Ant. There is no installer program with Ant, so all you need to do is unzip the download to the directory in which you want to install the software, for example, C:\Program Files. If you use WinZip to extract the files from the Zip file, make sure that the Use Folder Names option is checked so that the Ant installation folder structure is preserved.

Before we can get started with Ant, we need to modify the system path so that Ant can be started from any Command Prompt, irrespective of what the current directory is on the file system. We also need to add some system-wide environment variables that Ant needs if it is to operate correctly. The following instructions are for Windows XP; users of other operating systems should consult their documentation to find out how to modify the system path, and add and edit environment variables.

Right-click on the My Computer icon and select Properties. Then click the Advanced tab and select the Environment Variables button. Depending upon whether you're the administrator of the computer or not, you can either add the Ant installation folder to the global path -- which affects all users -- or to the path for just your user account. If the New, Edit and Delete buttons are greyed out in the System Variables group, then you don't have permissions to modify the global path and can only set Ant up for your own user account. Don't worry, it will still work perfectly well. Let's assume that you're going to do just that.

If you haven't already got a user variable named Path, click the New button and set the Variable Name to Path and the Variable Value to the full path to the bin folder in the Ant installation, for example, C:\Program Files\Apache Group\apache-ant-1.6.2\bin, then click OK. If you already have a Path user variable, highlight it in the list, then click the Edit button. Add a semi-colon to the end of the existing path, then add the full path to the bin folder as described above. You might end up with a path looking vaguely like this: C:\Program Files\WidgetWare\Widget; C:\Program Files\Apache Group\apache-ant-1.6.2\bin

Click OK when you've finished making the edit.

The next step is to set up a new environment variable called ANT_HOME. While you're still within the Environment Variables dialogue, click the New button in the User variables group and create a new variable with a name of ANT_HOME and a value that corresponds to the Ant installation folder. For example, C:\Program Files\apache-ant-1.6.2 Note that there's no \bin on the end this time. Click OK.

Finally, we need to set up another new environment variable: one that will tell Ant where your Java Development Kit (JDK) is installed. Follow the procedure described above for the ANT_HOME environment variable, but this time, set the Variable name to JAVA_HOME and the Variable value to the location at which your JDK is installed. On my machine it's C:\Program Files\Java\jdk1.5.0, but yours may be different. Now click OK several times to close all the open dialogues and property sheets.

You can confirm that these steps have been successful by opening a Command Prompt and entering set ant_home followed by Enter, and then set java_home followed by Enter. The respective paths that you entered in the steps above should be displayed. If this doesn't work, try logging off and back on again.

We also need to verify that Ant is installed correctly and ready to go. In the same Command Prompt window, type ant –version followed by Enter. If all is well, then Ant should respond by telling you which version it is and when it was compiled. If this is the case then we're ready to start learning more about Ant and to write our first build file!

Good Things Come In Threes: Projects, Targets And Tasks

The three basic concepts in Ant are the project, targets and tasks. Actually, there are also properties, but who ever heard of good things coming in fours? The concepts are really simple: each Ant build file contains one and only one project, and that project must contain at least one target, but will usually contain more. Also, each target contains tasks. Let's take a look at the project part of all that by diving right in and starting to write a build file.

Use a text editor to create a new file named build.xml and save it somewhere. You can use Notepad for this task, or you can use a fancy syntax-highlighting editor -- it really doesn't matter. Type or paste in the following:

<?xml version="1.0" encoding="UTF-8"?>
<project name="helloworld" default="compile" basedir=".">
 <description>
   Build file for the Hello World application.
 </description>
</project>

The first line is simply a standard declaration that says that this is an XML 1.0 document that uses the UTF-8 character encoding. You might have come across this line, or something similar, before. Ant doesn't actually require this to be present, but it's a good idea to include it because Ant build files are XML documents and valid XML documents must start with this declaration.

Next, there's a project tag with a name attribute. This is simply a name that we want to give the project; in this case, it's the spectacularly unimaginative "helloworld". The project's name is used when we call Ant build files from other Ant build files, which we don't need to worry about for now.

The default attribute tells Ant which target to execute when no specific target is supplied on the command line. More about that later.

Finally, the basedir attribute is the path to the directory that Ant should use when working out paths. More often than not, it will be set to . (a single period), which is Windows and UNIX shorthand for referring to the same directory that the file itself is in. In other words, if you saved your build.xml file in C:\SitePoint Tutorials\Ant, then the basedir attribute would have the value C:\SitePoint Tutorials\Ant; when Ant works out any relative paths later, it uses that as a starting point.

Nested within the project tag is a description tag. This is where you can provide a more detailed description of the project that will get output if the person using the build file requests help on the build file.