-
-
-
- Frequently Asked Questions
- |
-
-
-
-
-
-
- |
-
- About this FAQ
-
- |
-
-
-
-
-
-
-
-
-
-
-
-
-
- |
-
- It doesn't work (as expected)
-
- |
-
-
-
-
- |
-
- Ant and IDEs/Editors
-
- |
-
-
-
-
- |
-
- Advanced Issues
-
- |
-
-
-
-
- |
-
- Known Problems
-
- |
-
-
-
-
-
-
-
- |
-
-
- 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 is
- used to drive Anakia. This file assumes that you have the
- jakarta-site2 module checked out from CVS 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.
-
-
-
- |
-
-
- What is Apache Ant?
-
-
- |
-
-
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.
-
-
-
- |
-
-
- Why do you call it Ant?
-
-
- |
-
-
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
- |
-
-
-
-
-
-
-
-
- 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 ant-dev or ant-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 input stream of the
- cat command to read from a file, something
- like:
-
-shell-prompt> cat < foo
-
-
and try to translate it into
-
-<exec executable="cat">
- <arg value="<" />
- <arg value="foo" />
-</exec>
-
-
This will not do what you expect. The input redirection is
- performed by your shell, not the command itself, so this
- should read:
-
-<exec executable="/bin/sh">
- <arg value="-c" />
- <arg value="cat < 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 "cat < 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" ?>
-
-
-
-
- |
-
-
- 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 the depends
- 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 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.
-
-
-
- |
-
-
- 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 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.
-
-
-
-
- |
-
-
- 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">
-]>
-
-
-
-
- |
-
-
- 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.
-
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:
-
- - 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.
-
-
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.
-
-
-
-
-
-
- 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 it's duplicates.
-
A fixed version of the wrapper script can be found here.
- Simply replace your script with this version.
-
-
