Getting Started with Ant

by Dr. Wenjie He

Apache Ant is a Java-based build tool that is platform independent. The configuration files are XML-based. The Eclipse has Ant built-in. Although we will use Eclipse and its built-in Ant to develop most of our web applications, we also install an Ant version outside the Eclipse, so that we can run Ant at the command line.

1. Installing Ant

1. Download Ant at the Apache Ant download page http://ant.apache.org/bindownload.cgi. The current Ant version is 1.7.1. Download the version for your operation system. Here we download apache-ant-1.7.1-bin.zip for Windows machines.
2. Select a directory for your Ant installation. As in our plan, we created a directory called C:\JavaEE\Tools. Unzip the file apache-ant-1.7.1-bin.zip and extract all the files into C:\JavaEE\Tools. Then our Ant's installation directory is C:\JavaEE\Tools\apache-ant-1.7.1.

2. Setting Up Ant Environment

Ant relies on Java. We assume that you have Java JDK installed in this tutorial.

1. Set the ANT_HOME environment variable to your Ant installation directory. In this tudtorial, we set it as follows,
   Variable name: ANT_HOME
   Variable value: C:\JavaEE\Tools\apache-ant-1.7.1
2. Add ;%ANT_HOME%\bin at the end of your PATH environment variable (including the semi-colon).
3. Assume that you have already set the JAVA_HOME environment variable to point to yout JDK installation directory, otherwise you need to set it. Add %JAVA_HOME%\bin into your PATH environment variable if you have not done so.
4. Add the . (the path of the current directory) to your CLASSPATH environment variable.
Watch the video clip ( play ) for the whole procedure.
5. Restart your computer to make your new environment variables take effect.

Study Examples

Download Source Code

Download the source code for this tutorial AntExamples.zip, and extract the files in it to an approriate directory.

Example 1.   HelloWorld

Code Listing: build.xml

           
1.	<project name="HelloWorld" basedir="." default="main">
2.
3.	    <target name="clean">
4.	        <delete dir="build"/>
5.	    </target>
6.
7.	    <target name="compile">
8.	        <mkdir dir="build/classes"/>
9.	        <javac srcdir="src" destdir="build/classes"/>
10.	    </target>
11.
12.	    <target name="jar">
13.	        <mkdir dir="build/jar"/>
14.	        <jar destfile="build/jar/${ant.project.name}.jar" 
15			basedir="build/classes">
16.	            <manifest>
17.	                <attribute name="Main-Class" 
18.				value="org.apache.ant.HelloWorld"/>
19.	            </manifest>
20.	        </jar>
21.	    </target>
22.
23.	    <target name="run">
24.	        <java jar="build/jar/${ant.project.name}.jar" fork="true"/>
25.	    </target>
26.
27.	    <target name="main">
28.	    </target>
29.
30.	</project>
      

1. (Line 1) Each Ant buildfile contains exactly one project element and at least one (default) target.
2. (Line 1) The default attribute specifies the default target (see target below). When you run an Ant command without providing any target, then the default target will be executed.
3. (Line 1) The name attribute specifies the name of the project.
4. (Line 1) The basedir attribute sets the base directory, and all the relative directories are with respected to this directory.
5. (Line 3) Each project defines one or more targets. A target is a set of tasks you want to execute. When starting Ant, you can select which target(s) you want to execute. When no target is given, the project's default is used.
6. (Line 3) The name attribute specifies the name of the target.
7. (Line 4) A task is a piece of code that can be executed. There are two types Ant's tasks: the built-in tasks and the user-defined tasks. The delete task is an Ant built-in task. When it is executed, the directory specified by its dir attribute (inside the dase directory) is deleted.
8. (Line 8) The built-in mkdir task creates a new directory.
9. (Line 9) The built-in javac task compiles a Java source tree. The source directory will be recursively scanned for Java source files to compile. Only Java files that have no corresponding .class files or those whose .class files are older than their .java files will be compiled.
   When the source files are part of a package, the directory structure of the source tree should follow the package hierarchy.
For example, the source file of HelloWorld.java is listed below,
Code Listing: HelloWorld.java

    
1.	package org.apache.ant;
2.
3.	public class HelloWorld {
4.	    public static void main(String[] args) {
5.	        System.out.println("Hello World");
6.	    }
7. 	}
	

The directory structure under src is org/apache/ant.
10. (Line 14) The built-in jar task creates a .jar file on a set of files. The basedir attribute is the reference directory from which to jar.
11. (Line 14) The destfile attribute specifies the JAR file to be created.
12. (Line 14) ${ant.project.name} refers the value of the built-in property ant.project.name.
13. (Line 16) The manifest nested element allows the manifest for the Jar file to be provided inline in the build file rather than in an external file. After the Main-Class is defined, this JAR file becomes an executable JAR file.
14. (Line 24) The java task executes a Java class within the running (Ant) VM or forks another VM if specified.
15. (Line 24) When the fork attribute is set true, it makes the class execution in another VM.

Running Targets

1. Run the compile target.

    
ant compile
	 

2. Run the jar target.

    
ant jar
	 

3. Run the run target.

    
ant run
	 

4. Run the clean target.

    
ant clean
	 

Example 2.   HelloWorld2

Code Listing: build.xml

  
1.	<project name="HelloWorld2" basedir="." default="main">
2.
3.	    <property name="src.dir"     value="src"/>
4.	    <property name="build.dir"   value="build"/>
5.	    <property name="classes.dir" value="${build.dir}/classes"/>
6.	    <property name="jar.dir"     value="${build.dir}/jar"/>
7.	    <property name="main-class"  value="org.apache.ant.HelloWorld2"/>
8.
9.	    <target name="clean">
10.	        <delete dir="${build.dir}"/>
11.	    </target>
12.
13.	    <target name="compile">
14.	        <mkdir dir="${classes.dir}"/>
15.	        <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
16.	    </target>
17.	
18.	    <target name="jar" depends="compile">
19.	        <mkdir dir="${jar.dir}"/>
20.	        <jar destfile="${jar.dir}/${ant.project.name}.jar" 
21.			basedir="${classes.dir}">
22.	            <manifest>
23.	                <attribute name="Main-Class" value="${main-class}"/>
24.	            </manifest>
25.	        </jar>
26.	    </target>
27.
28.	    <target name="run" depends="jar">
29.	        <java jar="${jar.dir}/${ant.project.name}.jar" fork="true"/>
30.	    </target>
31.
32.	    <target name="clean-build" depends="clean,jar"/>
33.
34.    	    <target name="main" depends="clean,run"/>
35.
36.	</project>

      

1. (Line 3) A project can have a set of properties. A property has a name and a value; the name is case-sensitive. Properties may be used in the value of task attributes. Later when we use ${src.dir}, it means the value of src
2. (Line 18) The depends attribute of target specifies the target name that must be executed before this target. When there are several targets that this target depends on, a comma-separated list of names of targets can be used.

Run the default main target.

  
ant
      

Example 3.   HelloAnt

Code Listing: build.xml

  
1.	<project name="HelloAnt" basedir="." default="main">
2.
3.	    <property name="src.dir"     value="src"/>
4.	    <property name="build.dir"   value="build"/>
5.	    <property name="classes.dir" value="${build.dir}/classes"/>
6.	    <property name="jar.dir"     value="${build.dir}/jar"/>
7.	    <property name="browser" 
8.			location="C:/Program Files/Internet Explorer/iexplore.exe"/>
9.	    <property name="file" location="HelloAnt.html"/>
10.
11.	    <property name="main-class"  value="myant.HelloAnt"/>
12.
13.	    <target name="clean">
14.	        <delete dir="${build.dir}"/>
15.	        <delete file="${file}"/>
16.	    </target>
17.
18.	    <target name="compile">
19.	        <mkdir dir="${classes.dir}"/>
20.	        <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
21.	    </target>
22.
23.	    <target name="jar" depends="compile">
24.	        <mkdir dir="${jar.dir}"/>
25.	        <jar destfile="${jar.dir}/${ant.project.name}.jar" 
26.			basedir="${classes.dir}">
27.	            <manifest>
28.	                <attribute name="Main-Class" value="${main-class}"/>
29.	            </manifest>
30.	        </jar>
31.	    </target>
32.
33.	    <target name="run" depends="jar">
34.	        <java jar="${jar.dir}/${ant.project.name}.jar" fork="true"/>
35.	        <exec executable="${browser}">
36.	    	    <arg value="${file}"/>
37.	        </exec>
38.	    </target>
39.
40.	    <target name="clean-build" depends="clean,jar"/>
41.
42.	    <target name="main" depends="clean,run"/>
43.
44.	</project>
      

1. (Line 35) The exec task executes a system command.
2. (Line 36) The arg element inside the exec gives an argument for the command.

Run the default target.

Example 4.   MyTask

Code Listing: build.xml

  
1.	<?xml version="1.0" encoding="ISO-8859-1"?>
2.	<project name="MyTask" basedir="." default="use">
3.	
4.	    <property name="src.dir" value="src"/>
5.	    <property name="classes.dir" value="classes"/>
6.
7.	    <target name="clean" description="Delete all generated files">
8.	        <delete dir="${classes.dir}" failonerror="false"/>
9.	        <delete file="${ant.project.name}.jar"/>
10.	    </target>
11.
12.	    <target name="compile" description="Compiles the Task">
13.	        <mkdir dir="${classes.dir}"/>
14.	        <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
15.	    </target>
16.
17.	    <target name="jar" description="JARs the Task" depends="compile">
18.	        <jar destfile="${ant.project.name}.jar" basedir="${classes.dir}"/>
19.	    </target>
20.
21.	    <target name="use" description="Use the Task" depends="jar">
22.	        <taskdef name="hellotask" classname="org.apache.ant.HelloTask" 
23.			 classpath="${ant.project.name}.jar"/>
24.	        <hellotask/>
25.	    </target>
26.
27.	</project>
       

1. (Line 8) The attribute failonerror="false" means that if there is an error in this task (delete), the execution of the target (clean) still continues.
2. (Line 22) The taskdef task defines a user-defined task. The classname and classpath speak for themselves.

Run the default target.

Code Listing: HelloTask.java

  
1.	package org.apache.ant;
2.
3.	public class HelloTask {
4.
5.	    public void execute() {
6.	        String message = "Hello Task";
7.	        System.out.println("Here is the message: " + message );
8.	    }
9.	}
      

1. (Line 5) The execute method is invoked automatically.

Running Ant on School Machines

Many students use the school machines to work on their Java EE projects, and they do not have the privilege to set the environment variables on the school machines. In this situation, we can use a .bat script to set the environment variables as follows.

1. Create a folder called Ant under the C drive.
Here I want to make it simple. Since we install Ant on school's machine temporarily, we do not need to use the long path C:\JavaEE\Tools\ as I recommended before. But if you need to work with other students on the same project, you may need to use the long path as others do.
2. Unzip the file apache-ant-1.7.1.zip and extract all the files into the folder C:\Ant.
3. Download the script setenv.bat and put it in the directory C:\Ant.
4. Open a command window and cd to the directory C:\Ant.
5. At the command line, type the following command,

setEnvAnt

You would see all the environment variables needed for Ant are set in this window. If you use a new window, all these environment variavles are gone. You need to reset them if you want to use them.
6. In the same command window in which you set the environment variables, cd to the directory that contains your project to be built by Ant.

==========The End==========