Apache Ant is a software tool for automating software build processes. It is similar to Make but is implemented using the Java language, requires the Java platform, and is best suited to building Java projects. However, that doesn’t mean it is restricted to Java projects. I use Ant increasingly for all my web development projects as it is an integral part of Eclipse, my IDE of choice. It makes building applications and releasing them across different servers far more efficient and less problematic.

When I start a new project, after creating the folder structure, I create the Ant build file. Ant defines the build process and must be used by every developer working on the project. All of the tips in this article assume that the Ant build file is extremely important, must be written with care, and maintained in version control and re-factored periodically, when the project dependencies change.

Ant uses XML to describe the build process and its dependencies. By default the XML file is named build.xml. This makes it really simple for you setup and edit different build processes. However, since Ant is relatively simple to set up, you need to follow a common set of best practices. Some of these best practices were inspired by mistakes made on previous projects, or ideas passed on to me by other developers.

Automate absolutely everything

Ant is a powerful tool. If you choose to use it, get it to do absolutely everything. Ant can integrate with your source control databases such as Subversion (SVN), run SQL scripts, change file permissions, send files across FTP, zip and un-zip files, and many more tasks besides these.

If you use Ant, only use Ant

Use Ant as a common baseline. Regardless of what IDE you use to develop your applications, set up an Ant build file that all team members use. The build.xml file is the one true build script. Make a rule that everyone should perform a successful Ant build before code is checked into version control. This will ensure that code will always build from the same build file.

Follow consistent conventions

Ant expects your build file to be called build.xml and the build’s properties file build.properties. These files should also be in the root directory of your project. Other than an insane desire to change convention and confuse other team members, don’t change this convention. Another less-well-known convention is to prefix all internal commands with a hyphen (-). It has the advantage that it is not possible to invoke targets that follow this naming convention, from the command line.

Spend time formatting the build file. Since XML is quite verbose, use tabs and line breaks to make the file readable to the human eye. Ant itself doesn’t care if the file looks pretty, but you can bet that you and your team will.

Pick meaningful, human-readable names for targets and properties. For example dir.reports is better than simple rpt. The specific naming convention is not important, beyond being meaningful to your organisation. For example, I use the following:

deploy.local
deploy.dev
deploy.test
deploy.live
-build
-clean
-concatenate
-minify
-prepare

The -concatenate and -minify commands are specific to web projects, the later using the Yahoo compressor library to minify CSS and JavaScript files.

Provide a clean target

Every build file should include a target that removes all generated files and directories, bringing everything back to its original pristine state. All files remaining after the clean should be those found in version control.

An example clean command could be as follows:

<target name="clean" description="Deletes all generated files and directories">
	<delete dir="${dir.build}" />
	<delete dir="${dir.dist}" />
</target>

Use build files for all stages of the development process (development, staging and production)

Ant standardises your build and release cycle. Therefore use it for all stages of the development process. Use it for releasing code to your local development server, your staging or user acceptance testing server and your production server. The different deployments can obviously differ slightly based upon the needs, i.e. your production build need not include the creation of dummy data, but may include a call to source control.

Make build files self-contained

A build file that relies on external dependencies is one that will be difficult to configure or has the potential to cause problems. If your build depends on additional tools, put them in your source control repository. I generally include a lib for all dependencies in my project root. This folder includes such files as the Yahoo Compressor or JSLint.

Prefer a single build file

It is possible to split the build up into several small build files, each of which is responsible for a small proportion of the overall build. This isn’t always the best idea! Breaking the build often makes it harder to comprehend the whole process. It is better not to over-engineer the project and keep to a single, well formatted build file.

If your project is split into different build files, there should always be a master build file, found in the root directory of the project, even if it only delegates actual work to subordinate builds.

Put the build.xml file in the project’s root directory

The Ant build file can reside anywhere in the project tree, but conceptually it makes sense to put the file in the project root. This keeps things clean, simple and somewhat obvious to new members to the project. Having a build file in the top-level directory also makes it conceptually easy to see how relative paths point to different directories in the project tree.

When the build.xml file is in the top-level directory, you can compile code from the command line without the need to change the working directory.

Modularise your project

Arrange your project into coherent self-contain modules.

The following shows how I typically arrange my project files.

[root directory]
	/docs
	/lib
	/src
build.properties
build.xml
task.properties

The docs folder contains project documentation, the lib folder contains libraries specific to the project and required by Ant (generally this is a link to repository containing a number of utility JAR files, such as those for SVN and FTP). Finally, the src folder contains the actual project files.

Use version control

It is important to use version control for your entire project. The build file is an important artefact that needs to be versioned along with the source code of the project. When you tag a build for release, the build file should also be included. If you then need to roll back to a previous release, you will be able to build the code based upon the build file used for that particular release (after all, build files develop along with changes to the source code).

Third-party JAR and executable files should also be maintained in your local version control. This makes it possible to recreate previous releases, after all third-party libraries are likely to develop and change as frequently as your own code. If you want or need to take advantage of these changes, it is necessary to version control the older versions.

Avoid including build output in version control. Provided that you use version control correctly, you will be able to recreate these files at a later date.

Include comments in the build file (self-documenting)

Make the build file self-documenting. Adding target descriptions is one way to achieve this. For example:

<target name="clean" description="Deletes all generated files and directories">

Internal targets should not include description attributes. Internal targets may include targets that perform immediate processing, such as file concatenation or minifying.

Another way to include help in the build file is the echo tag. You can put any amount of comment between these tags and the information is printed to screen. For example:

<target name="clean" description="Deletes all generated files and directories">
	<echo>Cleaning project...</echo>
	<echo>Deleting build directory...</echo>
	<delete dir="${dir.build}" />
	<echo>Deleting dist directory...</echo>
	<delete dir="${dir.dist}" />
</target>

Summary

By using Ant and creating and maintaining build scripts for a project, the reliance on ad-hoc manual procedures for compiling and creating websites is removed. Using a defined process with Ant, or similar build tool, removes errors across the entire project, whilst allowing teams to develop code more efficiently.

References

Holzner, Steve (2005). Ant: The Definitive Guide, 2nd Edition, O’Reilly, ISBN 978-0-596-00609-9.

Apache Ant – http://ant.apache.org

Eclipse started out as a Java IDE and has continually grown from there. Plugins now include, amongst a plethora of others, the venerable Aptana, CFEclipse, SQL Explorer, Subclipse and, more recently, the Adobe-developed Flex Builder and ColdFusion-equivalent codenamed Bolt.

Apache Ant is a software tool for automating software build processes. It is implemented using the Java language, requires the Java platform, and was originally developed to automate the build of Java projects. However, since Ant was created as a simple, platform-independent tool, it can really be used to automate the build of anything you choose.

Ant uses XML to describe the build process and its dependencies, using a file commonly called build.xml. Using this file, Ant makes it trivial to integrate unit testing frameworks with the build process and has made it easy for web developers to adopt test-driven development, and even Extreme Programming.

Fortunately for us, if you download and run Eclipse, you already have Ant installed and so do not have any complex configuration to concern yourself with; well, at least initially.

Setting Up Eclipse

For the most part, Eclipse has all you need to get up and running with Ant pre-installed. However, most projects will include a release target which uses FTP to upload the files to a live server. The FTP ant task requires some extra libraries (.jar files):

commons-net-*.jar
jakarta-oro-*.jar

(The library files can be downloaded from here).

Copy the files into the ant lib folder of your Eclipse install. The folder is commonly located here:

C:\Program Files\Eclipse\plugins\org.apache.ant_*\lib

(The asterix * refers to the Ant version).

Next, go to Window > Preferences and select Ant > Runtime. In the Classpath tab, select Ant Home Entries, click Add External JARs… and select the 2 files you copied to the ant lib folder.

A Typical Ant Project Setup

A project with ant build scripts should have the following within the repository:

• build.xml (the actual ant build script)
• build.properties.template (a template for individual build.properties files)
• an optional top level lib folder (containing jar files for external ant tasks)

Examples of the build.xml and build.properties.template files can be downloaded from here.

Create Your Own build.properties File

Make a copy of the build.properties.template file (name it build.properties) and set the values to fit your local setup (in most cases, the only property you may want to change is deploy.dir.local which is the path to the site on your local machine).

This file should never be committed to the repository (the repository should be set to ignore it anyway).

Basic Build Tasks

The build file should have a deploy.local task. This task builds the project and copies it to your local webserver (the path to the web server folder will be defined in the build.properties file).

Most projects should also have a deploy.dev task to copy the latest work to the dev server so that other people can view it.

Setting Up an Automatic Build

To make things easy, you can set deploy.local to run every time you save a file. This is called an automatic build.

The process for setting up automatic build is quite convoluted. I’m not sure why but this is the best way I’ve found to make it work.

Step 1: Add the build file to your ant view

Click the add button and select the build.xml file from the project. You can also drag the build.xml file onto the ant view (To add the ant view to your perpective, go to Window > Show View > Other…)

Step 2: Run as Ant Build

In your ant view, right click the newly added build file and select Run As > Ant Build… In the dialog window, select the ‘Hide internal targets not selected for execution’ option in the Targets tab. You can rename the builder in the box at the top of the window if you wish (I usually remove the trailing ‘build.xml’. Click Apply and Close.

Step 3: Setup automatic build

Right click on the project, select Properties, then Builders. Click Import. Before closing the screen, highlight the imported build and select edit. Go to the Targets tab select clean for ‘After a clean’ and deploy.local for ‘Auto build’. Apply the changes and close.

Step 4: Enable Auto Build

Go to Project > Build Automatically

Acknowledgment: Thanks should go to Martin Laine for his help and guidance which resulted in this article.