Appendix A. Installation
If there is one area where Ant could be improved, it’s in the area of installation. It still has a fairly manual installation process, and a few things can go wrong. Here’s a summary of how to install Ant, and also a troubleshooting guide in case something goes awry.
Before you begin
Before installing Ant, check that a Java SE Software Development Kit, otherwise known as JDK, is installed on the target system. Type javac at a command prompt; if a usage message doesn’t appear, then either a JDK needs to be installed or the PATH environment variable path isn’t set up correctly. Sun distributes their versions under http://java.sun.com/javase/—you need to download the appropriate JDK for your system.
On Windows, install the JDK on a path without spaces in it, such as c:javajdk, instead of a path such as C:Program FilesJava. Spaces in paths can confuse Ant and other programs.
After installing the JDK, Ant requires the environment variable JAVA_HOME to be set to the directory into which it was installed. You should also append JAVA_HOMEin to the PATH environment variable, so that you can run the SDK’s programs from the command line. Some Ant tasks depend on this, since they run these programs.
The steps to install Ant
The core stages of the Ant installation process are the same regardless of the platform:
1. Download Ant.
2. Unzip or untar it into a directory.
3. Set up some environment variables to point to the JDK and Ant.
4. Add Ant’s bin directory to the command line path.
5. Add any optional libraries to Ant that you desire or need. (This can be done later.)
The exact details vary from platform to platform, and as Ant works to varying degrees on everything from laptops to mainframes, it isn’t possible to cover all the possible platforms you may want to install Ant onto; instead we’ll cover only the Windows and Unix/Linux platforms.
Ant distributions come as source or binary distributions. Binary distributions should work out of the box, whereas source editions need to be built using the Ant bootstrap scripts. It’s probably safest to hold off getting the source editions until chapters 17 and 18, when we look at extending Ant’s Java code.
When downloading a binary version, get either the latest release build, or a beta release of the version about to be released. Nightly builds are incomplete and built primarily as a test, rather than for public distribution.
Setting up Ant on Windows
Download the binary distribution zip file from http://ant.apache.org/ to your local disk. Then unzip it to where you want the files to live, making sure that the unzip tool preserves directory structure. The jar tool built into the JDK can expand the archive:
jar xvf apache-ant-1.7.0-bin.zip
Let’s assume you unzipped it to c:javaant. This new directory you’ve created and installed Ant into is called “Ant home.”
You should add the bin subdirectory, here c:javaantin, to the end of the Path environment variable so Ant can be called from the command line. You also should set the ANT_HOME environment variable to point to the Ant home directory. The batch file that starts Ant can usually just assume that ANT_HOME is one directory up from where the batch file lives, but sometimes it’s nice to know for sure.
You can set environment variables in the “system” section of the control panel, in its “Advanced” tab pane, under “Environment Variables....” This dialog is somewhat cramped and noticeably less usable than a text file, but such is progress. After closing the dialog box, any new console windows or applications started should pick up the altered settings. You can check by typing SET at the command prompt, which should include lines like the following:
ANT_HOME=C:JavaApacheAnt JAVA_HOME=C:Javajdk Path=C:WINDOWSsystem32;C:WINDOWS;C:Javajdkin;C:JavaAntin
If these variables aren’t set, try logging out and in again.
This is also a good time to check that the CLASSPATH environment variable isn’t set. If it is, all JAR files listed in it get picked up by Ant, which can cause confusion. If there’s a quote inside the CLASSPATH, or if it ends in a backslash, Ant will fail with an obscure error. This variable has made both mistakes:
CLASSPATH="C:Program FilesJARSxerces.jar";c:projectclasses
The correct setting—if it has to be used at all—would be
CLASSPATH=C:Program FilesJARSxerces.jar;c:projectclasses
As we said, you shouldn’t need this at all. It only confuses Ant and other Java programs.
To test that Ant is installed, type ant -version at a newly opened console. The result should be the version of Ant that’s installed:
Apache Ant version 1.7.0 compiled on December 13 2006
The printed version number must match that of the version you’ve just downloaded; anything else means there’s still a problem.
Setting up Ant on Unix
The first step to running Ant on a Unix/Linux system is to install a JDK. Ant works best with an official Sun JDK. The Kaffe and Classpath projects provide a runtime that’s good for running code, but the official JDK is still best for development. Sun provides the JDK at http://java.sun.com/.
Many Linux distributions provide a packaged distribution, such as an RPM or .deb file. Those that are created by the JPackage team at http://www.jpackage.org/ are the best; they integrate the installation with the operating system’s library management tools. Their web site shows how you can use yum or apt to subscribe to their releases. Sun provides RPM packages that are not fully compatible with JPackage installations.
With JPackage, the JDK will be installed somewhere like /usr/lib/jvm/jdk_sun_1.5.10; with a Sun RPM, the destination is something like /usr/java/jdk_1.5.10. To stop this value from changing every time you update the JDK, set up a symbolic link, such as /usr/lib/jvm/jdk, to point to the JDK you want to use. Then set up the login scripts of yourself—or all users in the system—to have the JAVA_HOME environment variable set to this location. In the bash script language, it would be something like
export JAVA_HOME=/usr/lib/jvm/jdk
You should also add the bin subdirectory of the JDK to the PATH environment variable.
To test for the JDK, you should try running java first:
> java -version java version "1.5.0_06" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_10) Java HotSpot(TM) Client VM (build 1.5.0_10, mixed mode, sharing)
If this picks up another Java runtime from the one you’ve just installed, then you have an existing runtime installed somewhere. Uninstall it and try again.
Once java works, check that javac is on the command line, as is tnameserv. The latter is available only if the JDK’s bin directory is on the path. If it’s found, the JDK is installed, and it’s time to install Ant.
As with the JDK, the JPackage team provides a version of Ant. You can install it and have it set up Ant to work from the command line. The alternative is to do it by hand.
1. Download the .tar.gz file from http://ant.apache.org/.
2. Expand it using gunzip:
3. Untar it using the Gnu tar program. AIX, Solaris, and HPUX users will encounter problems if they use the version that ships with their OS, as it cannot handle long filenames:
4. Set the ANT_HOME environment in the login script
5. Add $ANT_HOME/bin to the PATH environment variable:
6. Log out and in again.
7. Change to Ant’s bin directory:
8. Run Ant:
The result should be the version of Ant that’s installed:
Apache Ant version 1.7.0 compiled on December 13 2006
A different version means that there’s a conflicting copy of Ant on the path, perhaps one preinstalled by the system administrators.
There’s a place where Ant options (such as ANT_OPTS) can be set in Unix, the .antrc file in the user’s home directory, which is read in by the Ant shell script. Other mechanisms for starting Ant under Unix, such as the Perl or Python scripts, don’t read this file.
Installation configuration
There are two useful environment variables that the Ant wrapper scripts use when invoking Ant: ANT_OPTS and ANT_ARGS. These can be used to configure Ant’s scripts—but have no effect on IDE-hosted Ant.
ANT_OPTS
The ANT_OPTS environment variable provides options to the JVM executing Ant, such as system properties and memory configuration. One use of the environment variable is to set up the proxy settings for Ant tasks and Java programs hosted in Ant’s JVM. Declaring two system properties is sufficient here
-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080
Remember these are system properties, not Ant properties. They will be visible as Ant properties, but they are interpreted by the JVM, not Ant.
ANT_ARGS
In a similar fashion to ANT_OPTS, the ANT_ARGS environment variable is passed to Ant’s main process as command-line arguments, in addition to the arguments that you specify on the command line. This could be useful, for example, if you always want to use Ant’s NoBannerLogger to remove the output from empty targets.
export ANT_ARGS=-logger org.apache.tools.ant.NoBannerLogger
Any Ant command-line parameter can be set in this environment variable.
Troubleshooting installation
Getting started with Ant is difficult: you don’t know exactly what to expect, and there are a few complex steps to go through. This is where you discover that a consequence of free, open source software is that nobody staffs the support lines apart from other users of the tool.
Because Ant does work for most developers, any installation that doesn’t work is almost always due to some local configuration problem. Something is missing or mis-configured or, perhaps, some other piece of software is interfering with Ant.
The best source of diagnostics is built into Ant—the -diagnostics command:
ant -diagnostics
This will list out Ant’s view of its own state. If you get an error instead, something has gone horribly wrong, either with the command line or the classpath. If it works, it will display information about the installation, including Ant’s JAR versions, which tasks cannot be instantiated, system properties, the classpath, and other relevant information. This output may help to determine the cause of any installation or configuration problems. It is also important data to include in any bug report filed against installation problems.
If you cannot get Ant to work, consult the Ant user mailing list. Remember that Ant does work on most people’s machines, so if there’s a problem it is in the local system. These are hard bugs to track down, and nobody else can do it but you. All you are likely to get is advice such as “reset CLASSPATH” or “remove the RPM and try again,” because there are no obvious answers to these problems.
Problem: Java not installed/configured
If Java is missing or not on the path, then Ant doesn’t work.
| Test | Run java from the command line; if this isn’t a known command, then either Java isn’t installed or the path is wrong. |
| Fix | Install the JDK; set up JAVA_HOME to point to the install location. Add the bin directory to the PATH, and log out and in again. |
Problem: JDK not installed/configured
Ant needs to find the JDK so that it can use classes in tools.jar, such as the Java compiler. Without the JDK, some Ant tasks will fail with “class not found” exceptions. The environment variable JAVA_HOME is used to find the JDK—if it isn’t set, Ant will warn you on startup with an error message:
Warning: JAVA_HOME environment variable is not set.
This may just be a warning, but it’s a warning that some tasks will not work properly. More insidiously, if JAVA_HOME is wrong, Ant will not notice until some tasks fail, usually <javac> and <javadoc>.
| Test 1 | Run javac from the command line; if this isn’t a known command, then either Java isn’t installed or the path is wrong. |
| Test 2 | Use set or setenv to verify that the environment variable JAVA_HOME exists. Verify that the file tools.jar can be found in the subdirectory JAVA_HOME/lib. |
| Fix | Install the JDK; set up JAVA_HOME to point to the install location. |
Problem: Ant not on the path
Ant is started by a platform-dependent batch file or shell script, or by a portable script in a language such as Perl or Python. If the path doesn’t include Ant’s bin directory, these scripts aren’t found and so Ant cannot start.
| Test | Run ant -version from the command line: a version number and build time should appear. If the command interpreter complains that ant is unknown, then the path is wrong. If the error is that the Java command is unknown, then the problem is actually with the Java installation, covered earlier. |
| Fix | Modify the environment path variable to include the Ant scripts, log out, and reboot or otherwise reload the environment to have the change applied. |
Problem: Another version of Ant is on the path
Many Java products include a version of Ant, including Apache Tomcat, IBM Web-Sphere, and BEA WebLogic. This may be an older version of Ant, or the installation may be incomplete.
| Test | Run ant -diagnostics to get a diagnostics output, including ant.home. |
| Fix | Remove or rename other copies of the batch files/shell scripts, or reorder your path to place the version you want first. |
Problem: Ant fails with an error about a missing task or library
This can mean that a library containing needed task definitions is missing. The -diagnostics command will probe for missing tasks. Usually the problem is missing third-party libraries, though it also can be caused by a custom build of Ant that was compiled without those libraries.
| Test | Run ant -diagnostics to see if the task is present. |
| Fix | Consult Ant’s documentation to see what extra libraries are needed—download them and install them in the ANT_HOME/lib directory. |
Problem: The ANT_HOME directory points to the wrong place
If ANT_HOME is set, but it’s set to the wrong location, much confusion can arise. A warning about lcp.bat being missing is one obvious sign when calling ant.bat; another is failure to find ant.jar, with a Java error about the class org.apache.tools.ant.Main not being found.
| Test | Look at the value of ANT_HOME and verify it’s correct. |
| Fix | Either set the variable to the correct location, or omit it. |
Problem: Incompatible Java libraries on the classpath
If you set up the CLASSPATH environment variable with a list of commonly needed JAR files, there’s a risk that the libraries listed clash with the versions Ant needs.
| Test | Look at the value of CLASSPATH and verify it’s empty. Run Ant with the -noclasspath option to omit the classpath. |
| Fix | Remove the environment variable. |
Problem: Java extension libraries conflicting with Ant
Java supports extension libraries; JAR files placed into JAVA_HOMEjrelibext are loaded by the runtime using a different classloader than normal. This can cause problems if any code in the extension libraries (such as jaxp.jar) tries to locate classes loaded under a different classloader.
| Test | Look in the JRE/lib/ext directory for any JAR files that have crept in as extension libraries and that are confusing Ant. |
| Fix | Move the XML parser libraries to a different directory. |
Problem: Sealing violation when running Ant
This exception happens when a library has been marked as sealed but another library implements classes in one of the packages of the sealed library. This exception means there is an XML parser conflict, perhaps from an older version on the classpath or extension library, or perhaps from some other library that contains a sealed copy of the JAXP API. The underlying cause will be one of the two problems above: extension library conflicts or classpath incompatibilities.
| Fix | The message should identify which libraries have sealing problems. Use this to identify the conflict, and fix it, usually by removing one of the libraries. You can unseal a JAR file by editing its manifest, but this only fixes a symptom of the conflict, not the underlying problem. |
Problem: Calling Ant generates a Java usage message
If the Java invocation string that the Ant launcher scripts is somehow corrupt, then the java program will not be able to parse it, so it will print a message beginning with Usage: java [-options] class [args...].
This is usually caused by one of the environment variables, JAVA_HOME, ANT_HOME, ANT_OPTS, or CLASSPATH being invalid. Backslashes at the end and quotes in the middle are the common causes.
| Test | Examine the environment variables to see if there are any obvious errors. |
| Fix | Fix any obvious errors. Otherwise, unset each variable in turn until Ant works; this will identify the erroneous variable. |
Problem: Illegal Java options in the ANT_OPTS variable
The ANT_OPTS environment variable must contain options the local JVM recognizes. Any invalid parameter will generate an error message such as the following (where ANT_OPTS was set to –3):
Unrecognized option: -3 Could not create the Java virtual machine.
If the variable contains a string that is mistaken for the name of the Java class to run as the main class, then a different error appears:
Exception in thread "main" java.lang.NoClassDefFoundError: one
| Test | Examine ANT_OPTS and verify that the variable is unset or contains valid JVM options. |
| Fix | Correct or clear the variable. |
Problem: Incomplete source tree on a SYSV Unix installation
The original SYSV Unix tar utility cannot handle the long filenames of the Java source tree, and doesn’t expand the entire Java source tree—files appear to be missing.
| Test | In a source distribution, run build.bat or build.sh. If it fails, the source tree may be corrupt. |
| Fix | Untar Ant using the GNU tar utility, or download the .zip file and use unzip. |
To summarize, most common installation problems stem from incorrect environment settings, especially the CLASSPATH environment variable, or duplicate and conflicting Ant installations.
If these tests don’t identify the problem, call for help on the Ant user mailing list. This is a mailing list where Ant users solve each other’s problems, be they related to installing Ant or getting a build to work.