# Installing Ant

## Getting Ant

### Binary Edition

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

### 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 non 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 latest Ant release from http://ant.apache.org/srcdownload.cgi. If you prefer the leading-edge code, you can access the code as it is being developed via SVN. The Ant website has details on accessing SVN. All bug fixes will go in against the HEAD of the source tree, and the first response to many bugreps will be "have you tried the latest version". Don't be afraid to download and build a prererelease edition, as everything other than new features are usually stable.

See the section Building Ant on how to build Ant from the source code. You can also access the Ant SVN 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 NT-platforms, OS/2 Warp, Novell Netware 6, OpenVMS and MacOS X. The platforms used most for development are, in no particular order, Linux, MacOS X, Windows XP and Unix; these are therefore that platforms that tend to work best. As of Ant1.7, Windows 9x is no longer supported.

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

The binary distribution of Ant includes the latest version of the Apache Xerces2 XML parser. Please see http://java.sun.com/xml/ 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 of your preferred parser into Ant's `lib` directory or put the jars on the system classpath. Some parts of Ant will fail if you use an old parser, especially one that is not namespace-aware. In particular, avoid the Crimson parser.

Tip: "ant -diagnostics" will list the XML parser used and its location.

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

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

### 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 ;-)

Only the `bin` and `lib` directories are required to run Ant. To install Ant, choose a directory and copy the distribution files 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:\command.com c:\ /p /e:32768`

### Setup

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

- Add the `bin` directory to your path.
- Set the `ANT_HOME` environment variable to the directory where you installed Ant. On some operating systems, Ant's startup scripts can guess `ANT_HOME` (Unix dialects and Windows 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.

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 Note:
| The ant.bat script makes use of three environment variables - ANT_HOME, CLASSPATH and JAVA_HOME. Ensure that ANT_HOME and JAVA_HOME variables are set, and that they do not have quotes (either ' or ") and they do not end with \ or with /. CLASSPATH should be unset or empty.

### Check Installation

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

    Buildfile: build.xml does not exist!
    Build failed

So Ant works. This message is there because you need to write an individual buildfile for your project. With a `ant -version` you should get an output like

    Apache Ant version 1.7.0 compiled on December 13 2006

### 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 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 `/home/kev/.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.

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. As the round trip time for diagnosis on the Ant user mailing list can be slow, and because filing bug reports complaining about 'ant.bat' not working will be rejected by the developers as WORKSFORME "this is a configuration problem, not a bug", you can save yourself a lot of time and frustration by following some simple steps.

1. Do not ever set `CLASSPATH`. Ant does not need it, it only causes confusion and breaks things.
2. If you ignore the previous rule, do not ever, ever, put quotes in the `CLASSPATH`, even if there is a space in a directory. This will break Ant, and it is not needed.
3. If you ignore the first rule, do not ever, ever, have a trailing backslash in a `CLASSPATH`, as it breaks Ant's ability to quote the string. Again, this is not needed for the correct operation of the `CLASSPATH` environment variable, even if 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 way to test for classpath-related problems.

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

You can also make your Ant script reject this environment variable 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 retrieve files from HTTP servers. If you are behind a firewall with a proxy server, then Ant needs to be configured with the proxy. Here are the different ways to do this.

- With Java1.5
  When you run Ant on Java1.5, you could try to use the automatic proxy setup mechanism with `-autoproxy`.
- With explicit JVM properties.
  These are documented by Sun, and control the proxy behaviour of the entire JVM. To set them in Ant, declare them in the `ANT_OPTS` environment variable. This is the best option for a non-mobile system. For a laptop, you have to change these settings as you roam.
- In the build file itself
  If you are writing an build file that is always to be used behind the firewall, the <setproxy> task lets you configure the proxy (which it does by setting the JVM properties). If you do this, we strongly recommend using ant properties to define the proxy host, port, etc, so that individuals can override the defaults.

The Ant team acknowledges that this is unsatisfactory. Until the JVM automatic proxy setup works properly everywhere, explicit JVM options via ANT_ARGS are probably the best solution. Setting properties on Ant's command line do not work, because those are Ant properties being set, not JVM 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 with proxies is with authenticating proxies. Ant cannot go beyond what the JVM does here, and as it is very hard to remotely diagnose, test and fix proxy-related problems, users who work behind a secure proxy will have to spend much time configuring the JVM properties until they are happy.

### 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 )

Having a symbolic link set up to point to the JVM/JSK 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 correctly place 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, and best way is to get these external libraries from JPackage if JPackage has them available. (Note: for each such library, you will have to get both the external package itself (e.g. `oro-2.0.8-2jpp.noarch.rpm`) and the small library that links ant 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 the optional 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 starteam, which jpackage does not support:

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 option is to create an `.ant/lib` subdirectory of your home directory and place your non-jpackage ant jars there, thereby avoiding mixing jpackage libraries with non-jpacakge stuff in the same folder. More information on where Ant finds its libraries is available here
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-starteam.jar`, into the library directory you chose 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 Ant available, 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 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 `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.

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 SVN.

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.

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

Make sure you have downloaded any auxiliary jars required to build tasks you are interested in. These should be added to the `lib/optional` directory of the source tree. See Library Dependencies for a list of JAR requirements for various features. Note that this will make the auxiliary JAR 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)

> `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 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.
- Create the ant.jar and ant-launcher.jar JAR files
- Create optional JARs for which the build had the relevant libraries. If a particular library is missing from ANT_HOME/lib/optional, then the matching ant- JAR file will not be created. For example, ant-junit.jar is only built if there is a junit.jar in the optional directory.

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)

> `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` and `install-lite` targets will overwrite the current Ant version in `ANT_HOME`.

## Library Dependencies

The following libraries are needed in Ant's classpath 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 particular 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 | style task | If you use JDK 1.4+, an XSL transformer is already included, so you need not do anything special. XALAN : http://xml.apache.org/xalan-j/index.html
jakarta-regexp-1.3.jar | regexp type with mappers | http://jakarta.apache.org/regexp/
jakarta-oro-2.0.8.jar | regexp type with mappers and the perforce tasks To use the FTP task, you need jakarta-oro 2.0.8 or later, and commons-net | http://jakarta.apache.org/oro/
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/
stylebook.jar | stylebook task | SVN repository of http://xml.apache.org/svn.html
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.sourceforge.net/
judo.jar | Judoscript with script task | http://www.judoscript.com/index.html
commons-logging.jar | CommonsLoggingListener | http://jakarta.apache.org/commons/logging/index.html
log4j.jar | Log4jListener | http://jakarta.apache.org/log4j/docs/index.html
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://jakarta.apache.org/commons/net/index.html
bcel.jar | classfileset data type, JavaClassHelper used by the ClassConstants filter reader and optionally used by ejbjar for dependency determination | http://jakarta.apache.org/bcel/
mail.jar | Mail task with Mime encoding, and the MimeMail task | http://java.sun.com/products/javamail/
jsse.jar | Support for SMTP over TLS/SSL in the Mail task Already included Java 1.4+ | http://java.sun.com/products/jsse/
activation.jar | Mail task with Mime encoding, and the MimeMail task | http://java.sun.com/products/javabeans/glasgow/jaf.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.29 or later | sshexec and scp tasks | http://www.jcraft.com/jsch/index.html
JAI - Java Advanced Imaging | image task | http://java.sun.com/products/java-media/jai/
Starteam SDK | Starteam version management tasks | http://www.borland.com/downloads/download_starteam.html

## 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. This code 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 being available, either it is not present, or libraries that it depends on are absent.
- XML Parser information
- JVM system properties
- The status of the temp directory. If this is not writeable, or its clock is horribly wrong (possible if it is on a network drive), a lot of tasks will fail with obscure error messages.
- The current time zone as Java sees it. If this is not what it should be for your 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 the best place to start with any problem. Please do your homework first, make sure that it is not a `CLASSPATH` problem, and run a diagnostics check to see what Ant thinks of its own state. 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 if there really is a fixable bug in Ant related to configuration, such as it not working on a particular platform, with a certain JVM version, etc, or if you are advised to do it by the user mailing list.