A guide to Ant, an advanced build system

Ant is a very advanced and flexible build system. It seems really modular and able to accomplish a lot of tasks. However, it also seems complex to understand and learn.

The Basics

• Ant build files are XML files.

• These XML buildfiles (default name, like "Makefile" for GNU Make, is "build.xml") contain a list of targets. A target itself contains a list of tasks.

• A task is anything Ant can do: it can launch a Java compilation, copy files to a directory, and LOTS of other stuff.

Ant and Gentoo

• On Gentoo, Ant uses the ANT_TASKS environment variable. This will create a default system classpath. Be cautious about this classpath: it may include some versions of jars you don't want to use. To disable the default system classpath, use ANT_TASKS="none".

Hints & Tips

• To import another file from a first one, you can use the import task:

<import file="configuration.ant.xml"/>

In this case, the imported file must be a valid Ant XML file. You can also (more easily) just include a list of properties from a file directly with the property task.

• To be able to reference a variable and expand it (eg, for ${DeploymentDirectory} to be replaced by /var/www/), you must use a property (here, with the name "DeploymentDirectory"). It won't work if you try to reference an XML node, for example.

• In the javac task, don't include part of the package structure in the srcdir attribute. Eg, don't write srcdir=src/com/example/. Else it will confuse Ant, and Ant will rebuild every Java source file at every run.

• To echo a path or file set, create a property and use the refid attribute, pointing to the file set. Then echo the property.

• You can build path structures containing file sets very easily with nested fileset nodes.

<path id="hosted.class.path">
  <pathelement path="${java.class.path}/" />
  <fileset dir="/usr/share/tomcat-5.5/common/lib" casesensitive="yes">
  <include name="**/*.jar" />
</fileset>

• To use special characters like " (quotes) in Ant, use the HTML/XHTML special representations (").

• To print Ant's class path from the command line:

ant --execdebug

File Sets

• When invoking a task involving file sets (delete for example), and you want to also include empty directories, don't forget to add the includeemptydirs="true" attribute.

• Pay attention to nested elements in file sets. For example, if you want all *.xml files, but not *.cfg.xml files, use:

<fileset dir="src/" includes="**/*.xml" >
    <exclude name="**/*.gwt.xml"/>
</fileset>

The following would not work:

<fileset dir="src/" includes="**/*.xml" />
<fileset dir="src/" excludes="**/*.gwt.xml"/>

Tasks

• The scp task does not seem to work with directories containing subdirectories (the scp operation will hang). Update: this was due to a bug introduced in jsch 0.1.30 (the library Ant uses for SSH communication). Update to jsch 0.1.32 and a recent ant-jsch.

• There seems to be a very interesting Subversion task (svnant, developed at Tigris) which allows you to do operations based on file selectors. You could then define a fileset with all modified files, for example.

Gant

Gant seems to be a really excellent build system. It is a combination of Groovy code and Ant tasks. Quick notes about Gant:

• ${root.property} WILL not refer to an Ant property in a Gant script, but (logically) to a Groovy variable. Access an Ant property in the following way:

Ant.antProject.properties."root.property"

Set it using:

Ant.property(name:"local.deployment.dir", value:"/var/lib/tomcat-5.5/webapps/")