Installing Ant

Getting Ant

Binary Edition

The latest stable version of Ant is available from the Ant web page If you like living on the edge, you can download the latest version from

Source Edition

If you prefer the source edition, you can download the source for the latest Ant release from 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 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

Ant has been used successfully on many platforms, including Linux, commercial flavours of Unix such as Solaris and HP-UX, Windows 9x and NT, OS/2 Warp, Novell Netware 6 and MacOS X.

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

The binary distribution of Ant includes the latest version of the Apache Xerces2 XML parser. Please see for more information about JAXP. If you wish to use a different JAXP-compliant parser, you should remove xercesImpl.jar and xml-apis.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.2 or later.

Note: The Microsoft JVM/JDK is not supported.

Note #2: If a JDK is not present, only the JRE runtime, then many tasks will not work.

Installing Ant

The binary distribution of Ant consists of the following directory layout:

   +--- bin  // contains launcher scripts
   +--- lib  // contains Ant jars plus necessary dependencies
   +--- docs // contains documentation
   |      +--- ant2    // a brief description of ant2 requirements
   |      |
   |      +--- images  // various logos for html documentation
   |      |
   |      +--- manual  // Ant documentation (a must read ;-)
   +--- etc // contains xsl goodies to:
            //   - create an enhanced report from xml output of various tasks.
            //   - migrate your build files and get rid of 'deprecated' warning
            //   - ... and more ;-)
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.

Windows 95, Windows 98 & Windows ME Note:
  On these systems, the script used to launch Ant will have problems if ANT_HOME is a long filename (i.e. a filename which is not of the format known as "8.3"). This is due to limitations in the OS's handling of the "for" batch-file statement. It is recommended, therefore, that Ant be installed in a short, 8.3 path, such as C:\Ant.

On these systems you will also need to configure more environment space to cater for the environment variables used in the Ant lauch script. To do this, you will need to add or update the following line in the config.sys file

shell=c:\ c:\ /p /e:32768


Before you can run ant there is some additional set up you will need to do:

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.

Optional Tasks

Ant supports a number of optional tasks. An optional task is a task which typically requires an external library to function. The optional tasks are packaged together with the core Ant tasks.

The external libraries required by each of the optional tasks is detailed in the Library Dependencies section. These external libraries may either be placed in Ant's lib directory, where they will be picked up automatically, or made available on the system CLASSPATH environment variable.

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:\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

Unix (csh)

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


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

The supplied ant shell scripts all support an ANT_OPTS environment variable which can be used to supply extra options to ant. Some of the scripts also read in an extra script stored in the users home directory, which can be used to set such options. Look at the source for your platform's invocation script for details.

Building Ant

To build Ant from source, you can either install the Ant source distribution or checkout the 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 directory. See Library Dependencies 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) -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:

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 (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) install    (Unix)

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

build install-lite    (Windows) 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.

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 (and Java 1.4 and higher includes a regexp implementation which Ant will find automatically). You will also need to install the Ant optional jar containing the task definitions to make these tasks available. Please refer to the Installing Ant / Optional Tasks section above.

Jar Name Needed For Available At
An XSL transformer like Xalan or XSL:P style task If you use JDK 1.4, an XSL transformer is already included, so you need not do anything special.
jakarta-regexp-1.3.jar regexp type with mappers
jakarta-oro-2.0.7.jar regexp type with mappers and the perforce tasks
For the use of the FTP task together with MS FTP servers, you need CVS HEAD of commons-net and jakarta-oro after 2004-02-01 or a release of commons-net after 1.1.0 and jakarta-oro after 2.0.8
junit.jar junit tasks
xalan.jar junitreport task
stylebook.jar stylebook task CVS repository of
testlet.jar deprecated test task Build from the gzip compress tar archive in
antlr.jar antlr task
bsf.jar script task
Note: Ant 1.6 and later require Apache BSF, not the IBM version. I.e. you need BSF 2.3.0-rc1 or later.
netrexx.jar netrexx task, Rexx with the script task
js.jar Javascript with script task
If you use Apache BSF 2.3.0-rc1, you must use rhino 1.5R3 - later versions of BSF work with 1.5R4 as well.
jython.jar Python with script task
jpython.jar Python with script task deprecated, jython is the prefered engine
jacl.jar and tcljava.jar TCL with script task
BeanShell JAR(s) BeanShell with script task.
Note: Ant 1.6 and later require BeanShell version 1.3 or later
jruby.jar Ruby with script task
judo.jar Judoscript with script task
commons-logging.jar CommonsLoggingListener
log4j.jar Log4jListener
commons-net.jar ftp, rexec and telnet tasks
In order to interact successfully with a MS FTP server, you need CVS HEAD of commons-net and jakarta-oro after 2004-02-01 or a release of commons-net after 1.1.0 and jakarta-oro after 2.0.8.
bcel.jar classfileset data type, JavaClassHelper used by the ClassConstants filter reader and optionally used by ejbjar for dependency determination
mail.jar Mail task with Mime encoding, and the MimeMail task
jsse.jar Support for SMTP over TLS/SSL
in the Mail task
Already included in jdk 1.4
activation.jar Mail task with Mime encoding, and the MimeMail task
jdepend.jar jdepend task
resolver.jar 1.1beta or later xmlcatalog datatype only if support for external catalog files is desired
jsch.jar sshexec and scp tasks
JAI - Java Advanded Imaging image task
IContract icontract task
Warning : the icontract jar file contains also antlr classes.
To make the antlr task work properly, remove antlr/ANTLRGrammarParseBehavior.class from the icontract jar file installed under $ANT_HOME/lib.

Copyright © 2000-2004 The Apache Software Foundation. All rights Reserved.