Installing Apache Ant

Getting Apache Ant

The Short Story

To get up and running with the binary edition of Ant quickly, follow these steps:

1. Make sure you have a Java environment installed, See SystemRequirements for details.
2. Download Ant. See Binary Edition for details.
3. Uncompress the downloaded file into a directory.
4. Set environmental variables JAVA_HOME to your Java environment, ANT_HOME tothe directory you uncompressed Ant to, and add ${ANT_HOME}/bin (Unix) or%ANT_HOME%/bin (Windows) to your PATH. See Setup for details.
5. Optionally, from the ANT_HOME directory run ant -f fetch.xml -Ddest=system to getthe library dependencies of most of the Ant tasks that require them. If you don't do this, many of the dependentAnt tasks will not be available. See Optional Tasks for details and other optionsfor the -Ddest parameter.
6. Optionally, add any desired Antlibs. See Ant Libraries for a list.

Note that the links in the list above will give more details about each of the steps,should you need them. Or you can just continue reading the rest of this document.

1. Get the source code. See Source Edition for details.
2. Build Ant. See Building Ant for details.

For the full story, continue reading.

Binary Edition

The latest stable version of Ant is available from the Ant web page http://ant.apache.org/

The binary edition of Ant is shipped with 3 different compression formats:

1. .zip - Recommended compression format for Windows, can also be used on other platforms. Supportedby many programs and some operating systems natively.
2. .tar.gz - Uses the tar program to gather files together, and gzip to compress and uncompress.
3. .tar.bz2 - Uses the tar program to gather files together, and bzip2 to compress and uncompress..

As a binary in an RPM Package

Consult the jpackage section below.

Bundled in IDEs

All the main Java IDEs ship with Ant, products such as Eclipse, NetBeans and IntelliJ IDEA. If you install Ant this way you usually get the most recent release of Ant at the time the IDE was released. Some of the IDEs (Eclipse and NetBeans in particular) ship with extra tasks that only work if IDE-specific tools are on Ant's path. To use these on command-line versions of Ant, the relevant JARs need to be added to the command-line Ant as extra libraries/tasks. Note that if it is an IDE task or extension that is not behaving, the Ant team is unable to field bug reports. Try the IDE mailing lists first, who will cross-file bugs if appropriate.

IDE's can invariably be pointed at different Ant installations. This lets developers upgrade to a new release of Ant, and eliminate inconsistencies between command-line and IDE Ant.

Bundled in Java applications

Many Java applications, most particularly application servers, ship with a version of Ant. These are primarily for internal use by the application, using the Java APIs to delegate tasks such as JSP page compilation to the Ant runtime. Such distributions are usually unsupported by everyone. Particularly troublesome are those products that not only ship with their own Ant release, they add their own version of ANT.BAT or ant.sh to the PATH. If Ant starts behaving wierdly after installing something, try the diagnostics advice.

Source Edition

If you prefer the source edition, you can download the source for the latestAnt release fromhttp://ant.apache.org/srcdownload.cgi.If you prefer the leading-edge code, you can accessthe code as it is being developed via SVN. The Ant website has details onaccessing SVN.All bug fixes will go in against the HEAD of the source tree, and the firstresponse to many bugreps will be "have you tried the latest version".Don't be afraid to download and build a prererelease edition, as everythingother than new features are usually stable.

See the section Building Ant on how tobuild Ant from the source code.You can also access theAnt SVN repository on-line.

Archive Download Area Layout

Older versions of Ant are available in the archives at http://archive.apache.org/dist/ant/. Thefiles are organized as follows.

System Requirements

For the current version of Ant, you will also need a JDK installed onyour system, version 1.4 or later required, 1.5 or later strongly recommended.The later the version of Java , the more Ant tasks you get.

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

Note: Ant 1.8.* works with jdk1.4 and higher, Ant 1.7.* works with jdk1.3 and higher, Ant 1.6.* works with jdk 1.2 and higher, Ant 1.2 to Ant 1.5.* work with jdk 1.1 and higher.

Open Source Java Runtimes

The Ant team strongly supports users running Ant on Kaffe and other open source Java runtimes, and so strives to have a product that works well on those platforms. What appears to work well is Kaffe with Gnu Classpath and the Xerces and Xalan libraries.

Installing Ant

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

  ant   +--- README, LICENSE, fetch.xml, other text files. //basic information   +--- bin  // contains launcher scripts   |   +--- lib  // contains Ant jars plus necessary dependencies   |   +--- docs // contains documentation   |  |   |  +--- 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 ;-)

Setup

Before you can run Ant there is some additional set up youwill need to do unless you are installing the RPMversion from jpackage.org:

• Add the bin directory to your path.
• Set the ANT_HOME environment variable to thedirectory where you installed Ant. On some operating systems, Ant'sstartup scripts can guess ANT_HOME (Unix dialects andWindows NT/2000), but it is better to not rely on this behavior.
• Optionally, set the JAVA_HOME environment variable(see the Advanced section below).This should be set to the directory where your JDK is installed.

Operating System-specific instructions for doing this from the commandline are in the Windows, Linux/Unix (bash),and Linux/Unix (csh) sections. Note that using this method,the settings will only be valid for the command line session you run them in.

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

Check Installation

You can check the basic installation with opening a new shell and typing ant. Youshould get a message like this

Buildfile: build.xml does not exist!Build failed

Apache Ant version 1.7.1 compiled on June 27 2008

If this does not work ensure your environment variables are set right. They must resolve to:

• required: %ANT_HOME%inant.bat
• optional: %JAVA_HOME%injava.exe
• required: %PATH%=...maybe-other-entries...;%ANT_HOME%in;...maybe-other-entries...

Optional Tasks

Ant supports a number of optional tasks. An optional task is a task whichtypically requires an external library to function. The optional tasks arepackaged together with the core Ant tasks.

The external libraries required by each of the optional tasks is detailedin the Library Dependencies section. These externallibraries must be added to Ant's classpath, in any of the following ways:

• In ANT_HOME/lib. This makes the JAR files available to all Ant users and builds.

• In ${user.home}/.ant/lib (as of Ant 1.6). This allows different users to add new libraries to Ant. All JAR files added to this directory are available to command-line Ant.

• On the command line with a -lib parameter. This lets you add new JAR files on a case-by-case basis.

• In the CLASSPATH environment variable. Avoid this; it makes the JAR files visible to all Java applications, and causes no end of support calls. See below for details.

• In some <classpath> accepted by the task itself. For example, as of Ant 1.7.0 you can run the <junit> task without junit.jar in Ant's own classpath, so long as it is included (along with your program and tests) in the classpath passed when running the task.

  Where possible, this option is generally to be preferred, as the Ant script itself can determine the best path to load the library from: via relative path from the basedir (if you keep the library under version control with your project), according to Ant properties, environment variables, Ivy downloads, whatever you like.

If you are using the binary version of Ant, or if you are working from source code, you can easily gather most of the dependencies and install them for use with your Ant tasks. In your ANT_HOME directory you should see a file called fetch.xml. This is an Ant script that you can run to install almost all the dependencies the optional Ant tasks need.

To do so, change to the ANT_HOME directory and execute the command:

ant -f fetch.xml -Ddest=[option]

where option is one of the following, as described above:

• system - store in Ant's lib directory (Recommended)
• user - store in the user's home directory
• optional - store in Ant's source code lib/optional directory, used if building Ant source code

You may also need to set proxy settings. See the Proxy Settings section for details.

Note that not all dependencies are gathered using fetch.xml. Tasks that depend oncommercial software, in particular, will require you to have the commercial software installedin order to be used.

The Apache Ant Project also provides additional tasks and types that are available as separatelydownloaded Ant Libraries. You can see the the list of available Antlibs atthe Ant Libraries page.

You can also find tasks and types provided by third-party projects at theExternal Tools and Tasks page.

IDEs have different ways of adding external JAR files and third-party tasks to Ant. Usually it is done by some configuration dialog. Sometimes JAR files added to a project are automatically added to ant's classpath.

The CLASSPATH environment variable

The CLASSPATH environment variable is a source of many Ant support queries. Asthe round trip time for diagnosis on the Ant user mailing list can be slow, andbecause filing bug reports complaining about 'ant.bat' not working will berejected by the developers as WORKSFORME "this is a configuration problem, not abug", you can save yourself a lot of time and frustration by following somesimple steps.

1. Do not ever set CLASSPATH. Ant does not need it, it only causes confusionand breaks things.
2. If you ignore the previous rule, do not ever, ever, put quotes in theCLASSPATH, even if there is a space in a directory. This will break Ant, and itis not needed.
3. If you ignore the first rule, do not ever, ever, have a trailing backslashin a CLASSPATH, as it breaks Ant's ability to quote the string. Again, this isnot needed for the correct operation of the CLASSPATH environment variable, evenif a DOS directory is to be added to the path.
4. You can stop Ant using the CLASSPATH environment variable by setting the-noclasspath option on the command line. This is an easy wayto test for classpath-related problems.

The usual symptom of CLASSPATH problems is that ant will not run with some errorabout not being able to find org.apache.tools.ant.launch.Launcher, or, if you have got thequotes/backslashes wrong, some very weird Java startup error. To see if this isthe case, run ant -noclasspath or unset the CLASSPATH environmentvariable.

You can also make your Ant script reject this environmentvariable just by placing the following at the top of the script (or in an init target):

<property environment="env."/><property name="env.CLASSPATH" value=""/><fail message="Unset $CLASSPATH / %CLASSPATH% before running Ant!"> <condition> <not> <equals arg1="${env.CLASSPATH}" arg2=""/> </not> </condition></fail>

Proxy Configuration

Many Ant built-in and third-party tasks use network connections to retrievefiles from HTTP servers. If you are behind a firewall with a proxy server, thenAnt needs to be configured with the proxy. Here are the different ways to dothis.

• With Java1.5
  

  When you run Ant on Java1.5, you could try to use the automatic proxy setupmechanism with -autoproxy.

• With explicit JVM properties.
  

  These are documented by Oracle,and control the proxy behaviour of the entire JVM. To set them in Ant, declarethem in the ANT_OPTS environment variable. This is the best optionfor a non-mobile system. For a laptop, you have to change these settings as youroam. To set ANT_OPTS:

  For csh/tcsh:

   setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"

  For bash:

   export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"

  For Windows, set the environment variable in the appropriate dialog box and open a new console. or, by hand

   set ANT_OPTS = -Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080

• In the build file itself
  

  If you are writing a build file that is always to be used behind the firewall,the <setproxy> task lets you configure the proxy (which it does by settingthe JVM properties). If you do this, we strongly recommend using ant propertiesto define the proxy host, port, etc, so that individuals can override thedefaults.

The Ant team acknowledges that this is unsatisfactory. Until the JVMautomatic proxy setup works properly everywhere, explicit JVM options viaANT_ARGS are probably the best solution. Setting properties on Ant'scommand line do not work, because those are Ant properties being set, notJVM options. This means the following does not set up the command line:

ant -Dhttp.proxyHost=proxy -Dhttp.proxyPort=81

All it does is set up two Ant properties.

One other troublespot withproxies is with authenticating proxies. Ant cannot go beyond what the JVM doeshere, and as it is very hard to remotely diagnose, test and fix proxy-relatedproblems, users who work behind a secure proxy will have to spend much timeconfiguring the JVM properties until they are happy.

Windows and OS/2

Assume Ant is installed in c:ant. The following sets up theenvironment:

set ANT_HOME=c:antset JAVA_HOME=c:jdk-1.5.0.05set PATH=%PATH%;%ANT_HOME%in

Linux/Unix (bash)

Assume Ant is installed in /usr/local/ant. The following sets upthe environment:

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

Linux/Unix (csh)

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

Having a symbolic link set up to point to the JVM/JDK version makes updates more seamless.

RPM version from jpackage.org

The JPackage project distributes an RPM version of Ant.With this version, it is not necessary to set JAVA_HOME or ANT_HOME environment variables and the RPM installer will correctlyplace the Ant executable on your path.

NOTE: Since Ant 1.7.0, if the ANT_HOME environment variable is set, the jpackage distribution will be ignored.

Optional jars for the JPackage version are handled in two ways. The easiest, andbest way is to get these external libraries from JPackage if JPackage has themavailable. (Note: for each such library, you will have to get both the externalpackage itself (e.g. oro-2.0.8-2jpp.noarch.rpm) and the small library that linksant and the external package (e.g. ant-apache-oro-1.6.2-3jpp.noarch.rpm).

However, JPackage does not package proprietary software, and since some of theoptional packages depend on proprietary jars, they must be handled as follows.This may violate the spirit of JPackage, but it is necessary if you need these proprietary packages.For example, suppose you want to install support for netrexx, which jpackage does notsupport:

1. Decide where you want to deploy the extra jars. One option is in $ANT_HOME/lib,which, for JPackage is usually /usr/share/ant/lib. Another, less messy optionis to create an .ant/lib subdirectory of your home directory and place yournon-jpackage ant jars there, thereby avoiding mixing jpackagelibraries with non-jpackage stuff in the same folder.More information on where Ant finds its libraries is availablehere
2. Download a non-jpackage binary distribution from the regular Apache Ant site
3. Unzip or untar the distribution into a temporary directory
4. Copy the linking jar, in this case ant-jai.jar, into the library directory youchose in step 1 above.
5. Copy the proprietary jar itself into the same directory.

Finally, if for some reason you are running on a system with both the JPackage and Apache versions of Antavailable, if you should want to run the Apache version (which will have to be specified with an absolute file name,not found on the path), you should use Ant's --noconfig command-line switch to avoid JPackage's classpath mechanism.

Advanced

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

• The classpath for Ant must contain ant.jar and any jars/classesneeded for your chosen JAXP-compliant XML parser.
• When you need JDK functionality(such as for the javac task or thermic task), then tools.jarmust be added. The scripts supplied with Ant,in the bin directory, will addthe required JDK classes automatically, if the JAVA_HOMEenvironment variable is set.
• When you are executing platform-specific applications, such as theexec task or thecvs task, the property ant.homemust be set to the directory containing where you installed Ant. Againthis is set by the Ant scripts to the value of the ANT_HOME environmentvariable.

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

---

Building Ant

To build Ant from source, you can either install the Ant source distributionor checkout the ant module from SVN. See Source Edition for details.

Once you have installed the source, change into the installationdirectory.

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

Note: The bootstrap process of Ant requires a greedycompiler like Sun's javac or jikes. It does not work with gcj orkjc.

Make sure you have downloaded any auxiliary jars required tobuild tasks you are interested in. These should beadded to the lib/optionaldirectory of the source tree.See Library Dependenciesfor a list of JAR requirements for various features.Note that this will make the auxiliary JARavailable for the building of Ant only. For running Ant you willstill need tomake the JARs available as described underInstalling Ant.

You can also get most of the auxiliary jar files (ie. the jar filesthat various optional Ant tasks depend on) by running Ant on thefetch.xml build file. See OptionalTasks for instructions on how to do this.

As of version 1.7.0 Ant has a hard dependency on JUnit. The fetch.xml build script will download JUnit automatically, but if you don't use this you must install it manually into lib/optional (download it from JUnit.org) if you are using a source distribution of Ant.

Your are now ready to build Ant:

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

sh 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 manualcompilation of enough Ant code to be able to run Ant. The bootstrapped Ant isused for the remainder of the build steps.
• Invokes the bootstrapped Ant with the parameters passed to the build script. Inthis case, these parameters define an Ant property value and specify the "dist" targetin Ant's own build.xml file.
• Create the ant.jar and ant-launcher.jar JAR files
• Create optional JARs for which the build had the relevant libraries. Ifa particular library is missing from ANT_HOME/lib/optional, then the matchingant- JAR file will not be created. For example, ant-junit.jar is only builtif there is a junit.jar in the optional directory.

On most occasions you will not need to explicitly bootstrap Ant since the buildscripts do that for you. If however, the build file you are using makes use of featuresnot 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_HOMEdirectory, you can use:

build install    (Windows)

sh build.sh install    (Unix)

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

build install-lite    (Windows)

sh build.sh install-lite    (Unix)

This will only install the bin and lib directories.

Both the install andinstall-lite targets will overwritethe current Ant version in ANT_HOME.

Ant's build script will try to set executable flags for its shell scripts on Unix-like systems. There are various reasons why the chmod-task might fail (like when you are running the build script as a different user than the one who installed Ant initially). In this case you can set the Ant property chmod.fail to false when starting the build like in

sh build.sh install -Dchmod.fail=false

and any error to change permission will not result in a build failure.

---

Library Dependencies

The following libraries are needed in Ant's classpathif you are using theindicated feature. Note that only one of the regexp libraries isneeded for use with the mappers(and Java includes a regexp implementation whichAnt will find automatically).You will also need to install the particularAnt optional jar containing the task definitions to make thesetasks available. Please refer to the Installing Ant / Optional Tasks section above.

Jar Name	Needed For	Available At
jakarta-regexp-1.3.jar	regexp type with mappers (if you do not wish to use java.util.regex)	http://attic.apache.org/projects/jakarta-regexp.html
jakarta-oro-2.0.8.jar	regexp type with mappers (if you do not wish to use java.util.regex) and the Perforce tasks To use the FTP task,you need jakarta-oro 2.0.8 or later, and commons-net	http://attic.apache.org/projects/jakarta-oro.html
junit.jar	<junit> task. May be in classpath passed to task rather than Ant's classpath.	http://www.junit.org/
xalan.jar	junitreport task	http://xml.apache.org/xalan-j/
antlr.jar	antlr task	http://www.antlr.org/
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. Note: BSF 2.4.0 is needed to use a post 1.5R3 version of rhino's javascript. Note: BSF 2.4.0 uses jakarata-commons-logging so it needs the commons-logging.jar.	http://jakarta.apache.org/bsf/
Groovy jars	Groovy with script and scriptdef tasks You need to get the groovy jar and two asm jars from a groovy installation. The jars are groovy-[version].jar, asm-[vesion].jar and asm-util-[version].jar and antlr-[version].jar. As of groovy version 1.0-JSR-06, the jars are groovy-1.0-JSR-06.jar, antlr-2.7.5.jar, asm-2.2.jar and asm-util-2.2.jar. Alternatively one may use the embedded groovy jar file. This is located in the embedded directory of the groovy distribution. This bundles all the needed jar files into one jar file. It is called groovy-all-[version].jar.	http://groovy.codehaus.org/ The asm jars are also available from the creators of asm - http://asm.objectweb.org/
netrexx.jar	netrexx task, Rexx with the script task	http://www.ibm.com/software/awdtools/netrexx/download.html
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 (e.g. version 2.4.0) work with 1.5R4 and higher).	http://www.mozilla.org/rhino/
jython.jar	Python with script task Warning : jython.jar also contains classes from jakarta-oro. Remove these classes if you are also using jakarta-oro.	http://jython.sourceforge.net/
jpython.jar	Python with script task deprecated, jython is the prefered engine	http://www.jpython.org/
jacl.jar and tcljava.jar	TCL with script task	http://www.scriptics.com/software/java/
BeanShell JAR(s)	BeanShell with script task. Note: Ant requires BeanShell version 1.3 or later	http://www.beanshell.org/
jruby.jar	Ruby with script task	http://jruby.org/
judo.jar	Judoscript with script task	http://www.judoscript.org/
commons-logging.jar	CommonsLoggingListener	http://commons.apache.org/logging/
log4j.jar	Log4jListener	http://logging.apache.org/log4j/
commons-net.jar	ftp, rexec and telnet tasks jakarta-oro 2.0.8 or later is required together with commons-net 1.4.0. For all users, a minimum version of commons-net of 1.4.0 is recommended. Earlier versions did not support the full range of configuration options, and 1.4.0 is needed to compile Ant.	http://commons.apache.org/net/
bcel.jar	classfileset data type, JavaClassHelper used by the ClassConstants filter reader and optionally used by ejbjar for dependency determination	http://commons.apache.org/bcel/
mail.jar	Mail task with Mime encoding, and the MimeMail task	http://www.oracle.com/technetwork/java/index-jsp-139225.html
activation.jar	Mail task with Mime encoding, and the MimeMail task	http://www.oracle.com/technetwork/java/javase/jaf-135115.html
jdepend.jar	jdepend task	http://www.clarkware.com/software/JDepend.html
resolver.jar 1.1beta or later	xmlcatalog datatype only if support for external catalog files is desired	http://xml.apache.org/commons/.
jsch.jar 0.1.42 or later	sshexec and scp tasks	http://www.jcraft.com/jsch/index.html
JAI - Java Advanced Imaging	image task	https://jai.dev.java.net/

Troubleshooting

Diagnostics

Ant has a built in diagnostics feature. If you run ant-diagnostics ant will look at its internal state and print it out. Thiscode will check and print the following things.

• Where Ant is running from. Sometimes you can be surprised.
• The version of ant.jar and of the ant-*.jar containing the optional tasks - and whether they match
• Which JAR files are in ANT_HOME/lib
• Which optional tasks are available. If a task is not listed as beingavailable, either it is not present, or libraries that it depends on areabsent.
• XML Parser information
• JVM system properties
• The status of the temp directory. If this is not writeable, or its clock ishorribly wrong (possible if it is on a network drive), a lot of tasks will failwith obscure error messages.
• The current time zone as Java sees it. If this is not what it should be foryour location, then dependency logic may get confused.

Running ant -diagnostics is a good way to check that ant is installed. It is also a first step towards self-diagnosis of any problem. Any configuration problem reported to the user mailing list will probably result ins someone asking you to run the command and show the results, so save time by using it yourself.

For under-IDE diagostics, use the <diagnostics> task to run the same tests as an ant task. This can be added to a diagnostics target in a build file to see what tasks are available under the IDE, what the XML parser and classpath is, etc.

user mailing list

If you cannot get Ant installed or working, the Ant user mailing list is thebest place to start with any problem. Please do your homework first, make surethat it is not a CLASSPATH problem, and run a diagnostics check to see what Ant thinks of its ownstate. Why the user list, and not the developer list?Because there are more users than developers, so more people who can help you.

Please only file a bug report against Ant for a configuration/startup problem ifthere really is a fixable bug in Ant related to configuration, such as it notworking on a particular platform, with a certain JVM version, etc, or if you areadvised to do it by the user mailing list.

 
» Authors         » The Apache Software Foundation