Installing Ant

Getting Ant

Binary edition

The latest stable version of Ant can be downloaded from http://jakarta.apache.org/builds/ant/release/v1.3/bin/. If you like living on the edge, you can download the latest version from http://jakarta.apache.org/builds/ant/nightly/.

Source Edition

If you prefer the source edition, you can download the source for the latest Ant release from http://jakarta.apache.org/builds/ant/release/v1.3/src/. Again, if you prefer the edge, you can access the code as it is being developed via CVS. The Jakarta website has details on accessing CVS. Please checkout the jakarta-ant module. See the section Building Ant on how to build Ant from the source code. You can also access the Ant CVS repository on-line.

System Requirements

To build and use Ant, you must have a JAXP-compliant XML parser installed and available on your classpath.

Both the binary and source distributions of Ant include the reference implementation of JAXP 1.0. Please see http://java.sun.com/xml/ for more information. If you wish to use a different JAXP-compliant parser, you should remove jaxp.jar and parser.jar from Ant's lib directory. You can then either put the jars from your preferred parser into Ant's lib directory or put the jars on the system classpath.

For the current version of Ant, you will also need a JDK installed on your system, version 1.1 or later. A future version of Ant will require JDK 1.2 or later.

Installing Ant

The binary distribution of Ant consists of three directories: bin, docs and lib Only the bin and lib directories are required to run Ant. To install Ant, choose a directory and copy the distribution file there. This directory will be known as ANT_HOME. Before you can run ant there is some additional set up you will need to do:

Add the bin directory to your path.
Set the ANT_HOME environment variable to the directory where you installed Ant.
Optionally, set the JAVA_HOME environment variable (see the Advanced section below). This should be set to the directory where your JDK is installed.
If you are using Ant's optional tasks then you may need to add additional jars to your lib directory or to your CLASSPATH. See Library Dependencies for for a list of jar requirements for various optional tasks.

Note: Do not install Ant's ant.jar file into the lib/ext directory of the JDK/JRE. Ant is an application, whilst the extension directory is intended for JDK extensions. In particular there are security restrictions on the classes which may be loaded by an extension.

Windows

Assume Ant is installed in c:\ant\. The following sets up the environment:

set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk1.2.2
set PATH=%PATH%;%ANT_HOME%\bin

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.2.2
export PATH=${PATH}:${ANT_HOME}/bin

Advanced

There are lots of variants that can be used to run Ant. What you need is at least the following:

The classpath for Ant must contain ant.jar and any jars/classes needed for your chosen JAXP-compliant XML parser.
When you need JDK functionality (such as for the javac task or the rmic task), then for JDK 1.1, the classes.zip file of the JDK must be added to the classpath; for JDK 1.2 or JDK 1.3, tools.jar must be added. The scripts supplied with Ant, in the bin directory, will add the required JDK classes automatically, if the JAVA_HOME environment variable is set.
When you are executing platform-specific applications, such as the exec task or the cvs task, the property ant.home must be set to the directory containing where you installed Ant. Again this is set by the Ant scripts to the value of the ANT_HOME environment variable.

Building Ant

To build Ant from source, you can either install the Ant source distribution or checkout the jakarta-ant module from CVS.

Once you have installed the source, change into the installation directory.

Set the JAVA_HOME environment variable to the directory where the JDK is installed. See Installing Ant for examples on how to do this for your operating system.

Make sure you have downloaded any auxiliary jars required to build tasks you are interested in. These should either be available on the CLASSPATH or added to the lib/optional directory. See Library Dependencies for for a list of jar requirements for various features. Note that this will make the auxiliary jars available for the building of Ant only. For running Ant you will still need to make the jars available as described under Installing Ant.

Your are now ready to build Ant:

build -Ddist.dir=<directory_to_contain_Ant_distribution> dist (Windows)

build.sh -Ddist.dir=<directory_to_contain_Ant_distribution> dist (Unix)

This will create a binary distribution of Ant in the directory you specified.

The above action does the following:

If necessary it will bootstrap the Ant code. Bootstrapping involves the manual compilation of enough Ant code to be able to run Ant. The bootstrapped Ant is used for the remainder of the build steps.
Invokes the bootstrapped Ant with the parameters passed to the build script. In this case, these parameters define an Ant property value and specify the "dist" target in Ant's own build.xml file.

On most occasions you will not need to explicitly bootstrap Ant since the build scripts do that for you. If however, the build file you are using makes use of features not yet compiled into the bootstrapped Ant, you will need to manually bootstrap. Run bootstrap.bat (Windows) or bootstrap.sh (UNIX) to build a new bootstrap version of Ant.

If you wish to install the build into the current ANT_HOME directory, you can use:

build install (Windows)

build.sh install (Unix)

You can avoid the lengthy Javadoc step, if desired, with:

build install-lite (Windows)

build.sh install-lite (Unix)

This will only install the bin and lib directories.

Both the install and install-lite targets will overwrite the current Ant version in ANT_HOME.

Running Ant

Running Ant is simple, when you installed it as described in the previous section. Just type ant.

When nothing is specified, Ant looks for a build.xml file in the current directory. If found, it uses that file as the buildfile. If you use the -find option, Ant will search for a buildfile in the parent directory, and so on, until the root of the filesystem has been reached. To make Ant use another buildfile, use the command-line option -buildfile file, where file is the buildfile you want to use.

You can also set properties that override properties specified in the buildfile (see the property task). This can be done with the -Dproperty=value option, where property is the name of the property, and value is the value for that property. This can also be used to pass in the value of some environment variables. You can also access environment variables using the property task. Just pass -DMYVAR=%MYVAR% (Windows) or -DMYVAR=$MYVAR (Unix) to Ant – you can then access these variables inside your buildfile as ${MYVAR}.

Two more options are: -quiet, which instructs Ant to print less information on the console when running, and -verbose, which causes Ant to print additional information to the console.

It is also possible to specify one or more targets that should be executed. When omitted, the target that is specified in the default attribute of the <project> tag is used.

The -projecthelp option gives a list of this project's targets. First those with a description, then those without one.

Command-line option summary:

ant [options] [target [target2 [target3] ...]]
Options:
-help                  print this message
-projecthelp           print project help information
-version               print the version information and exit
-quiet                 be extra quiet
-verbose               be extra verbose
-debug                 print debugging information
-emacs                 produce logging information without adornments
-logfile file          use given file for log output
-logger classname      the class that is to perform logging
-listener classname    add an instance of class as a project listener
-buildfile file        use specified buildfile
-find file             search for buildfile towards the root of the filesystem and use the first one found
-Dproperty=value       set property to value

Examples

ant

runs Ant using the build.xml file in the current directory, on the default target.

ant -buildfile test.xml

runs Ant using the test.xml file in the current directory, on the default target.

ant -buildfile test.xml dist

runs Ant using the test.xml file in the current directory, on a target called dist.

ant -buildfile test.xml -Dbuild=build/classes dist

runs Ant using the test.xml file in the current directory, on a target called dist, setting the build property to the value build/classes.

Running Ant by Hand

If you have installed Ant in the do-it-yourself way, Ant can be started with:

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]

These instructions actually do exactly the same as the ant command. The options and target are the same as when running Ant with the ant command. This example assumes you have set your classpath to include:

ant.jar
jars/classes for your XML parser
the JDK's required jar/zip files

Library Dependencies

The following libraries are needed in your CLASSPATH or in the install directory's lib directory if you are using the indicated feature. Note that only one of the regexp libraries is needed for use with the mappers.

Jar Name Needed For Available At

jakarta-regexp-1.2.jar regexp type with mappers jakarta.apache.org/regexp/

jakarta-oro-2.0.1.jar regexp type with mappers and the perforce tasks jakarta.apache.org/oro/

junit.jar junit tasks www.junit.org

stylebook.jar stylebook task CVS repository of xml.apache.org

testlet.jar test task java.apache.org/framework

antlr.jar antlr task www.antlr.org

bsf.jar script task oss.software.ibm.com/developerworks/projects/bsf

netrexx.jar netrexx task www2.hursley.ibm.com/netrexx

rhino.jar javascript with script task www.mozilla.org

jpython.jar python with script task www.jpython.org

netcomponents.jar ftp and telnet tasks www.savarese.org/oro/downloads

Jar Name	Needed For	Available At
jakarta-regexp-1.2.jar	regexp type with mappers	jakarta.apache.org/regexp/
jakarta-oro-2.0.1.jar	regexp type with mappers and the perforce tasks	jakarta.apache.org/oro/
junit.jar	junit tasks	www.junit.org
stylebook.jar	stylebook task	CVS repository of xml.apache.org
testlet.jar	test task	java.apache.org/framework
antlr.jar	antlr task	www.antlr.org
bsf.jar	script task	oss.software.ibm.com/developerworks/projects/bsf
netrexx.jar	netrexx task	www2.hursley.ibm.com/netrexx
rhino.jar	javascript with script task	www.mozilla.org
jpython.jar	python with script task	www.jpython.org
netcomponents.jar	ftp and telnet tasks	www.savarese.org/oro/downloads