Frequently Asked Questions
Questions
About this FAQ
- Where do I find the latest version of this document?
- How can I contribute to this FAQ?
- How do you create the HTML version of this FAQ?
General
Installation
How do I ...
- How do I add an external task that I've written to the page "External Tools and Task"?
- How do I pass parameters from the command line to my build file?
- How can I use Jikes-specific command-line switches?
- How do I include a < character in my command-line arguments?
-
How do I redirect standard input or standard output
in the
<exec>
task? - How do I execute a batch file or shell script from Ant?
- I want to execute a particular target only if multiple conditions are true.
- How can I include national characters like German umlauts in my build file?
-
How do I use
jar
'sM
switch? I don't want a MANIFEST. -
How can I do something like
<property name="prop" value="${${anotherprop}}"/>
(double expanding the property)?
It doesn't work (as expected)
- Why does Ant always recompile all my Java files?
-
I've used a
<delete>
task to delete unwanted SourceSafe control files (CVS files, editor backup files, etc.), but it doesn't seem to work; the files never get deleted. What's wrong? -
I have a target I want to skip if a property is set,
so I have
unless="property"
as an attribute of the target, but all the targets this target depends on are still executed. Why? -
In my
<fileset>
, I've put in an<exclude>
of all files followed by an<include>
of just the files I want, but it isn't giving me any files at all. What's wrong? -
ant
failed to build my program via javac even when I put the needed jars in an externalbuild.properties
file and reference them bypathelement
orclasspath refid
. -
Ant creates WAR files with a lower-case
web-inf
or JAR files with a lower-casemeta-inf
directory.
Ant and IDEs/Editors
- Is Ant supported by my IDE/Editor?
- Why doesn't (X)Emacs/vi/MacOS X's project builder correctly parse the error messages generated by Ant?
Advanced Issues
- Is there a DTD that I can use to validate my build files?
- How do I include an XML snippet in my build file?
- How do I send an email with the result of my build process?
- How do I get at the properties that Ant was running with from inside BuildListener?
Known Problems
- <chmod> or <exec> doesn't work in Ant 1.3 on Unix
- JavaDoc failed: java.io.IOException: javadoc: cannot execute
- <style> or <junit> ignores my <classpath>
-
When running Ant 1.4 on Windows XP and JDK 1.4, I get
various errors when trying to
<exec>
, fork<java>
or access environment variables. -
The
ant
wrapper script of Ant 1.5 fails for Cygwin ifANT_HOME
is set to a Windows style path. -
<zip>
is broken in Ant 1.5.2.
Answers
Where do I find the latest version of this document?
The latest version can always be found at Ant's homepage http://ant.apache.org/faq.html.
How can I contribute to this FAQ?
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.
How do you create the HTML version of this FAQ?
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.
Tell us a little bit about Ant's history.
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 Version | Release Date |
---|---|
1.1 | 19 July 2000 |
1.2 | 24 October 2000 |
1.3 | 3 March 2001 |
1.4 | 3 September 2001 |
1.4.1 | 11 October 2001 |
1.5 | 10 July 2002 |
1.5.1 | 3 October 2002 |
1.5.2 | 3 March 2003 |
1.5.3 | 9 April 2003 |
1.5.4 | 12 August 2003 |
1.6.0 | 18 December 2003 |
1.6.1 | 12 February 2004 |
I get checksum errors when I try to extract the
tar.gz
distribution file. Why?
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
).
How do I add an external task that I've written to the page "External Tools and Task"?
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.
How do I pass parameters from the command line to my build file?
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
.
How can I use Jikes-specific command-line switches?
A couple of switches are supported via "magic" properties:
switch | property | default |
---|---|---|
+E | build.compiler.emacs | false == not set |
+P | build.compiler.pedantic | false == not set |
+F | build.compiler.fulldepend | false == not set |
(Only for Ant < 1.4; replaced by the
nowarn
attribute of the <javac>
task after that.)-nowarn |
build.compiler.warnings | true == not set |
With Ant >= 1.5, you can also use nested
<compilerarg>
elements with the
<javac>
task.
How do I include a < character in my command-line arguments?
The short answer is "Use: <
".
The long answer is that this probably won't do what you want anyway (see the next section).
How do I redirect standard input or standard output
in the <exec>
task?
Say you want to redirect the standard output stream of the
m4
command to write to a file, something
like:
shell-prompt> m4 foo.m4 > foo
and try to translate it into
<exec executable="m4"> <arg value="foo.m4"/> <arg value=">"/> <arg value="foo"/> </exec>
This will not do what you expect. The output redirection is performed by your shell, not the command itself, so this should read:
<exec executable="/bin/sh"> <arg value="-c" /> <arg value="m4 foo.m4 > foo" /> </exec>
Note that you must use the value
attribute of
<arg>
in the last element, in order to have
the command passed as a single, quoted argument. Alternatively,
you can use:
<exec executable="/bin/sh"> <arg line='-c "m4 foo.m4 > foo"'/> </exec>
Note the double-quotes nested inside the single-quotes.
How do I execute a batch file or shell script from Ant?
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:
<exec dir="." executable="cmd" os="Windows NT"> <arg line="/c test.bat"/> </exec>
I want to execute a particular target only if multiple conditions are true.
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:
<target name="cond" depends="cond-if"/> <target name="cond-if" if="prop1"> <antcall target="cond-if-2"/> </target> <target name="cond-if-2" if="prop2"> <antcall target="cond-if-3"/> </target> <target name="cond-if-3" unless="prop3"> <echo message="yes"/> </target>
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.
<target name="cond" depends="cond-if,cond-else"/> <target name="check-cond"> <condition property="cond-is-true"> <and> <not> <equals arg1="${prop1}" arg2="$${prop1}" /> </not> <not> <equals arg1="${prop2}" arg2="$${prop2}" /> </not> <equals arg1="${prop3}" arg2="$${prop3}" /> </and> </condition> </target> <target name="cond-if" depends="check-cond" if="cond-is-true"> <echo message="yes"/> </target> <target name="cond-else" depends="check-cond" unless="cond-is-true"> <echo message="no"/> </target>
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>
:
<target name="check-cond"> <condition property="cond-is-true"> <and> <isset property="prop1"/> <isset property="prop2"/> <not> <isset property="prop3"/> </not> </and> </condition> </target>
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.
How can I include national characters like German umlauts in my build file?
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
<?xml version="1.0" encoding="ISO-8859-1" ?>
How do I use jar
's M
switch?
I don't want a MANIFEST.
A JAR archive is a ZIP file, so if you don't want a
MANIFEST you can simply use <zip>
.
If your file names contain national characters you should
know that Sun's jar
utility like Ant's
<jar>
uses UFT8 to encode their names while
<zip>
uses your platforms default encoding.
Use the encoding attribute of <zip>
if
necessary.
How can I do something like <property name="prop"
value="${${anotherprop}}"/>
(double expanding the property)?
Without any external help you can not.
With <script/>, which needs external libraries, you can do
<script language="javascript"> propname = project.getProperty("anotherprop"); project.setNewProperty("prop", propname); </script>
With AntContrib (external task library) you can do
<propertycopy name="prop" from="${anotherprop}"/>
.
Why does Ant always recompile all my Java files?
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.
I've used a <delete>
task to
delete unwanted SourceSafe control files (CVS files, editor
backup files, etc.), but it doesn't seem to work; the files
never get deleted. What's wrong?
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:
<delete> <fileset dir="${build.src}" includes="**/vssver.scc"/> </delete>
You need to switch off the default exclusions, and it will work:
<delete> <fileset dir="${build.src}" includes="**/vssver.scc" defaultexcludes="no"/> </delete>
For a complete listing of the patterns that are excluded by default, see the user manual.
I have a target I want to skip if a property is set,
so I have unless="property"
as an attribute
of the target, but all the targets this target
depends on are still executed. Why?
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:
- Put the same condition on each of the dependent targets.
- Execute the steps using
<antcall>
, instead of specifying them inside thedepends
attribute.
In my <fileset>
, I've put in an
<exclude>
of all files followed by an
<include>
of just the files I want, but it
isn't giving me any files at all. What's wrong?
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.
ant
failed to build my program via javac
even when I put the needed jars in an external
build.properties
file and reference them by
pathelement
or classpath refid
.
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.
Ant creates WAR files with a lower-case
web-inf
or JAR files with a lower-case
meta-inf
directory.
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 and changes 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.
With WinZIP (version 8.1 at least), this can be corrected in the configuration. In the Options/Configuration menu, in the View tab, General section, check the "Allow all upper case files names" box. The META-INF and WEB-INF will look correct.
Is Ant supported by my IDE/Editor?
See the section on IDE integration on our External Tools and Tasks page.
Why doesn't (X)Emacs/vi/MacOS X's project builder correctly parse the error messages generated by Ant?
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ä).
# Detect (X)Emacs compile mode if [ "$EMACS" = "t" ] ; then ANT_ARGS="$ANT_ARGS -emacs" ANT_OPTS="$ANT_OPTS -Dbuild.compiler.emacs=true" fi
Alternatively, you can add the following snippet to your
.emacs
to make Emacs understand Ant's
output.
(require 'compile) (setq compilation-error-regexp-alist (append (list ;; works for jikes '("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):\\([0-9]+\\):[0-9]+:[0-9]+:" 1 2 3) ;; works for javac '("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):" 1 2)) compilation-error-regexp-alist))
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:
#!/usr/bin/perl # # May 2001 dirkx@apache.org - remove any # [foo] lines from the output; keeping # spacing more or less there. # $|=1; while(<STDIN>) { if (s/^(\s+)\[(\w+)\]//) { if ($2 ne $last) { print "$1\[$2\]"; $s = ' ' x length($2); } else { print "$1 $s "; }; $last = $2; }; print; };
Is there a DTD that I can use to validate my build files?
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 namedtest
(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.
How do I include an XML snippet in my build file?
You can use XML's way of including external files and let the parser do the job for Ant:
<?xml version="1.0"?> <!DOCTYPE project [ <!ENTITY common SYSTEM "file:./common.xml"> ]> <project name="test" default="test" basedir="."> <target name="setup"> ... </target> &common; ... </project>
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:
<!DOCTYPE project PUBLIC "-//ANT//DTD project//EN" "file:./ant.dtd" [ <!ENTITY include SYSTEM "file:./header.xml"> ]>
Starting with Ant 1.6, there is a new
<import>
task that can (also) be used to
include build file fragments. Unlike the snippets used with
entity includes, the referenced files have to be complete Ant
build files, though.
The example above would become:
<?xml version="1.0"?> <project name="test" default="test" basedir="."> <target name="setup"> ... </target> <import file="./common.xml"/> ... </project>
Unlike entity includes, <import>
will
let you use Ant properties in the file name.
How do I send an email with the result of my build process?
If you are using a nightly build of Ant 1.5 after 2001-12-14, you can use the built-in MailLogger:
ant -logger org.apache.tools.ant.listener.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:
import java.io.*; import java.util.*; import javax.mail.*; import javax.mail.internet.*; import org.apache.tools.ant.*; /** * A simple listener that waits for a build to finish and sends an email * of the results. The settings are stored in "monitor.properties" and * are fairly self explanatory. * * @author Will Glozer * @version 1.05a 09/06/2000 */ public class BuildMonitor implements BuildListener { protected Properties props; /** * Create a new BuildMonitor. */ public BuildMonitor() throws Exception { props = new Properties(); InputStream is = getClass().getResourceAsStream("monitor.properties"); props.load(is); is.close(); } public void buildStarted(BuildEvent e) { } /** * Determine the status of the build and the actions to follow, now that * the build has completed. * * @param e Event describing the build status. */ public void buildFinished(BuildEvent e) { Throwable th = e.getException(); String status = (th != null) ? "failed" : "succeeded"; try { String key = "build." + status; if (props.getProperty(key + ".notify").equalsIgnoreCase("false")) { return; } Session session = Session.getDefaultInstance(props, null); MimeMessage message = new MimeMessage(session); message.addRecipients(Message.RecipientType.TO, parseAddresses( props.getProperty(key + ".email.to"))); message.setSubject(props.getProperty(key + ".email.subject")); BufferedReader br = new BufferedReader(new FileReader( props.getProperty("build.log"))); StringWriter sw = new StringWriter(); String line = br.readLine(); while (line != null) { sw.write(line); sw.write("\n"); line = br.readLine(); } br.close(); message.setText(sw.toString(), "UTF-8"); sw.close(); Transport transport = session.getTransport(); transport.connect(); transport.send(message); transport.close(); } catch (Exception ex) { System.out.println("BuildMonitor failed to send email!"); ex.printStackTrace(); } } /** * Parse a comma separated list of internet email addresses. * * @param s The list of addresses. * @return Array of Addresses. */ protected Address[] parseAddresses(String s) throws Exception { StringTokenizer st = new StringTokenizer(s, ","); Address[] addrs = new Address[st.countTokens()]; for (int i = 0; i < addrs.length; i++) { addrs[i] = new InternetAddress(st.nextToken()); } return addrs; } public void messageLogged(BuildEvent e) { } public void targetStarted(BuildEvent e) { } public void targetFinished(BuildEvent e) { } public void taskStarted(BuildEvent e) { } public void taskFinished(BuildEvent e) { } }
With a monitor.properties
like this:
# configuration for build monitor mail.transport.protocol=smtp mail.smtp.host=<host> mail.from=Will Glozer <will.glozer@jda.com> build.log=build.log build.failed.notify=true build.failed.email.to=will.glozer@jda.com build.failed.email.subject=Nightly build failed! build.succeeded.notify=true build.succeeded.email.to=will.glozer@jda.com build.succeeded.email.subject=Nightly build succeeded!
monitor.properties
should be placed right next
to your compiled BuildMonitor.class
. To use it,
invoke Ant like:
ant -listener BuildMonitor -logfile build.log
Make sure that mail.jar
from JavaMail and
activation.jar
from the
Java
Beans Activation Framework are in your CLASSPATH
.
How do I get at the properties that Ant was running with from inside BuildListener?
You can get at a hashtable with all the properties that Ant has been using through the BuildEvent parameter. For example:
public void buildFinished(BuildEvent e) { Hashtable table = e.getProject().getProperties(); String buildpath = (String)table.get("build.path"); ... }
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.
<chmod> or <exec> doesn't work in Ant 1.3 on Unix
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:
tr -d '\r' < $ANT_HOME/bin/antRun > /tmp/foo mv /tmp/foo $ANT_HOME/bin/antRun
JavaDoc failed: java.io.IOException: javadoc: cannot execute
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.
<style> or <junit> ignores my <classpath>
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.
Technically the sentence above isn't true for Ant 1.6
and later anymore, but the result is the same. For the sake
of this discussion, CLASSPATH
and
ANT_HOME/lib
are identical.
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
TheClassLoader
class uses a delegation model to search for classes and resources. Each instance ofClassLoader
has an associated parent class loader. When called upon to find a class or resource, aClassLoader
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 aClassLoader
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:
- 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. - remove the class that loads the external library from
the
CLASSPATH
.
Using The Second Option with Ant 1.5.4 and Earlier:
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
.
Using The Second Option with Ant 1.6 and later:
In Ant 1.6 optional.jar
has been split into
multiple jars, each one containing classes with the same
dependencies on external libraries. You can move the
"offending" jar out of ANT_HOME/lib. For the
<junit>
task it would be
ant-junit.jar
and for <style>
it would be ant-trax.jar
,
ant-xalan1.jar
or ant-xslp.jar
-
depending on the processor you use.
If you use the option to break up optional.jar
for <junit>
or remove
ant-junit.jar
, you still have to use a
<taskdef>
with a nested
<classpath>
to define the junit task.
When running Ant 1.4 on Windows XP and JDK 1.4, I get
various errors when trying to <exec>
, fork
<java>
or access environment
variables.
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.
The ant
wrapper script of Ant 1.5 fails
for Cygwin if ANT_HOME
is set to a Windows style
path.
This problem has been reported only hours after Ant 1.5 has been released, see Bug 10664 and all its duplicates.
A fixed version of the wrapper script can be found here. Simply replace your script with this version.
Yes, it is.
The problem reported by most people - see Bug
17648 and all its duplicates - is that Ant creates
archives that a partially unreadable by WinZIP. Luckily
jar
deals with the archives and so the generated
jars/wars/ears will most likely work for you anyway.
There are additional problems, see bugs Bug 17780, Bug 17871 and Bug 18403. All of them are supposed to be fixed with Ant 1.5.3 (and only 18403 should exist in 1.5.3beta1).