Ant Tutorial

What is Ant?

Ant is a sophisticated version of a Makefile or a build script. It simplifies a complicated compile and build process into something as short as typing "ant" on the command line. Ant is different because it is completely platform independent, unlike a Makefile. Ant is built on java, and interprets all build commands as calls within java, allowing a build script to be written once and used on nearly any operating system.

Setup

Ant needs to be installed before its build scripts can be run. To install ant, download the latest binary distribution from http://ant.apache.org/. Unzip the folder anywhere where you will remember its pathname. Next, set the path for the operating system you are using:

(Taken from http://ant.apache.org/manual/index.html)

Windows and OS/2
Assume Ant is installed in c:\ant\. The following sets up the environment:

set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk-1.5.0.05
set PATH=%PATH%;%ANT_HOME%\bin

Linux/Unix (bash)
Assume Ant is installed in /usr/local/ant. The following sets up the environment:

export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk-1.5.0.05
export PATH=${PATH}:${ANT_HOME}/bin

Linux/Unix (csh)

setenv ANT_HOME /usr/local/ant
setenv JAVA_HOME /usr/local/jdk/jdk-1.5.0.05
set path=( $path $ANT_HOME/bin )

Once the environment variables have been correctly set, you're ready to start running ant build scripts.

The most basic build script

The script

This is a very, very basic example to explain the layout of an ant build script. The following xml code is located in a file called build.xml. Ant will look for this file wherever it is run.
If you are unfamiliar with xml (extensible markup language), visit http://www.w3schools.com/xml/default.asp for a tutorial on how to write and understand xml.

build.xml:

<?xml version="1.0"?>
<project default="all">
	<target name="all">
		<echo>This is a basic ant build script.</echo>
	</target>
</project>

• The first line, <?xml version="1.0"?> is not particular to Ant. It is a part of xml and should be included in all Ant build scripts.

• The second line contains the project tag: <project default="all">...</project>. This tag defines the main settings for Ant to use when building the project. The only setting that has been defined here is the default target to build. This means that when Ant is run with no command line argument, it will look for and build "all". This can be the name of any target, I've just chosen to call it "all".

• The third line contains the target tag: <target name="all">...</target>. This tag defines a particular task to be run. Here, we have created the target named "all" which we referenced in the project tag. Target tags must appear within the project tag. Target tags contain lists of task tags to be executed when that target is run.

• The fourth line contains the echo tag: <echo>This is a basic ant build script.</echo>. Like the echo command in unix, it will write the provided text to the console. Echo is a task tag. There are many tasks that can be performed in Ant. A list of them can be found here: http://ant.apache.org/manual/tasksoverview.html.

Running it

Copy the xml in the exmaple above into a new file, build.xml. From the command line, navigate to the directory containing the build.xml file. Type ant and press enter. You should see the following output:

Buildfile: build.xml

all:
     [echo] This is a basic ant build script.

BUILD SUCCESSFUL
Total time: 0 seconds

If you do not get output similar to this from running ant, check your path and try again.

As you can see, Ant ran the target "all" and performed the echo task.

A realistic example

The script

While the basic script demonstrates how to create a script and run it, it isn't very useful for demonstrating how to use Ant to compile code. Here is a more useful script:

<?xml version="1.0"?>
<project name="example" basedir="." default="all">
	<property name="src" value="."/>
	<property name="bin" value="bin"/>

	<target name="all" depends="compile" description="Builds the entire project">
		<echo>All Files Compiled!</echo>
	</target>

	<target name="compile" depends="setup" description="Compiles the source files">
		<javac srcdir="${src}" destdir="${bin}"/>
	</target>

	<target name="setup" description="Creates the class file directory">
		<mkdir dir="${bin}"/>
	</target>

	<target name="clean" description="Removes all class files">
		<delete dir="${bin}"/>
	</target>

	<target name="cleanBuild" description="Deletes and recompiles all files from source">
		<antcall target="clean"/>
		<antcall target="all"/>
	</target>
</project>

This script has several targets and many new tags and values specified. To get a general idea of what each target does, you can type ant -projecthelp. Ant should display something like this:

Buildfile: build.xml

Main targets:

 all         Builds the entire project
 clean       Removes all class files
 cleanBuild  Deletes and recompiles all files from source
 compile     Compiles the source files
 setup       Creates the class file directory
Default target: all

Ant looks through all of the script's target tags and displays the value of the "description" attribute for each target. It also displays the default target for this project. Specific targets can be run instead of the default by running ant [targetName] at the command line.

• The project tag has two new attributes: "name" and "basedir". Name is simply the name of the project. Basedir is the directory on which all relative paths are built. In this script we simply make it the current working directory, but you may need to change this to another value.

• Some of the target tags have a new attribute named "depends". Depends lists all targets that must be successfully completed before this target can be run. For example, the "compile" target can't be run until the "setup" target has finished, which creates the directory for the compiled class files to be placed in. Multiple depends targets can be specified by listing them with commas: <target depends="target1,target2">...</target>.

• There are two new tags inside of the project: <property name="src" value="."/> and <property name="bin" value="bin"/>. These property tags are like variables in a script. Here they are used to specify the source and binary folders. Using a property tag makes it easy if suddenly the "bin" folder needed to be renamed to "build". You would only have to change it in one place. To use the property somewhere in the script, specify it with ${PropertyName}. For example, in this script attribute="${src}" is the equivalent of: attribute=".".

• In the compile target we finally use the <javac> tag. Two attributes have been specified for this tag: "srcdir" and "destdir". Ant will recursively search through srcdir and its subdirectories for all .java files. It will compile these java files and place the resulting .class files inside destdir. Just like a Makefile, the javac tag won't compile anything that has a .class file with a later modification date than its corresponding .java file, resulting in faster compile times. The javac tag has many attributes which correspond to javac's command line interface. Descriptions of these attributes can be found here: http://ant.apache.org/manual/CoreTasks/javac.html.

• Two new tags: <mkdir> and <delete> simulate command line utilities. On windows, to delete a file del must be used, while the linux/unix equivalent is rm. Ant standardizes this function into one universal tag which will work on either operating system. For more information about these and other tags and their specific attributes and options, including examples, please visit: http://ant.apache.org/manual/tasksoverview.html.

• Finally, the target cleanBuild uses yet another new tag named <antcall>. This tag is used to specifically run a target within the project. You may be wondering, why not just use the depends attribute? The reason is that we want the "clean" target to run before the "all" target. Depends gives no guarantee about the order in which targets are run. We can use antcall to sequentially run targets.

Running it

1. Download the following files to a new directory: build.xml, MainClass.java, SubClass.java.
2. Open a command prompt in the directory
3. Run ant. You should get the following output:

   Buildfile: build.xml
   
   setup:
       [mkdir] Created dir: ...\ant_test\bin
   
   compile:
       [javac] Compiling 2 source files to ...\ant_test\bin
   
   all:
        [echo] All Files Compiled!
   
   BUILD SUCCESSFUL
   Total time: 0 seconds
   

4. Modify SubClass.java so that the System.out line reads: System.out.println("I was made using Ant twice!");
5. Run ant again. You should get the following output:

   Buildfile: build.xml
   
   setup:
   
   compile:
       [javac] Compiling 1 source file to ...\ant_test\bin
   
   all:
        [echo] All Files Compiled!
   
   BUILD SUCCESSFUL
   Total time: 0 seconds
   

6. Note that the setup taget did not do anything because the directory "bin" already exists, and that javac only compiles the one source file we modified.
7. Run ant cleanBuild. You should get the following output:

   Buildfile: build.xml
   
   cleanBuild:
   
   clean:
      [delete] Deleting directory ...\ant_test\bin
   
   setup:
       [mkdir] Created dir: ...\ant_test\bin
   
   compile:
       [javac] Compiling 2 source files to ...\ant_test\bin
   
   all:
        [echo] All Files Compiled!
   
   BUILD SUCCESSFUL
   Total time: 0 seconds
   

8. The entire old bin folder and its contents were deleted, the folder was recreated and all source files were recompiled.
9. Run ant clean, the bin folder is removed.

What now?

By now you should have a good enough grasp of ant to be able to start using it for your own projects. Ant can be used for far more sophisticated tasks than simple compile tasks like I've shown here. Ant can even automatically generate documentation for your project as part of your build process. If you can't find a task that suits your needs from Ant's existing list of tasks, you can write your own. If you're thirsting for more, the Ant User Manual and google should be able to satisfy your curiosity. Happy coding!