Ant: Installation

Ant 1.10 needs a JDK of version 8 or later to run. A JRE is enough to start Ant, but then many tasks do not work, because they need classes that only a JDK carries (javac, javadoc, jar signing tools). The manual lists Linux, Unix flavours such as Solaris and HP-UX, macOS, Windows NT descendants, OS/2 Warp, Novell Netware 6 and OpenVMS as platforms where Ant has been used; the ones used most for development are Linux, macOS, Windows and Unix. Windows 9x has not been supported since Ant 1.7. The Java floors of the older lines (1.9: Java 5, 1.8: 1.4, 1.7: 1.3, 1.6: 1.2) and the JDK releases that removed features Ant had to follow are in the history page.

The Java that runs Ant is not the Java that compiles your project: the javac task can pass release, source and target to compile for an older platform, and the java task can fork a different JVM. That separation is why the Running Ant page distinguishes JAVA_HOME (the JVM that runs Ant) from the toolchain a build chooses for itself. Maven has toolchains for the same purpose and Gradle has toolchains with automatic provisioning; Ant has no equivalent, so a build that needs a specific JDK passes it to the tasks explicitly.

Source: Ant manual: System Requirements

Ant publishes two checks for each archive, and the PGP signature is the one to trust. Take the .asc file and KEYS from the main distribution directory, not from a mirror. The steps below were run on the Ant 1.10.18 .tar.gz, with a throwaway GNUPGHOME so the check leaves your keyring alone. The .sha512 file holds the bare digest with no file name (see the Supply-Chain Security page for the shasum -c form and for the tampered-file counter-example); here the digest is compared directly.

"Good signature" with the "not certified" warning is the expected result of a fresh keyring: the signature is valid for a key that appears in KEYS, and the warning says that you have not told GnuPG to trust that key. The question left is how you came to trust KEYS; fetching it over HTTPS from downloads.apache.org and comparing the fingerprint with the Apache web of trust is the stronger route. Because this verification used the KEYS file that came inside the archive itself, it proves the archive is internally consistent, not that it is genuine. Do it with the file from the main distribution directory for a real check.

The SBOM that ships in the archive is covered in the supply-chain page (26 CycloneDX JSON files, one for each JAR in lib).

Source: Apache Ant: Binary Distributions, Verify Releases

Choose a directory, unpack the archive there, and call that directory ANT_HOME. The distribution unpacked here is 44 MB on disk:

(The listing is of the real 1.10.18 archive; /opt is the manual-style location, and the run extracted into a scratch directory.)

Only bin and lib are required to run Ant; the rest can be left out of a minimal copy, for example in a container image. The JAR files in lib look redundant until you remember that each optional task has a JAR of its own: ant-jsch.jar holds the scp and sshexec tasks and needs the JSch library, which is not in the distribution, and the same pattern repeats for ant-commons-net.jar (FTP), ant-junitlauncher.jar (JUnit Platform), ant-xz.jar and the others. The next sections show what that means.

Source: Ant manual: Installing Ant

Three environment variables matter, and only one is required in practice.

The manual’s snippets for each shell are below (/usr/local/ant and the JDK 11 paths are its example values):

These settings last only for the shell session you type them in; put them in a profile file (or, on Windows, in the system environment dialog) to make them permanent. The Windows batch file expects ANT_HOME and JAVA_HOME to be set without quotes and without a trailing \ or /, and CLASSPATH to be unset or empty; since Ant 1.10.16, ant.bat exits with a non-zero status if ANT_HOME is not set. A symbolic link such as /usr/local/jdk pointing at the current JDK makes updates easier. Do not install ant.jar into the lib/ext directory of a JDK: Ant is an application, and extension classes are subject to security restrictions (the directory does not exist on current JDKs anyway). None of the Windows snippets was run here ("not run here"); they are the manual’s.

The commands below were run: a clean copy of Ant 1.10.18 reached through a symbolic link on the PATH, with ANT_HOME unset (the script resolved the link and guessed ANT_HOME), and then with JAVA_HOME pointing at two other JDKs. The build file is a four-line probe that prints what Ant knows about itself:

The first line is the output of -version; the three ant.home lines are the three places where the diagnostics report prints the home. The last block is the echo lines of the two JAVA_HOME runs, with the Buildfile and BUILD SUCCESSFUL lines left out. The probe is the same in all runs, which is the point: one Ant directory, three JVMs, chosen by JAVA_HOME alone.

When the Java cannot be found, the launcher script (not Ant) prints its own message and exits with status 1. Both JAVA_HOME and JAVACMD (the full path of the java executable, which wins over JAVA_HOME) were tried with a wrong value:

Source: Ant manual: Setup

A new shell and two commands are the check the manual proposes. With no build file in the directory, Ant reports it and exits with status 1; that failure proves Ant itself started:

If either fails, the manual’s checklist is the right one: ANT_HOME must resolve to the directory that contains bin/ant (%ANT_HOME%\bin\ant.bat on Windows), JAVA_HOME is optional but must contain bin/java when set, and PATH must contain ANT_HOME/bin. The manual’s own example output shows version 1.9.2 from 2013; the 1.10.18 text above replaces it.

Source: Ant manual: Check Installation

Ant needs libraries in two situations: its own optional tasks need third-party JARs, and your build needs JARs for tasks it defines (taskdef, antlibs, a test framework). There are five places, in the order the manual lists them:

The -lib option and the -nouserlib and -noclasspath switches that turn two of these off are described in Running Ant. The difference between the places is easy to see with ant -diagnostics. A clean copy of Ant 1.10.18 has no JSch, so the tasks that depend on it are listed as missing. The same Ant is then run with a home directory that has .ant/lib/jsch-0.1.55.jar (the home was moved with -Duser.home through ANT_OPTS, so that the real home was not touched), then with -nouserlib, and then with -lib pointing at the same directory:

The first block is the clean installation: seven tasks are missing. The second has the JAR in the user library directory, and sshsession, scp and sshexec are now available (the USER_HOME/.ant/lib jar listing section is printed too). With -nouserlib the output was identical to the first block, and with -lib it was identical to the second (the listing of the user directory is the only difference): the library location changes what the one run can load, and that is the whole mechanism.

Source: Ant manual: Optional Tasks

An optional task is one whose implementation needs an external library. The task classes ship in the distribution (the ant-*.jar files in lib), the library does not. If the library is missing, Ant cannot create the task, and says so with a message that is worth recognising. The build below uses scp against localhost with a key file that does not exist (nothing connects anywhere):

The message names the missing class, the three places to put the JAR, and tells you that this is a configuration problem. With JSch on the path (the Ant copy used for the next section), the same build file fails later and differently, which shows that the task now loads:

The diag target is the build-file form of ant -diagnostics: the diagnostics task prints the same report from inside a build, which is what you want when asking how Ant behaves under an IDE.

Source: Apache Ant manual: Library Dependencies and SCP

Every task and thread in Ant’s JVM shares one HTTP, FTP and SOCKS proxy configuration. A get, an XSL task that fetches a stylesheet by URL, an Ivy resolver and any third-party task that uses java.net.URL are all affected, and a build that works at home can hang behind a corporate firewall. The only way to fix it is to configure the JVM, and the manual gives four ways:

Setting a property on Ant’s own command line does not work, because -D defines an Ant property, not a JVM system property. That is easy to demonstrate, with a tiny class that prints the JVM property and a build file that runs it inside Ant’s JVM (the proxy host is a placeholder that does not exist):

The three blocks are the results of the three commands (the second and third show only the line of interest). The first prints null: -D defined an Ant property named http.proxyHost (it appears in <echoproperties/>), and no JVM property. ANT_OPTS and setproxy set the real JVM property. The diagnostics report has a "Java1.5+ proxy settings" section that also shows the system properties: with ANT_OPTS set, http.proxyHost and http.proxyPort were listed there. -autoproxy was run too and reported "Direct connection", which is the correct answer for a machine with no system proxy; the behaviour behind a real proxy was not run here ("not run here").

The manual is candid about the limits: Ant cannot go beyond what the JVM does for authenticating proxies, and diagnosing them remotely is hard, so users behind a secure proxy have to spend time with the JVM properties until they work. The Maven Resolver Ant Tasks and Ivy have their own proxy settings in addition to the JVM’s (a <proxy> type in the first, the credentials and settings elements in the second); the Maven Resolver Ant Tasks page covers them. In Maven the equivalent is the <proxies> element of settings.xml, and in Gradle the systemProp.http.proxyHost properties of gradle.properties.

Source: Ant manual: Proxy Configuration

Source: Ant manual: Proxy Configuration (full page)

Source: Ant manual: the setproxy task

ant -diagnostics prints a report of Ant’s view of itself, and is the first thing the user mailing list will ask you for. It checks and prints, in this order: where Ant runs from, the version of ant.jar and of the ant-*.jar files and whether they match, the JARs in ANT_HOME/lib and in the user’s library directory, the optional tasks that are available and the ones that are not (with the missing class), the XML parser and the XSLT processor, whether symbolic links can be created, the JVM system properties, the temporary directory (an unwritable one, or one with a wrong timestamp, gives obscure failures in many tasks), the locale and time zone as Java sees them (a wrong zone confuses dependency checks), and the proxy settings. An excerpt of the run on a clean 1.10.18:

The report also lists the Is this ... VM? lines that belong to Java environments of the 2000s; they are always "no" today. Use ant -diagnostics to answer "which Ant is this" (the ant.home line catches the bundled copies mentioned above), "which Java" and "does this task have its library". From inside a build, or from an IDE, add the diagnostics task to a target. The temporary-directory and time-zone checks are the ones that surprise people: a network drive as the temporary directory is a classic cause of tasks that fail only on one machine.

Source: Ant manual: Troubleshooting, Diagnostics

Source: Ant manual: the diagnostics task

Ant needs no registration, so keeping several versions is a matter of directories. A practical layout is one unpacked directory per version (/opt/apache-ant-1.10.17, /opt/apache-ant-1.10.18), a symbolic link /opt/ant to the one in use, and PATH containing /opt/ant/bin. That works because the launcher script resolves the link to find ANT_HOME (the first run in this page’s setup section shows it). To try a new release for one command, call its bin/ant by full path. The manual adds that IDEs can be pointed at a different Ant, which removes the inconsistency between the command line and the IDE, and the packaged-JPackage case: to run an Apache Ant from a machine that also has a JPackage Ant, use its full path and pass --noconfig to the script.

Upgrading within the 1.10 line is a matter of unpacking the new release and reading the "changes that could break older environments" part of its release notes, which the history page summarises for each release since 1.10.0. Libraries added to ANT_HOME/lib by fetch.xml live in the old directory and must be added again (or, better, moved to ~/.ant/lib or to the build). The lib directory is therefore a poor place for libraries you care about; it is wiped by the next upgrade, whereas the user directory is not.

The messages in the first three rows were produced by the runs above. The rest of the cause and fix columns repeat the manual.

The install-time choices have effects later in the series. The optional libraries decide which test tasks work (see Testing with JUnit & junitlauncher); the library locations decide how build files find the antlibs that Antlibs & Namespaces introduces; the proxy settings decide whether the dependency managers of Ivy Settings & Resolvers can reach Maven Central. The book Java Development with Ant (Manning, 2002) was written for Ant 1.5; its installation advice predates -lib, ~/.ant/lib, fetch.xml, JDK 9 and later, and the Resolver Ant Tasks.