Java programming course (SIN) Pascal Perez (IN) – pascal.perez@epfl.

ch
1/6

ant: a Java-based build tool

“Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without
Make's wrinkles.

Why another build tool when there is already make, gnumake, nmake, jam, and others?
Because all those tools have limitations that Ant's original author couldn't live with when
developing software across multiple platforms. Make-like tools are inherently shell-based
-- they evaluate a set of dependencies, then execute commands not unlike what you
would issue in a shell. This means that you can easily extend these tools by using or
writing any program for the OS that you are working on. However, this also means that
you limit yourself to the OS, or at least the OS type such as Unix, that you are working
on.” – Apache Ant developer team.

build tools
When developing a large scale project, the compilation, packaging and distribution
generation can become very time consuming. Build tools offer a way of expressing a set
of tasks which must be accomplished for a certain goal (e.g. documentation generation,
full project compilation, etc…), and to write these in a build file.

Tasks depend on other tasks so that an order of task execution can be computed
automatically (removing that burden off the programmers!). For instance, suppose we
want to generate a full distribution of a program, the set of tasks might be:

- (1) init: initialize the build process

- (2) compile-java { depends on init }: compile all the Java sources
- (3) compile-c { depends on init }: compile all the C sources
- (4) jar { depends on compile-java }: generate a jar file
- (5) zip { depends on jar, compile-java and compile-c }: generate a distribution in a
zip file

From this information, it is possible to construct an oriented graph representing

dependencies:

1 5

which has three possible ordering (1)→(3)→(2)→(4)→(5), (1)→(2)→(3)→(4)→(5) and

(1)→(2)→(4)→(3)→(5).
 Java programming course (SIN) Pascal Perez (IN) – pascal.perez@epfl.ch
2/6

ant build files – xml & file layout

Ant build file, usually build.xml, is written in an XML dialect. For those who do not know
XML, don’t panic, it’s very easy.

An XML dialect is composed of tags (a name surrounded by ‘<’ and ‘>’). Every tag must
be opened and closed:

<hello></hello>

or in short

<hello />

the space before the ‘/>’ construct is not mandatory, but I recommend to adopt this
convention. For a full explanation consult Java & XML [1].

A tag can have attributes which are of the form:

<hello text="welcome" />

Tags can surround other tags or text:

<hello text="welcome">
<image path="pub/welcome.png" />
</hello>

And finally, comments are written:

<!-- comment -->

Bear in mind that this is a very short introduction to XML, for more information, consult
the W3C Recommendations [2].

A complete build file is of the form

<?xml version="1.0"?>
<project name="Project Name" default="default target" basedir=".">
<description>Project description</description>
...
</project>

Where the first line is called the prolog (specifying which version of XML we are using).
The description is not mandatory but very strongly recommended.

ant build files – targets

A build file must contain a set of tasks to complete. In ant, these are grouped in targets
which depend on one another. Targets are labeled by a name, usually have a list of
dependencies and should have a description. These are written as

<target name="target name"

depends="comma separated list of targets’ name"
description="a short description">
...
</target>
 Java programming course (SIN) Pascal Perez (IN) – pascal.perez@epfl.ch
3/6

ant build files – tasks

Ant has many built in tasks such as javac instantiation, zip archiving, jar creation (with
automatic manifest generation) and so on. We are going to cover some of the more
useful, for a full and detailed description consult ant’s documentation [3].

javac
Compile a Java source tree.

<javac srcdir="${src}" destdir="${classes}" />

Where srcdir is the source directory and destdir is the destination directory. Many
options are available.

javadoc
Generate the documentation from Java sources.

<javadoc sourcepath="${src}" destdir="${javadoc}"

packagenames="*" author="true" version="true" />

Where sourcepath is the source directory, destdir is the destination directory,

packagenames describes (with the help of wildcards) the set of packages for which
documentation will be generated, author and version specify whether the @author,
respectively @version, fields’ information should be included.

jar
Generates a jar file.

<jar destfile="${project}.jar" basedir="${classes}">

<manifest>
<attribute name="Built-By" value="Authors" />
<attribute name="Main-Class" value="main class" />
</manifest>
</jar>

Note here that the jar’s manifest will be automatically generated.

mkdir
Create a directory.

<mkdir dir="${classes}" />

delete
Delete a file of a directory.

<delete dir="${classes}" />

<delete file="${project}.jar " />

zip
Compress a set of files and creates a zip archive.

<zip destfile="${backup}/${project}-${DSTAMP}-${TSTAMP}.zip">
<zipfileset dir="${src}" prefix="src">
<include name="**/*" />
</zipfileset>
</zip>
 Java programming course (SIN) Pascal Perez (IN) – pascal.perez@epfl.ch
4/6

ant build files – properties

You have probably noticed from the previous examples, the funny ${src} kind of
notation. This actually represents a property named src. Properties can be used like
variables in a programming language.

There are defined as

<property name="project" value="Project Name" />

or, if the property points to a location (directory, file)

<property name="javadoc" location="doc" />

In addition, the time stamp (<tstamp />) task declares the two properties ${DSTAMP}
and ${TSTAMP} which, by default, represent the day stamp in the yyyymmdd format and
the time stamp in the hhmm format.

ant build files – a complete example: CirKuit 2D’s build file

CirKuit 2D [4] is a Java based game. It’s simplified build file is going to illustrate this
tutorial:

<?xml version="1.0"?>
<project name="CirKuit 2D" default="compile" basedir=".">
<description>CirKuit 2D build file</description>

<!-- set global properties for this build -->

<property name="project" value="CirKuit2D" />
<property name="version" value="2.0-alpha" />
<property name="src" location="src" />
<property name="classes" location="classes" />
<property name="javadoc" location="doc" />
<property name="backup" location="backup" />

<!-- Initialize the build -->

<target name="init">
<tstamp />
<mkdir dir="${classes}" />
<mkdir dir="${javadoc}" />
<mkdir dir="${backup}" />
</target>

<!-- Compile the java code from ${src} into ${classes} -->
<target name="compile" depends="init"
description="Compile the project">
<javac srcdir="${src}" destdir="${classes}" />
</target>

<!-- Generate the .jar file -->

<target name="jar" depends="compile"
description="Generate the jar file">
<jar destfile="${project}.jar" basedir="${classes}">
<manifest>
<attribute name="Built-By"
value="Sven Gowal and Pascal Perez" />
<attribute name="Main-Class" value="cirkuit.CirKuit" />
</manifest>
</jar>
</target>
 Java programming course (SIN) Pascal Perez (IN) – pascal.perez@epfl.ch
5/6

<!-- Generate the javadoc -->

<target name="doc" depends="init" description="Generating the javadoc">
<javadoc sourcepath="${src}" destdir="${javadoc}"
packagenames="*" author="true" version="true"
breakiterator="true">
<link href="http://java.sun.com/j2se/1.4.2/docs/api" />
</javadoc>
</target>

<!-- Backup .java files in a gzipped tar archive -->

<target name="backup" depends="init"
description="Make a backup of the source">
<zip destfile="${backup}/${project}-${DSTAMP}-${TSTAMP}.zip">
<zipfileset dir="${src}" prefix="src">
<include name="**/*" />
</zipfileset>
<zipfileset dir=".">
<include name="build.xml" />
</zipfileset>
</zip>
</target>

<!-- Cleaning -->

<target name="clean" description="Clean">
<delete dir="${classes}" />
</target>
</project>

It is then possible to type in a command line prompt:

$ ant
$ ant jar
$ ant doc
$ ant backup and
$ ant clean
 Java programming course (SIN) Pascal Perez (IN) – pascal.perez@epfl.ch
6/6

ant - installation
First of all, you must download ant from the Apache Ant website [3] or from a mirror.
The binary distribution is easier to install… and the source distribution requires ant for its
build process!

Binary distribution is available in zip, tar.gz and tar.bz2 format.

Extract all files of the archive and place them in a “reasonable” directory (further
mentioned as installdir) for instance

UNIX: /usr/ant, /usr/java/ant or other

Windows: C:\Program Files\ant

To be able to use the binaries in the command prompt, you must add to the PATH
environment variable a path to installdir/bin and add a ANT_HOME variable.

bashrc
export ANT_HOME=installdir
export PATH=${PATH}:${ANT_HOME}/bin

cshrc
set ANT_HOME installdir
set PATH ${PATH}:${ANT_HOME}/bin

Windows
Start > Parameters > Control Panel System and open the “Advanced” tab. A button label
“environment variables” let’s you access the system’s environment’s variables.

bibliography
[1] McLaughlin, Brett. Java & XML. Trans. Alexandre Gachet. Paris: O’Reilly, 2002.

[2] “Extensible Markup Language (XML) 1.0 (Second Edition).” 6 October 2000
<http://www.w3.org/TR/2000/REC-xml-20001006>.

[3] “Apache Ant.” 23 February 2005 <http://ant.apache.org>.

[4] “CirKuit 2D.” 21 February 2005 <http://projects.lha.ch>.