Before Ant, building and deploying web applications required a series of scripts or manual processes, which often led to mistakes.

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