The latest version can always be found at Ant's homepage http://ant.apache.org/faq.html.

The page you are looking it is generated from this document. If you want to add a new question, please submit a patch against this document to one of Ant's mailing lists; hopefully, the structure is self-explanatory.

If you don't know how to create a patch, see the patches section of this page.

We use Anakia to render the HTML version from the original XML file.

The Velocity stylesheets used to process the XML files can be found in the xdocs/stylesheets subdirectory of Ant's CVS repository - the build file docs.xml at the top level of the ant CVS module is used to drive Anakia.

This file assumes that you have the jakarta-site2 CVS module checked out as well, but if you follow the instruction from Anakia's homepage, you should get it to work without that. Just make sure all required jars are in the task's classpath.

Ant is a Java-based build tool. In theory, it is kind of like Make, without Make's wrinkles and with the full portability of pure Java code.

According to Ant's original author, James Duncan Davidson, the name is an acronym for "Another Neat Tool".

Later explanations go along the lines of "ants do an extremely good job at building things", or "ants are very small and can carry a weight dozens of times their own" - describing what Ant is intended to be.

Initially, Ant was part of the Tomcat code base, when it was donated to the Apache Software Foundation. It was created by James Duncan Davidson, who is also the original author of Tomcat. Ant was there to build Tomcat, nothing else.

Soon thereafter, several open source Java projects realized that Ant could solve the problems they had with Makefiles. Starting with the projects hosted at Jakarta and the old Java Apache project, Ant spread like a virus and is now the build tool of choice for a lot of projects.

In January 2000, Ant was moved to a separate CVS module and was promoted to a project of its own, independent of Tomcat, and became Apache Ant.

The first version of Ant that was exposed to a larger audience was the one that shipped with Tomcat's 3.1 release on 19 April 2000. This version has later been referred to as Ant 0.3.1.

The first official release of Ant as a stand-alone product was Ant 1.1, released on 19 July 2000. The complete release history:

Ant's distribution contains file names that are longer than 100 characters, which is not supported by the standard tar file format. Several different implementations of tar use different and incompatible ways to work around this restriction.

Ant's <tar> task can create tar archives that use the GNU tar extension, and this has been used when putting together the distribution. If you are using a different version of tar (for example, the one shipping with Solaris), you cannot use it to extract the archive.

The solution is to either install GNU tar, which can be found here, or use the zip archive instead (you can extract it using jar xf).

Join and post a message to the dev or user mailing list (one list is enough), including the following information:

• the name of the task/tool
• a short description of the task/tool
• a Compatibility: entry stating with which version(s) of Ant the tool/task is compatible to
• a URL: entry linking to the main page of the tool/task
• a Contact: entry containing the email address or the URL of a webpage for the person or list to contact for issues related to the tool/task. Note that we'll add a link on the page, so any email address added there is not obfuscated and can (and probably will) be abused by robots harvesting websites for addresses to spam.
• a License: entry containing the type of license for the tool/task

The preferred format for this information is a patch to this document.

Use properties. Using ant -Dname=value lets you define values for properties on the Ant command line. These properties can then be used within your build file as any normal property: ${name} will put in value.

A couple of switches are supported via "magic" properties:

With Ant >= 1.5, you can also use nested <compilerarg> elements with the <javac> task.

The short answer is "Use: <".

The long answer is that this probably won't do what you want anyway (see the next section).

Say you want to redirect the standard input stream of the cat command to read from a file, something like:

and try to translate it into

On native Unix systems, you should be able to run shell scripts directly. On systems running a Unix-type shell (for example, Cygwin on Windows) execute the (command) shell instead - cmd for batch files, sh for shell scripts - then pass the batch file or shell script (plus any arguments to the script) as a single command, using the /c or -c switch, respectively. See the above section for example <exec> tasks executing sh. For batch files, use something like:

There are actually several answers to this question.

If you have only one set and one unset property to test, you can specify both an if and an unless attribute for the target, and they will act as if they are "anded" together.

If you are using a version of Ant 1.3 or earlier, the way to work with all other cases is to chain targets together to determine the specific state you want to test for.

To see how this works, assume you have three properties: prop1, prop2, and prop3. You want to test that prop1 and prop2 are set, and that prop3 is not. If the condition holds true you want to echo "yes".

Here is the implementation in Ant 1.3 and earlier:

Note: <antcall> tasks do not pass property changes back up to the environment they were called from, so you would'nt be able to, for example, set a result property in the cond-if-3 target, then do <echo message="result is ${result}"/> in the cond target.

Starting with Ant 1.4, you can use the <condition> task.

This version takes advantage of two things:

• If a property a has not been set, ${a} will evaluate to ${a}.
• To get a literal $ in Ant, you have to escape it with another $ - this will also break the special treatment of the ${ sequence.

Because testing for a literal ${property} string isn't all that readable or easy to understand, post-1.4.1 Ant introduces the <isset> element to the <condition> task.

Here is the previous example done using <isset>:

The last option is to use a scripting language to set the properties. This can be particularly handy when you need much finer control than the simple conditions shown here but, of course, comes with the overhead of adding JAR files to support the language, to say nothing of the added maintenance in requiring two languages to implement a single system. See the <script> task documentation for more details.

You need to tell the XML parser which character encoding your build file uses, this is done inside the XML declaration.

By default the parser assumes you are using the UTF-8 encoding instead of your platform's default. For most Western European countries you should set the encoding to ISO-8859-1. To do so, make the very first line of you build file read like

In order to find out which files should be compiled, Ant compares the timestamps of the source files to those of the resulting .class files. Opening all source files to find out which package they belong to would be very inefficient. Instead, Ant expects you to place your source files in a directory hierarchy that mirrors your package hierarchy and to point Ant to the root of this directory tree with the srcdir attribute.

Say you have <javac srcdir="src" destdir="dest"/>. If Ant finds a file src/a/b/C.java, it expects it to be in package a.b so that the resulting .class file is going to be dest/a/b/C.class.

If your source-tree directory structure does not match your package structure, Ant's heuristic won't work, and it will recompile classes that are up-to-date. Ant is not the only tool that expects a source-tree layout like this.

If you have Java source files that aren't declared to be part of any package, you can still use the <javac> task to compile these files correctly - just set the srcdir and destdir attributes to the actual directory the source files live in and the directory the class files should go into, respectively.

This is probably happening because, by default, Ant excludes SourceSafe control files (vssver.scc) and certain other files from FileSets.

Here's what you probably did:

The list of dependencies is generated by Ant before any of the targets are run. This allows dependent targets, such as an init target, to set properties that can control the execution of the targets higher in the dependency graph. This is a good thing.

However, when your dependencies break down the higher-level task into several smaller steps, this behaviour becomes counter-intuitive. There are a couple of solutions available:

1. Put the same condition on each of the dependent targets.
2. Execute the steps using <antcall>, instead of specifying them inside the depends attribute.

The order of the <include> and <exclude> tags within a <fileset> is ignored when the FileSet is created. Instead, all of the <include> elements are processed together, followed by all of the <exclude> elements. This means that the <exclude> elements only apply to the file list produced by the <include> elements.

To get the files you want, focus on just the <include> patterns that would be necessary to get them. If you find you need to trim the list that the <include> elements produce, then use <exclude> elements.

When ant loads properties from an external file it dosn't touch the value of properties, trailing blanks will not be trimmed for example.

If the value represents a file path, like a jar needed to compile, the task which requires the value, javac for example would fail to compile since it can't find the file due to trailing spaces.

No it doesn't.

You may have seen these lower-case directory names in WinZIP, but WinZIP is trying to be helpful (and fails). If WinZIP encounters a filename that is all upper-case, it assumes it has come from an old DOS box andchanges the case to all lower-case for you.

If you extract (or just check) the archive with jar, you will see that the names have the correct case.

See the section on IDE integration on our External Tools and Tasks page.

Ant adds a "banner" with the name of the current task in front of all logging messages - and there are no built-in regular expressions in your editor that would account for this.

You can disable this banner by invoking Ant with the -emacs switch. To make Ant autodetect Emacs' compile mode, put this into your .antrc (contributed by Ville Skyttä).

Alternatively, you can add the following snippet to your .emacs to make Emacs understand Ant's output.

Yet another alternative that preserves most of Ant's formatting is to pipe Ant's output through the following Perl script by Dirk-Willem van Gulik:

An incomplete DTD can be created by the <antstructure> task - but this one has a few problems:

• It doesn't know about required attributes. Only manual tweaking of this file can help here.
• It is not complete - if you add new tasks via <taskdef> it won't know about it. See this page by Michel Casabianca for a solution to this problem. Note that the DTD you can download at this page is based on Ant 0.3.1.
• It may even be an invalid DTD. As Ant allows tasks writers to define arbitrary elements, name collisions will happen quite frequently - if your version of Ant contains the optional <test> and <junit> tasks, there are two XML elements named test (the task and the nested child element of <junit>) with different attribute lists. This problem cannot be solved; DTDs don't give a syntax rich enough to support this.

You can use XML's way of including external files and let the parser do the job for Ant:

will literally include the contents of common.xml where you've placed the &common; entity.

In combination with a DTD, this would look like this:

If you are using a nightly build of Ant 1.5 after 2001-12-14, you can use the built-in MailLogger:

See the Listeners & Loggers documentation for details on the properties required.

For older versions of Ant, you can use a custom BuildListener that sends out an email in the buildFinished() method. Will Glozer <will.glozer@jda.com> has written such a listener based on JavaMail. The source is:

With a monitor.properties like this:

You can get at a hashtable with all the properties that Ant has been using through the BuildEvent parameter. For example:

This is more accurate than just reading the same property files that your project does, since it will give the correct results for properties that were specified on the Ant command line.

The antRun script in ANT_HOME/bin has DOS instead of Unix line endings; you must remove the carriage-return characters from this file. This can be done by using Ant's <fixcrlf> task or something like:

There is a bug in the Solaris reference implementation of the JDK (see http://developer.java.sun.com/developer/bugParade/bugs/4230399.html). This also appears to be true under Linux. Moving the JDK to the front of the PATH fixes the problem.

These tasks don't ignore your classpath setting, you are facing a common problem with delegating classloaders.

First of all let's state that Ant adds all .jar files from ANT_HOME/lib to CLASSPATH, therefore "in CLASSPATH" shall mean "either in your CLASSPATH environment variable or ANT_HOME/lib" for the rest of this answer.

This question collects a common type of problem: A task needs an external library and it has a nested classpath element so that you can point it to this external library, but that doesn't work unless you put the external library into the CLASSPATH.

The root of the problem is that the class that needs the external library is on the CLASSPATH.

When you specify a nested <classpath> in Ant, Ant creates a new class loader that uses the path you have specified. It then tries to load additional classes from this classloader.

In most cases - for example the two cases above - Ant doesn't load the external library directly, it is the loaded class that does so.

In the case of <junit> it is the task implementation itself and in the case of <style> it is the implementation of the org.apache.tools.ant.taskdefs.XSLTLiaison class.

Ant's class loader implementation uses Java's delegation model, see http://java.sun.com/products/jdk/1.2/docs/api/java/lang/ClassLoader.html the paragraph

The ClassLoader class uses a delegation model to search for classes and resources. Each instance of ClassLoader has an associated parent class loader. When called upon to find a class or resource, a ClassLoader instance will delegate the search for the class or resource to its parent class loader before attempting to find the class or resource itself. The virtual machine's built-in class loader, called the bootstrap class loader, does not itself have a parent but may serve as the parent of a ClassLoader instance.

This means, Ant's class loader will consult the bootstrap class loader first, which tries to load classes from CLASSPATH. The bootstrap class loader doesn't know anything about Ant's class loader or even the path you have specified.

If the bootstrap class loader can load the class Ant has asked it to load, this class will try to load the external library from CLASSPATH as well - it doesn't know anything else - and will not find it unless the library is in CLASSPATH as well.

To solve this, you have two major options:

1. put all external libraries you need in CLASSPATH as well this is not what you want, otherwise you wouldn't have found this FAQ entry.
2. remove the class that loads the external library from the CLASSPATH.

The easiest way to do this is to remove optional.jar from ANT_HOME/lib. If you do so, you will have to <taskdef> all optional tasks and use nested <classpath> elements in the <taskdef> tasks that point to the new location of optional.jar. Also, don't forget to add the new location of optional.jar to the <classpath> of your <style> or <junit> task.

If you want to avoid to <taskdef> all optional tasks you need, the only other option is to remove the classes that should not be loaded via the bootstrap class loader from optional.jar and put them into a separate archive. Add this separate archive to the <classpath> of your <style> or <junit> task - and make sure the separate archive is not in CLASSPATH.

In the case of <junit> you'd have to remove all classes that are in the org/apache/tools/ant/taskdefs/optional/junit directory, in the <style> case it is one of the *Liaison classes in org/apache/tools/ant/taskdefs/optional.

If you use the option to break up optional.jar for <junit>, you still have to use a <taskdef> with a nested <classpath> to define the junit task.

Ant < 1.5 doesn't recognize Windows XP as a flavor of Windows that runs CMD.EXE instead of COMMAND.COM. JDK 1.3 will tell Ant that Windows XP is Windows 2000 so the problem doesn't show up there.

Apart from upgrading to Ant 1.5 or better, setting the environment variable ANT_OPTS to -Dos.name=Windows_NT prior to invoking Ant has been confirmed as a workaround.

This problem has been reported only hours after Ant 1.5 has been released, see Bug 10664 and all it's duplicates.

A fixed version of the wrapper script can be found here. Simply replace your script with this version.