antliscence/xdocs/faq.xml

<?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<document>

  <properties>
    <author email="bodewig@apache.org">Stefan Bodewig</author>
    <title>Frequently Asked Questions</title>
  </properties>

  <faqsection title="About this FAQ">
    <faq id="latest-version">
      <question>Where do I find the latest version of this
        document?</question>
      <answer>
        <p>The latest version can always be found at Ant&apos;s homepage
          <a href="http://ant.apache.org/faq.html">http://ant.apache.org/faq.html</a>.</p>
      </answer>
    </faq>

    <faq id="adding-faqs">
      <question>How can I contribute to this FAQ?</question>
      <answer>
        <p>The page you are looking it is generated from
          <a href="http://svn.apache.org/repos/asf/ant/core/trunk/xdocs/faq.xml">this</a>
          document.  If you want to add a new question, please submit
          a patch against this document to one of Ant&apos;s mailing lists;
          hopefully, the structure is self-explanatory.</p>

        <p>If you don&apos;t know how to create a patch, see the patches
          section of <a href="http://jakarta.apache.org/site/source.html">this
          page</a>.</p>
      </answer>
    </faq>

    <faq id="creating-faq">
      <question>How do you create the HTML version of this
        FAQ?</question>

      <answer>
        <p>We use
        <a href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a>
        to render the HTML version from the original XML file.</p>

        <p>The Velocity stylesheets used to process the XML files can
        be found in the <code>xdocs/stylesheets</code> subdirectory of
        Ant&apos;s SVN repository - the build file
        <code>docs.xml</code> at the top level of the ant SVN
        module (trunk) is used to drive Anakia.</p>

        <p>This file assumes that you have the
        <code>jakarta-site2</code> CVS module checked out as well, but
        if you follow the instruction from Anakia&apos;s homepage, you
        should get it to work without that.  Just make sure all
        required jars are in the task&apos;s classpath.</p>
      </answer>
    </faq>

  </faqsection>

  <faqsection title="General">
    <faq id="what-is-ant">
      <question>What is Apache Ant?</question>
      <answer>
        <p> Ant is a Java-based build tool. In theory, it is kind of
        like Make, without Make&apos;s wrinkles and with the full
        portability of pure Java code.</p>
      </answer>
    </faq>

    <faq id="ant-name">
      <question>Why do you call it Ant?</question>
      <answer>

        <p>According to Ant&apos;s original author, James Duncan
        Davidson, the name is an acronym for &quot;Another Neat
        Tool&quot;.</p>

        <p>Later explanations go along the lines of &quot;ants
        do an extremely good job at building things&quot;, or
        &quot;ants are very small and can carry a weight dozens of times
        their own&quot; - describing what Ant is intended to
        be.</p>
      </answer>
    </faq>

    <faq id="history">
      <question>Tell us a little bit about Ant&apos;s history.</question>
      <answer>

        <p>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.</p>

        <p>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.</p>

        <p>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.</p>

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

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

        <table>
          <tr>
            <th>Ant Version</th>
            <th>Release Date</th>
          </tr>

          <tr>
            <td>1.1</td>
            <td>19 July 2000</td>
          </tr>

          <tr>
            <td>1.2</td>
            <td>24 October 2000</td>
          </tr>

          <tr>
            <td>1.3</td>
            <td>3 March 2001</td>
          </tr>

          <tr>
            <td>1.4</td>
            <td>3 September 2001</td>
          </tr>

          <tr>
            <td>1.4.1</td>
            <td>11 October 2001</td>
          </tr>

          <tr>
            <td>1.5</td>
            <td>10 July 2002</td>
          </tr>

          <tr>
            <td>1.5.1</td>
            <td>3 October 2002</td>
          </tr>

          <tr>
            <td>1.5.2</td>
            <td>3 March 2003</td>
          </tr>

          <tr>
            <td>1.5.3</td>
            <td>9 April 2003</td>
          </tr>

          <tr>
            <td>1.5.4</td>
            <td>12 August 2003</td>
          </tr>

          <tr>
            <td>1.6.0</td>
            <td>18 December 2003</td>
          </tr>

          <tr>
            <td>1.6.1</td>
            <td>12 February 2004</td>
          </tr>

          <tr>
            <td>1.6.2</td>
            <td>16 July 2004</td>
          </tr>

          <tr>
            <td>1.6.3</td>
            <td>28 April 2005</td>
          </tr>

          <tr>
            <td>1.6.4</td>
            <td>19 May 2005</td>
          </tr>

          <tr>
            <td>1.6.5</td>
            <td>2 June 2005</td>
          </tr>

          <tr>
            <td>1.7.0</td>
            <td>19 December 2006</td>
          </tr>
          
          <tr>
            <td>1.7.1</td>
            <td>27 June 2008</td>
          </tr>
        </table>
      </answer>
    </faq>

  </faqsection>

  <faqsection title="Installation">
    <faq id="java-version">
      <question>Which version of Java is required to run
        Ant?</question>
      <answer>

        <p>You will need Java installed on your system, version 1.3 or
          later required, 1.5 or later strongly recommended. The later
          the version of Java, the more Ant tasks you get.</p>

        <p>If only the JRE is present but not a full JDK then many
          tasks will not work.</p>

        <p>The following table lists the minimum Java versions
          required to compile and run Ant.  Note that most committers
          work with more recent versions of the JDK and that Ant doesn't
          get tested much for older versions.</p>

        <table>
          <tr>
            <th>Ant Version</th>
            <th>Minimum Java Version</th>
          </tr>

          <tr>
            <td>1.1 up to 1.5.4</td>
            <td>1.1</td>
          </tr>

          <tr>
            <td>1.6.0 up to 1.6.5</td>
            <td>1.2</td>
          </tr>
          
          <tr>
            <td>1.7.0 up to 1.7.1</td>
            <td>1.3</td>
          </tr>

          <tr>
            <td>current svn trunk</td>
            <td>1.4</td>
          </tr>
        </table>
      </answer>
    </faq>

    <faq id="no-gnu-tar">
      <question>I get checksum errors when I try to extract the
      <code>tar.gz</code> distribution file. Why?</question>
      <answer>
        <p>Ant&apos;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.</p>

        <p>Ant&apos;s &lt;tar&gt; 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.</p>

        <p>The solution is to either install GNU tar, which can be
        found <a href="http://www.gnu.org/software/tar/tar.html">here</a>,
        or use the zip archive instead (you can extract it using
        <code>jar xf</code>).</p>
      </answer>
    </faq>

    <faq id="RedHat_ES_3">
      <question>How do you get ant-1.6.x (or any version later than
      1.5.2) to work on on RedHat ES 3?</question>
      <answer>
        <p>Redhat ES 3.0 comes installed with ant 1.5.2. Even if you
        have your PATH and ANT_HOME variables set correctly to a later
        version of ant, you will always be forced to use the
        preinstalled version.</p>

        <p>To use a later version of ant on this OS you could do the
        following:</p>

        <source><![CDATA[
$ ant -version
Apache Ant version 1.5.2-23 compiled on November 12 2003
$ su -
# rpm -e ant ant-libs
# exit
$ hash -r
$ ant -version
Apache Ant version 1.6.2 compiled on July 16 2004
]]></source></answer>
    </faq>
  </faqsection>

  <faqsection title="How do I ...">
    <faq id="implement-os-specific-configuration">
      <question>How do I realize os--specific configurations?</question>
      <answer>
        <p>The core idea is using property files which name accords to the
        os-name. Then simply use the build-in property <tt>os.name</tt>.</p>
        <p>For better use you should also provide a file with default values.
        But be careful with the correct os-names. For test simply &lt;echo&gt;
        the ${os.name} on all machines and you can be sure to use the right
        file names.</p>
        <source><![CDATA[
          <property file="${os.name}.properties"/>
          <property file="default.properties"/>
]]></source>
      </answer>
    </faq>


    <faq id="adding-external-tasks">
      <question>How do I add an external task that I&apos;ve written to the
      page &quot;External Tools and Tasks&quot;?</question>
      <answer>

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

        <ul>
          <li>the name of the task/tool</li>
          <li>a short description of the task/tool</li>
          <li>a Compatibility: entry stating with which version(s) of
          Ant the tool/task is compatible to</li>
          <li>a URL: entry linking to the main page of the tool/task</li>
          <li>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.  <strong>Note that we&apos;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.</strong></li>
          <li>a License: entry containing the type of license for the
          tool/task</li>
        </ul>

        <p>The preferred format for this information is a patch to <a
        href="http://svn.apache.org/repos/asf/ant/core/trunk/xdocs/external.xml">this</a>
        document.</p>

        <p>If you have written something bigger than a 'simple plugin' to Ant it
        may be better to add the link to <a href="projects.html">projects.html</a>.
        The procedure to add it is the same. The file to patch is <a
        href="http://svn.apache.org/repos/asf/ant/core/trunk/xdocs/projects.xml">this</a>
        document. The syntax of that file is the same.</p>

      </answer>
    </faq>

    <faq id="create-extensions">
      <question>How do I create new tasks?</question>
      <answer>
        <p>Apart from a lot of information on using Ant, the
        <a href="manual/index.html">Manual</a> also contains information
        on how to extend Ant with new tasks. This information
        can be found under &quot;Developing with Ant&quot;.</p>

        <p>Chances are that someone else already created the task you
        want to create, it may be wise to see
        <a href="external.html">External Tools and Tasks</a> and
        <a href="projects.html">Related Projects</a> first.</p>
      </answer>
    </faq>

    <faq id="passing-cli-args">
      <question>How do I pass parameters from the command line to my
        build file?</question>
      <answer>

        <p>Use properties. Using <code>ant
        -D<em>name</em>=<em>value</em></code> 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: <code>${<em>name</em>}</code> will put in
        <code><em>value</em></code>.</p>

      </answer>
    </faq>

    <faq id="jikes-switches">
      <question>How can I use Jikes-specific command-line
        switches?</question>

      <answer>

        <p>A couple of switches are supported via &quot;magic&quot;
          properties:</p>

        <table>
          <tr>
            <th>switch</th>
            <th>property</th>
            <th>default</th>
          </tr>

          <tr>
            <td>+E</td>
            <td>build.compiler.emacs</td>
            <td>false == not set</td>
          </tr>

          <tr>
            <td>+P</td>
            <td>build.compiler.pedantic</td>
            <td>false == not set</td>
          </tr>

          <tr>
            <td>+F</td>
            <td>build.compiler.fulldepend</td>
            <td>false == not set</td>
          </tr>

          <tr>
            <td><strong>(Only for Ant &lt; 1.4; replaced by the
                <code><strong>nowarn</strong></code>
                attribute of the <code><strong>&lt;javac&gt;</strong></code>
                task after that.)</strong><br></br>-nowarn</td>
            <td>build.compiler.warnings</td>
            <td>true == not set</td>
          </tr>

        </table>

        <p>With Ant &gt;= 1.5, you can also use nested
          <code>&lt;compilerarg&gt;</code> elements with the
          <code>&lt;javac&gt;</code> task.</p>

      </answer>
    </faq>

    <faq id="shell-redirect-1">
      <question>How do I include a &lt; character in my command-line arguments?</question>
      <answer>
        <p>The short answer is "Use: <code>&amp;lt;</code>".</p>

        <p>The long answer is that this probably won&apos;t do what you
        want anyway (see <a href="#shell-redirect-2">the next
        section</a>).</p>
      </answer>
    </faq>

    <faq id="shell-redirect-2">
      <question>How do I redirect standard input or standard output
        in the <code>&lt;exec&gt;</code> task?</question>
      <answer>
        <p>Say you want to redirect the standard output stream of the
        <code>m4</code> command to write to a file, something
        like:</p>

        <source><![CDATA[
shell-prompt> m4 foo.m4 > foo
]]></source>

        <p>and try to translate it into</p>

        <source><![CDATA[
<exec executable="m4">
  <arg value="foo.m4"/>
  <arg value="&gt;"/>
  <arg value="foo"/>
</exec>
]]></source>

        <p>This will not do what you expect.  The output redirection is
        performed by your shell, not the command itself, so this
        should read:</p>

        <source><![CDATA[
<exec executable="/bin/sh">
  <arg value="-c" />
  <arg value="m4 foo.m4 &gt; foo" />
</exec>
]]></source>

        <p>Note that you must use the <code>value</code> attribute of
        <code>&lt;arg&gt;</code> in the last element, in order to have
        the command passed as a single, quoted argument. Alternatively,
        you can use:</p>
        <source><![CDATA[
<exec executable="/bin/sh">
  <arg line='-c "m4 foo.m4 &gt; foo"'/>
</exec>
]]></source>

        <p>Note the double-quotes nested inside the single-quotes.</p>

      </answer>
    </faq>

    <faq id="batch-shell-execute">
      <question>How do I execute a batch file or shell script from Ant?</question>
      <answer>

        <p>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 - <code>cmd</code>
           for batch files, <code>sh</code> for shell scripts - then pass the
           batch file or shell script (plus any arguments to the script)
           as a single command, using the <code>/c</code> or
           <code>-c</code> switch, respectively. See
           <a href="#shell-redirect-2">the above section</a>
           for example <code>&lt;exec&gt;</code> tasks
           executing <code>sh</code>. For batch files, use something like:</p>
        <source><![CDATA[
<exec dir="." executable="cmd" os="Windows NT">
  <arg line="/c test.bat"/>
</exec>
]]></source>

      </answer>
    </faq>

    <faq id="multi-conditions">
      <question>I want to execute a particular target only if
        multiple conditions are true.</question>

      <answer>
        <p>There are actually several answers to this question.</p>

        <p>If you have only one set and one unset property to test,
        you can specify both an <code>if</code> and an <code>unless</code>
        attribute for the target, and they will act as if they
        are &quot;anded&quot; together.</p>

        <p>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.</p>

        <p>To see how this works, assume you have three properties:
        <code>prop1</code>, <code>prop2</code>, and <code>prop3</code>.
        You want to test that <code>prop1</code> and <code>prop2</code>
        are set, and that <code>prop3</code> is not. If the condition
        holds true you want to echo &quot;yes&quot;.</p>

        <p>Here is the implementation in Ant 1.3 and earlier:</p>

        <source><![CDATA[
<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>
]]></source>

        <p>Note: <code>&lt;antcall&gt;</code> tasks do <em>not</em> pass
        property changes back up to the environment they were called
        from, so you wouldn&apos;t be able to, for example, set a
        <code>result</code> property in the <code>cond-if-3</code> target,
        then do
        <code>&lt;echo message=&quot;result is ${result}&quot;/&gt;</code>
        in the <code>cond</code> target.</p>

        <p>Starting with Ant 1.4, you can use the
        <code>&lt;condition&gt;</code> task.</p>

        <source><![CDATA[
<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>
]]></source>

        <p>This version takes advantage of two things:</p>

        <ul>
          <li>If a property <code>a</code> has not been set,
          <code>${a}</code> will evaluate to <code>${a}</code>.</li>

          <li>To get a literal <code>$</code> in Ant, you have to
          escape it with another <code>$</code> - this will also break
          the special treatment of the <code>${</code> sequence.</li>
        </ul>

        <p>Because testing for a literal <code>${property}</code> string
        isn&apos;t all that readable or easy to understand,
        post-1.4.1 Ant introduces the <code>&lt;isset&gt;</code> element
        to the <code>&lt;condition&gt;</code> task.</p>

        <p>Here is the previous example done using
        <code>&lt;isset&gt;</code>:</p>

        <source><![CDATA[
<target name="check-cond">
  <condition property="cond-is-true">
    <and>
      <isset property="prop1"/>
      <isset property="prop2"/>
      <not>
        <isset property="prop3"/>
      </not>
    </and>
  </condition>
</target>
]]></source>

        <p>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
        <a href="manual/OptionalTasks/script.html">
        <code>&lt;script&gt;</code> task documentation</a> for more
        details.</p>
      </answer>
    </faq>

    <faq id="encoding">
      <question>How can I include national characters like German
        umlauts in my build file?</question>

      <answer>
        <p>You need to tell the XML parser which character encoding
        your build file uses, this is done inside the <a
        href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-prolog-dtd">XML
        declaration</a>.</p>

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

        <source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1" ?>
]]></source>
      </answer>
    </faq>

    <faq id="use-zip-instead-of-jar">
      <question>How do I use <code>jar</code>&apos;s <code>M</code> switch?
      I don&apos;t want a MANIFEST.</question>

      <answer>
        <p>A JAR archive is a ZIP file, so if you don&apos;t want a
        MANIFEST you can simply use <code>&lt;zip&gt;</code>.</p>

        <p>If your file names contain national characters you should
        know that Sun&apos;s <code>jar</code> utility like Ant&apos;s
        <code>&lt;jar&gt;</code> uses UTF-8 to encode their names while
        <code>&lt;zip&gt;</code> uses your platforms default encoding.
        Use the encoding attribute of <code>&lt;zip&gt;</code> if
        necessary.</p>
      </answer>
    </faq>

    <faq id="propertyvalue-as-name-for-property">
      <question>How can I do something like <code>&lt;property name="prop"
      value="${${anotherprop}}"/&gt;</code> (double expanding the property)?</question>

      <answer>
        <p>Without any external help you can not.</p>
        <p>With &lt;script/&gt;, which needs external libraries, you can do</p>
        <source><![CDATA[
<script language="javascript">
    propname = project.getProperty("anotherprop");
    project.setNewProperty("prop", propname);
</script>
]]></source>
         <p>With AntContrib (external task library) you can do <code>
         &lt;propertycopy name="prop" from="${anotherprop}"/&gt;</code>.</p>
         <p>With Ant 1.6 you can simulate the AntContribs &lt;propertycopy&gt;
         and avoid the need of an external library:</p>
        <source><![CDATA[
<macrodef name="propertycopy">
  <attribute name="name"/>
  <attribute name="from"/>
  <sequential>
    <property name="@{name}" value="${@{from}}"/>
  </sequential>
</macrodef>
]]></source>
      </answer>
    </faq>

    <faq id="delete-directory-children-only">
      <question>How can I delete everything beneath a particular directory,
    preserving the directory itself?</question>
      <answer>
<p>Most users who go down this path have no problem figuring out that
  <code>&lt;delete includeemptydirs="true" /&gt;</code> will help them.  The
  seemingly tricky part is preserving the base directory itself,
  which Ant includes in the directory scan. Fortunately the answer is simple:
</p>
        <source><![CDATA[
<delete includeemptydirs="true">
  <fileset dir="dirtokeep" includes="**/*" />
</delete>
]]></source>
      </answer>
    </faq>

    <faq id="delete-directory-only-if-empty">
      <question>How can I delete a particular directory,
        if and only if it is empty?</question>
      <answer>
        <p>Most users who go down this path have no problem figuring
          out that
          <code>&lt;delete includeemptydirs="true" /&gt;</code> will
          help them.  The seemingly tricky part is preserving the
          non-empty directories, which Ant includes in the directory
          scan. Fortunately the answer is simple:</p>

        <source><![CDATA[
<delete includeemptydirs="true">
  <fileset dir="dirtokeepifnotempty" excludes="**/*" />
</delete>
]]></source>
      </answer>
    </faq>
  </faqsection>

  <faqsection title="It doesn&apos;t work (as expected)">
    <faq id="general-advice">
      <question>General Advice</question>
      <answer>

        <p>There are many reasons why Ant doesn&apos;t behave as
        expected, not all of them are due to Ant bugs.  See our <a
        href="problems.html">Having Problems?</a> page for hints that
        may help pinning down the reasons for your problem.</p>
      </answer>
    </faq>

    <faq id="always-recompiles">
      <question>Why does Ant always recompile all my Java files?</question>
      <answer>

        <p>In order to find out which files should be compiled, Ant
        compares the timestamps of the source files to those of the
        resulting <code>.class</code> 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 <code>srcdir</code> attribute.</p>

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

        <p>If your source-tree directory structure does not match your
        package structure, Ant&apos;s heuristic won&apos;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.</p>

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

      </answer>
    </faq>

    <faq id="defaultexcludes">

      <question>I&apos;ve used a <code>&lt;delete&gt;</code> task to
      delete unwanted SourceSafe control files (CVS files, editor
      backup files, etc.), but it doesn&apos;t seem to work; the files
      never get deleted. What&apos;s wrong?</question>

      <answer>
        <p>This is probably happening because, by default, Ant excludes
        SourceSafe control files (<code>vssver.scc</code>) and certain other
        files from FileSets.</p>

        <p>Here&apos;s what you probably did:</p>


        <source><![CDATA[
<delete>
  <fileset dir="${build.src}" includes="**/vssver.scc"/>
</delete>
]]></source>

        <p>You need to switch off the default exclusions,
           and it will work:</p>
        <source><![CDATA[
<delete>
  <fileset dir="${build.src}" includes="**/vssver.scc"
           defaultexcludes="no"/>
</delete>
]]></source>

        <p>For a complete listing of the patterns that are excluded
        by default, see <a href="manual/dirtasks.html#defaultexcludes">the user
        manual</a>.</p>

      </answer>
    </faq>

    <faq id="stop-dependency">
      <question>I have a target I want to skip if a property is set,
      so I have <code>unless=&quot;property&quot;</code> as an attribute
      of the target, but all the targets this target
      depends on are still executed. Why?</question>

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

        <p>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:
        </p>

        <ol>
          <li>Put the same condition on each of the dependent targets.</li>

          <li>Execute the steps using <code>&lt;antcall&gt;</code>,
          instead of specifying them inside the <code>depends</code>
          attribute.</li>
        </ol>

      </answer>
    </faq>

    <faq id="include-order">
      <question>In my <code>&lt;fileset&gt;</code>, I&apos;ve put in an
      <code>&lt;exclude&gt;</code> of all files followed by an
      <code>&lt;include&gt;</code> of just the files I want, but it
      isn&apos;t giving me any files at all. What&apos;s wrong?
      </question>

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

        <p>To get the files you want, focus on just the
        <code>&lt;include&gt;</code> patterns that would be necessary
        to get them. If you find you need to trim the list that the
        <code>&lt;include&gt;</code> elements produce, then use
        <code>&lt;exclude&gt;</code> elements.</p>
      </answer>
    </faq>

    <faq id="properties-not-trimmed">
      <question><code>ant</code> failed to build my program via javac
      even when I put the needed jars in an external
      <code>build.properties</code> file and reference them by
      <code>pathelement</code> or <code>classpath refid</code>.</question>

      <answer>

        <p>When <code>ant</code> loads properties from an external
        file it doesn&apos;t touch the value of properties, trailing blanks
        will not be trimmed for example.</p>

        <p>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&apos;t find the file due to
        trailing spaces.</p>
      </answer>
    </faq>

    <faq id="winzip-lies">
      <question>Ant creates WAR files with a lower-case
        <code>web-inf</code> or JAR files with a lower-case
        <code>meta-inf</code> directory.</question>

      <answer>
        <p>No it doesn&apos;t.</p>

        <p>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.</p>

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

        <p>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.</p>
      </answer>
    </faq>

    <faq id="NoClassDefFoundError">
      <question>I installed Ant 1.6.x and now get
        <code>Exception in thread "main" java.lang.NoClassDefFoundError:
        </code>
      </question>
      <answer>
        <p>
          The cause of this is that there is an old version of ant somewhere in the
          class path or configuration.
        </p>
        <p>
          A version of this problem happens with jars that are in the classpath
          that include an embedded copy of ant classes.
          An example of this is some copies of weblogic.jar.
        </p>
        <p>
        One can check if this is the case by doing (on unix/sh):
        <code><pre>
        unset CLASSPATH
        ant -version
        </pre>
        </code>
        </p>
      </answer>
    </faq>

    <faq id="InstantiationException">
      <question>I installed Ant 1.6.x and now get
        <code>java.lang.InstantiationException: org.apache.tools.ant.Main</code>
      </question>
      <answer>
        <p>
          The cause of this is that there is an old version of ant somewhere in the
          class path or configuration.
        </p>
        <p>
          A version of this problem may be seen on some linux systems.
          Some linux systems (Fedora Core 2 for example), comes with a version
          of ant pre-installed. There is a configuration file called
          <code>/etc/ant.conf</code> which if present, the ant shell
          script will 'dot' include. On Fedora Core 2, the /etc/ant.conf
          file resets the <code>ANT_HOME</code> environment variable to
          <code>/usr/share/ant</code>. This causes the problem that
          an old version of ant (1.5.x in this cause) will be used
          with a new version of the ant script file.
        </p>
        <p>
          One can check if this is the case by doing
          <code>ant --noconfig -version</code>.
        </p>
      </answer>
    </faq>
    <faq id="mangled-manifest">
      <question>
        Whenever I use the Ant jar or manifest related tasks, long lines in
        my manifest are wrapped at 70 characters and the resulting jar does
        not work in my application server. Why does Ant do this?
      </question>

      <answer>
        <p>
          Ant implements the Java
          <a href="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html">Jar
          file specification</a>. Please refer to the notes section where it
          discusses the maximum allowable length of a line and the concept of
          continuation characters.
        </p>

        <p>
          If a jar file produced by Ant does not work in your appserver, and
          that failure is due to the wrapped manifest, then you need
          to consult your appserver provider, as it is a bug in their
          appserver. Far more likely, however, is a problem in your
          specification of your classpath. It is not Ant's wrapping of your
          classpath that is the problem.
        </p>

        <p>
          Do not raise a bug about this issue until you have checked to ensure
          that the problem is not due to your classpath specification.
        </p>
      </answer>
    </faq>

  </faqsection>

  <faqsection title="Ant and IDEs/Editors">
    <faq id="integration">
      <question>Is Ant supported by my IDE/Editor?</question>
      <answer>
        <p>See the <a href="external.html#IDE and Editor Integration">section
        on IDE integration</a> on our External Tools and Tasks page.</p>
      </answer>
    </faq>

    <faq id="emacs-mode">
      <question>Why doesn&apos;t (X)Emacs/vi/MacOS X&apos;s project builder
      correctly parse the error messages generated by Ant?</question>
      <answer>

        <p>Ant adds a &quot;banner&quot; 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.</p>

        <p>You can disable this banner by invoking Ant with the
        <code>-emacs</code> switch.  To make Ant autodetect
        Emacs&apos; compile mode, put this into your
        <code>.antrc</code> (contributed by Ville Skytt&#228;).</p>

        <source><![CDATA[
# Detect (X)Emacs compile mode
if [ "$EMACS" = "t" ] ; then
  ANT_ARGS="$ANT_ARGS -emacs"
  ANT_OPTS="$ANT_OPTS -Dbuild.compiler.emacs=true"
fi
]]></source>

        <p>Alternatively, you can add the following snippet to your
        <code>.emacs</code> to make Emacs understand Ant&apos;s
        output.</p>

        <source><![CDATA[
(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))
]]></source>

        <p>Yet another alternative that preserves most of Ant&apos;s
        formatting is to pipe Ant&apos;s output through the following Perl
        script by Dirk-Willem van Gulik:</p>

        <source><![CDATA[
#!/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;
};
]]></source>

      </answer>
    </faq>
  </faqsection>

  <faqsection title="Advanced Issues">
    <faq id="dtd">
      <question>Is there a DTD that I can use to validate my build
      files?</question>

      <answer>

        <p>An incomplete DTD can be created by the
          <code>&lt;antstructure&gt;</code> task - but this one
          has a few problems:</p>

          <ul>
            <li>It doesn&apos;t know about required attributes.  Only
            manual tweaking of this file can help here.</li>

            <li>It is not complete - if you add new tasks via
            <code>&lt;taskdef&gt;</code> it won&apos;t know about it.  See
            <a href="http://www.sdv.fr/pages/casa/html/ant-dtd.en.html">this
            page</a> 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.</li>

            <li>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 <code>&lt;test&gt;</code> and
            <code>&lt;junit&gt;</code> tasks, there are two XML
            elements named <code>test</code> (the task and the nested child
            element of <code>&lt;junit&gt;</code>) with different attribute
            lists.  This problem cannot be solved; DTDs don&apos;t give a
            syntax rich enough to support this.</li>
          </ul>
      </answer>
    </faq>

    <faq id="xml-entity-include">
      <question>How do I include an XML snippet in my build file?</question>
      <answer>
        <p>You can use XML&apos;s way of including external files and let
        the parser do the job for Ant:</p>

        <source><![CDATA[
<?xml version="1.0"?>

<!DOCTYPE project [
       <!ENTITY common SYSTEM "common.xml">
]>

<project name="test" default="test" basedir=".">

  <target name="setup">
    ...
  </target>

  &common;

  ...

</project>
]]></source>

        <p>will literally include the contents of <code>common.xml</code> where
        you&apos;ve placed the <code>&amp;common;</code> entity.</p>

        <p>(The filename <code>common.xml</code> in this example is resolved
        relative to the containing XML file by the XML parser. You may also use
        an absolute <code>file:</code> protocol URI.)</p>

        <p>In combination with a DTD, this would look like this:</p>

        <source><![CDATA[
<!DOCTYPE project PUBLIC "-//ANT//DTD project//EN" "ant.dtd" [
   <!ENTITY include SYSTEM "header.xml">
]>
]]></source>

        <p>Starting with Ant 1.6, there is a new
        <code>&lt;import&gt;</code> 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.</p>

        <p>The example above would become:</p>
        <source><![CDATA[
<?xml version="1.0"?>
<project name="test" default="test" basedir=".">

  <target name="setup">
    ...
  </target>

  <import file="./common.xml"/>

  ...

</project>
]]></source>

        <p>Unlike entity includes, <code>&lt;import&gt;</code> will
        let you use Ant properties in the file name.</p>
      </answer>
    </faq>

    <faq id="mail-logger">
      <question>How do I send an email with the result of my build
        process?</question>

      <answer>

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

        <source><![CDATA[
         ant -logger org.apache.tools.ant.listener.MailLogger
]]></source>

        <p>See the <a href="http://svn.apache.org/repos/asf/ant/core/trunk/docs/manual/listeners.html">Listeners
        &amp; Loggers</a> documentation for details on the properties
        required.</p>

        <p>For older versions of Ant, you can use a custom
        BuildListener that sends out an email
        in the buildFinished() method.  Will Glozer
        &lt;will.glozer@jda.com&gt; has written such a listener based
        on <a href="http://java.sun.com/products/javamail/">JavaMail</a>.
        The source is:</p>

        <source><![CDATA[
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) {
    }
}
]]></source>

      <p>With a <code>monitor.properties</code> like this:</p>

        <source><![CDATA[
# 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!
]]></source>

        <p><code>monitor.properties</code> should be placed right next
        to your compiled <code>BuildMonitor.class</code>.  To use it,
        invoke Ant like:</p>

        <source><![CDATA[
ant -listener BuildMonitor -logfile build.log
]]></source>

        <p>Make sure that <code>mail.jar</code> from JavaMail and
        <code>activation.jar</code> from the
        <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">Java
        Beans Activation Framework</a> are in your <code>CLASSPATH</code>.</p>

      </answer>
    </faq>

    <faq id="listener-properties">
      <question>How do I get at the properties that Ant was running
      with from inside BuildListener?</question>

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

        <source><![CDATA[
public void buildFinished(BuildEvent e) {
    Hashtable table = e.getProject().getProperties();
    String buildpath = (String)table.get("build.path");
    ...
}
]]></source>

        <p>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.</p>
      </answer>
    </faq>

  </faqsection>

  <faqsection title="Known Problems">
    <faq id="input-makes-exec-hang">
      <question><code>&lt;exec&gt;</code> causes other tasks to hang
        or leads to strange behaviour of <code>&lt;input&gt;</code>
        tasks.</question>

      <answer>

        <p>When Ant forks a new process for example by using the
          <code>&lt;exec&gt;</code>, <code>&lt;apply&gt;</code>
          or <code>&lt;java&gt;</code> tasks, it will also start a
          new thread reading from standard input and sending
          everything that it has read to that process.</p>

        <p>Unfortunately Ant has no way to know whether the forked
          process is ever going to read any input, so it will start such
          a thread even if the process doesn't need one.</p>

        <p>This behaviour leads to strange side effects like the Ant
          process
          being <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=34461">suspended
          when a build forking new process is run as a background
          process</a> on Unix-like systems or
          <code>&lt;input&gt;</code>
          tasks <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=41024">requiring
          additional inputs</a> if they come after
          an <code>&lt;exec&gt;</code> task.</p>

        <p>Fortunately there is a workaround for this, always specify
          <code>inputstring=""</code> for
          any <code>&lt;exec&gt;</code> task (or one of its sibblings)
          if you know the forked process doesn't consume any
          input.</p>
      </answer>
    </faq>

    <faq id="javac-stackoverflow">
      <question><code>&lt;javac&gt;</code> causes a
        StackOverflowError</question>

      <answer>

        <p>For some Java source files it is possible
          that <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=45370">causes
          a StackOverlowError</a> is thrown inside Sun's javac
          compiler.  As far as we can tell this is not triggered by a
          bug in Ant.</p>

        <p>It is possible to work around this problem by setting 
          <code>&lt;javac&gt;</code>'s fork attribute to true.</p>
      </answer>
    </faq>

    <faq id="170-requires-junit">
      <question>Ant 1.7.0 doesn't build from sources without
        JUnit</question>

      <answer>

        <p>When building Ant 1.7.0 from the source release without
        junit.jar the build fails with the message "We cannot build
        the test jar unless JUnit is present".</p>

        <p>With Ant 1.7.0 we've started to add ant-testutil.jar as
        part of the distribution and this causes a hard dependency on
        JUnit - at least in version 1.7.0.  Unfortunately the
        installation docs don't say so.</p>

        <p>There are two workarounds:</p>

        <ol>

          <li>Add junit.jar to your CLASSPATH when building Ant.</li>

          <li>Change Ant's buildfile and remove test-jar from the
          depends list of the dist-lite target.</li>

        </ol>

      </answer>
    </faq>

    <faq id="remove-cr">
      <question>&lt;chmod&gt; or &lt;exec&gt; doesn&apos;t work in Ant
        1.3 on Unix</question>
      <answer>

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

        <source><![CDATA[
tr -d '\r' < $ANT_HOME/bin/antRun > /tmp/foo
mv /tmp/foo $ANT_HOME/bin/antRun
]]></source>
      </answer>
    </faq>

    <faq id="javadoc-cannot-execute">
      <question>JavaDoc failed: java.io.IOException: javadoc: cannot execute</question>
      <answer>
        <p>There is a bug in the Solaris reference implementation of
        the JDK (see <a href="http://developer.java.sun.com/developer/bugParade/bugs/4230399.html">http://developer.java.sun.com/developer/bugParade/bugs/4230399.html</a>).
        This also appears to be true under Linux. Moving the JDK to
        the front of the PATH fixes the problem.</p>
      </answer>
    </faq>

    <faq id="delegating-classloader">
      <question>&lt;style&gt; or &lt;junit&gt; ignores my
      &lt;classpath&gt;</question>

      <answer>
        <p>Starting with Ant 1.7.0, &lt;junit&gt; will honor your
        nested &lt;classpath&gt;.</p>

        <p>These tasks don&apos;t ignore your classpath setting, you
        are facing a common problem with delegating classloaders.</p>

        <p>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&apos;t work unless you put the external library
        into the <code>CLASSPATH</code> or place it in
        <code>ANT_HOME/lib</code>.</p>

        <p>Some background is necessary before we can discuss
        solutions for <a href="#delegating-classloader-1.5">Ant
        1.5.x</a> and <a href="#delegating-classloader-1.6">Ant
        1.6.x</a>.</p>

        <p>When you specify a nested <code>&lt;classpath&gt;</code> 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.</p>

        <p>In most cases - for example using &lt;style&gt; or
        &lt;junit&gt; - Ant doesn&apos;t load the external library
        directly, it is the loaded class that does so.</p>

        <p>In the case of <code>&lt;junit&gt;</code> it is the task
        implementation itself and in the case of
        <code>&lt;style&gt;</code> it is the implementation of the
        <code>org.apache.tools.ant.taskdefs.XSLTLiaison</code>
        class.</p>

        <p><em>As of Ant 1.7</em> <code>&lt;junit&gt;</code> no longer
        requires you to have <code>junit.jar</code> in Ant's startup
        classpath even if <code>ant-junit.jar</code> is present there.</p>

        <p>Ant&apos;s class loader implementation uses Java&apos;s
        delegation model, see <a
        href="http://java.sun.com/products/jdk/1.2/docs/api/java/lang/ClassLoader.html">http://java.sun.com/products/jdk/1.2/docs/api/java/lang/ClassLoader.html</a>
        the paragraph</p>

        <blockquote>The <code>ClassLoader</code> class uses a
        delegation model to search for classes and resources. Each
        instance of <code>ClassLoader</code> has an associated parent
        class loader.  When called upon to find a class or resource, a
        <code>ClassLoader</code> 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&apos;s built-in class loader, called the bootstrap
        class loader, does not itself have a parent but may serve as
        the parent of a <code>ClassLoader</code>
        instance.</blockquote>

        <p>The possible solutions depend on the version of Ant you
        use, see the next sections.</p>
      </answer>
    </faq>

    <faq id="delegating-classloader-1.5">
      <question>&lt;style&gt; or &lt;junit&gt; ignores my
      &lt;classpath&gt; - Ant 1.5.x version</question>

      <answer>

        <p>Please read <a href="#delegating-classloader">the previous
        entry</a> before you go ahead.</p>

        <p>First of all let&apos;s state that Ant's wrapper script
        (<code>ant</code> or <code>ant.bat</code>) adds all
        <code>.jar</code> files from <code>ANT_HOME/lib</code> to
        <code>CLASSPATH</code>, therefore &quot;in
        <code>CLASSPATH</code>&quot; shall mean &quot;either in your
        <code>CLASSPATH</code> environment variable or
        <code>ANT_HOME/lib</code>&quot; for the rest of this
        answer.</p>

        <p>The root of the problem is that the class that needs the
        external library is on the <code>CLASSPATH</code>.</p>

        <p>Let's see what happens when you load the &lt;junit&gt;
        task.  Ant&apos;s class loader will consult the
        bootstrap class loader first, which tries to load classes from
        <code>CLASSPATH</code>.  The bootstrap class loader
        doesn&apos;t know anything about Ant&apos;s class loader or
        even the path you have specified.</p>

        <p>If the bootstrap class loader can load the class Ant has
        asked it to load (which it can if <code>optional.jar</code> is
        part of <code>CLASSPATH</code>), this class will try to load
        the external library from <code>CLASSPATH</code> as well - it
        doesn&apos;t know anything else - and will not find it unless
        the library is in <code>CLASSPATH</code> as well.</p>

        <p>To solve this, you have two major options:</p>

        <ol>
          <li>put all external libraries you need in
          <code>CLASSPATH</code> as well this is not what you want,
          otherwise you wouldn&apos;t have found this FAQ entry.</li>

          <li>remove the class that loads the external library from
          the <code>CLASSPATH</code>.</li>
        </ol>

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

        <p>If you want to avoid to <code>&lt;taskdef&gt;</code> 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 <code>optional.jar</code> and put them into a
        separate archive. Add this separate archive to the
        <code>&lt;classpath&gt;</code> of your
        <code>&lt;style&gt;</code> or <code>&lt;junit&gt;</code> task
        - and make sure the separate archive is not in
        <code>CLASSPATH</code>.</p>

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

        <p>If you use the option to break up <code>optional.jar</code>
        for <code>&lt;junit&gt;</code> or remove
        <code>ant-junit.jar</code>, you still have to use a
        <code>&lt;taskdef&gt;</code> with a nested
        <code>&lt;classpath&gt;</code> to define the junit task.</p>
      </answer>
    </faq>

    <faq id="delegating-classloader-1.6">
      <question>&lt;style&gt; or &lt;junit&gt; ignores my
      &lt;classpath&gt; - Ant 1.6.x version</question>

      <answer>
        <p>Please read <a href="#delegating-classloader">the general
        entry</a> before you go ahead.</p>

        <p>The wrapper script of Ant 1.6.x no longer adds the contents
        of <code>ANT_HOME/lib</code> to <code>CLASSPATH</code>,
        instead Ant will create a classloader on top of the bootstrap
        classloader - let's call it the coreloader for the rest of
        this answer - which holds the contents of
        <code>ANT_HOME/lib</code>.  Ant's core and its tasks will be
        loaded through this classloader and not the bootstrap
        classloader.</p>

        <p>This causes some small but notable differences between Ant
        1.5.x and 1.6.x.  Most importantly, a third-party task that is
        part of <code>CLASSPATH</code> will no longer work in Ant
        1.6.x since the task now can't find Ant's classes.  In a sense
        this is the same problem this entry is about, only
        <code>ant.jar</code> has become the external library in
        question now.</p>

        <p>This coreloader also holds the contents of
        <code>~/.ant/lib</code> and any file or directory that has
        been specified using Ant's <code>-lib</code> command line
        argument.</p>

        <p>Let's see what happens when you load the &lt;junit&gt;
        task.  Ant&apos;s class loader will consult the bootstrap
        class loader first, which tries to load classes from
        <code>CLASSPATH</code>.  The bootstrap class loader
        doesn&apos;t know anything about Ant&apos;s class loader or
        even the path you have specified.  If it fails to find the
        class using the bootstrap classloader it will try the
        coreloader next.  Again, the coreloader doesn't know anything
        about your path.</p>

        <p>If the coreloader can load the class Ant has asked it to
        load (which it can if <code>ant-junit.jar</code> is in
        <code>ANT_HOME/lib</code>), this class will try to load the
        external library from coreloader as well - it doesn&apos;t
        know anything else - and will not find it unless the library
        is in <code>CLASSPATH</code> or the coreloader as well.</p>

        <p>To solve this, you have the following major options:</p>

        <ol>
          <li>put all external libraries you need in
          <code>CLASSPATH</code> as well this is not what you want,
          otherwise you wouldn&apos;t have found this FAQ entry.</li>

          <li>put all external libraries you need in
          <code>ANT_HOME/lib</code> or <code>.ant/lib</code>.  This
          probably still isn't what you want, but you might reconsider
          the <code>.ant/lib</code> option.</li>

          <li>Always start Ant with the <code>-lib</code> command line
          switch and point to your external libraries (or the
          directories holding them).</li>

          <li>remove the class that loads the external library from
          the coreloader.</li>
        </ol>

        <p>In Ant 1.6 <code>optional.jar</code> 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 <code>ANT_HOME/lib</code>.  For the
        <code>&lt;junit&gt;</code> task it would be
        <code>ant-junit.jar</code> and for <code>&lt;style&gt;</code>
        it would be <code>ant-trax.jar</code>
        or <code>ant-xslp.jar</code> - 
        depending on the processor you use.</p>

        <p>If you do so, you will have to <code>&lt;taskdef&gt;</code>
        all optional tasks that need the external library and use
        nested <code>&lt;classpath&gt;</code> elements in the
        <code>&lt;taskdef&gt;</code> tasks that point to the new
        location of <code>ant-*.jar</code>.  Also, don&apos;t forget
        to add the new location of <code>ant-*.jar</code> to the
        <code>&lt;classpath&gt;</code> of your
        <code>&lt;style&gt;</code> or <code>&lt;junit&gt;</code>
        task.</p>

        <p>For example</p>
        <source><![CDATA[
    <taskdef name="junit"
            class="org.apache.tools.ant.taskdefs.optional.junit.JUnitTask">
      <classpath>
        <pathelement location="HOME-OF/junit.jar"/>
        <pathelement location="NEW-HOME-OF/ant-junit.jar"/>
      </classpath>
    </taskdef>
]]></source>
      </answer>
    </faq>

    <faq id="winxp-jdk14-ant14">
      <question>When running Ant 1.4 on Windows XP and JDK 1.4, I get
      various errors when trying to <code>&lt;exec&gt;</code>, fork
      <code>&lt;java&gt;</code> or access environment
      variables.</question>

      <answer>

        <p>Ant &lt; 1.5 doesn&apos;t recognize Windows XP as a flavor
        of Windows that runs <code>CMD.EXE</code> instead of
        <code>COMMAND.COM</code>.  JDK 1.3 will tell Ant that Windows
        XP is Windows 2000 so the problem doesn&apos;t show up
        there.</p>

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

    <faq id="1.5-cygwin-sh">
      <question>The <code>ant</code> wrapper script of Ant 1.5 fails
      for Cygwin if <code>ANT_HOME</code> is set to a Windows style
      path.</question>
      <answer>

        <p>This problem has been reported only hours after Ant 1.5 has
        been released, see <a
        href="http://issues.apache.org/bugzilla/show_bug.cgi?id=10664">Bug
        10664</a> and all its duplicates.</p>

        <p>A fixed version of the wrapper script can be found <a
        href="http://ant.apache.org/old-releases/v1.5/errata/">here</a>.
        Simply replace your script with this version.</p>
      </answer>
    </faq>

    <faq id="1.5.2-zip-broken">
      <question><code>&lt;zip&gt;</code> is broken in Ant 1.5.2.</question>
      <answer>

        <p>Yes, it is.</p>

        <p>The problem reported by most people - see <a
        href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17648">Bug
        17648</a> and all its duplicates - is that Ant creates
        archives that a partially unreadable by WinZIP.  Luckily
        <code>jar</code> deals with the archives and so the generated
        jars/wars/ears will most likely work for you anyway.</p>

        <p>There are additional problems, see bugs <a
        href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17780">Bug
        17780</a>, <a
        href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17871">Bug
        17871</a> and <a
        href="http://issues.apache.org/bugzilla/show_bug.cgi?id=18403">Bug
        18403</a>.  All of them are supposed to be fixed with Ant
        1.5.3 (and only 18403 should exist in 1.5.3beta1).</p>
      </answer>
    </faq>

    <faq id="unknownelement.taskcontainer">
      <question>
        Why do my custom task containers see Unknown Elements in Ant 1.6
        - they worked in Ant 1.5?
      </question>
      <answer>
        <p>
          The objects added in TaskContainer.addTask(Task task)
          have changed from  Tasks to UnknownElements.
        </p>
        <p>
          There was a number of valid reasons for this change. But the backward
          compatibility problems were not noticed until after Ant 1.6.0 was
          released.
        </p>
        <p>
          Your container class will need to be modified to check if the Task
          is an UnknownElement and call perform on it to
          convert it to a Task and to execute it.
          (see apache.tools.ant.taskdefs.Sequential)
        </p>
        <p>
          If you want to do more processing on the task,
          you need to use the techniques in apache.tools.ant.taskdefs.Antlib#execute()
          This does make use of one 1.6 method call (UE#getRealObject()),
          you need to use UE#getTask() instead - this will
          return null for non tasks (types like fileset id=x).
        </p>
        <p>
          So.. iterate over the tasks, if they are UEs, convert them to
          tasks, using UE#maybeConfigure and UE#getTask()
        </p>
        <source><![CDATA[
        for (Iterator i = tasks.iterator(); i.hasNext();) {
           Task t = (Task) i.next();
           if (t instanceof UnknownElement) {
              ((UnknownElement) t).maybeConfigure();
              t = ((UnknownElement) t).getTask();
              if (t == null) {
                  continue;
              }
           }
           // .... original Custom code
        }
        ]]></source>
        <p>
          This approach should work for ant1.5 and ant1.6.
        </p>
      </answer>
    </faq>

    <faq id="java.exception.stacktrace">
      <question>
        The program I run via &lt;java&gt; throws an exception but I
        can't seem to get the full stack trace.
      </question>
      <answer>
        <p>This is a know bug that has been fixed after the release of
        Ant 1.6.1.</p>

        <p>As a workaround, run your &lt;java&gt; task with
        <code>fork="true"</code> and Ant will display the full
        trace.</p>
      </answer>
    </faq>

    <faq id="junit-no-runtime-xml">
      <question>
        Using format=&quot;xml&quot;, &lt;junit&gt; fails with a
        <code>NoClassDefFoundError</code> if forked.
      </question>
      <answer>

        <p>The XML formatter needs the <a
        href="http://www.w3.org/DOM/">DOM classes</a> to work.  If you
        are using JDK 1.4 or later they are included with your Java
        Runtime and this problem won't occur.  If you are running JDK
        1.3 or earlier, the DOM classes have to be on your
        &lt;junit&gt; task's &lt;classpath&gt;.</p>

        <p>Prior to Ant 1.6.0 Ant would include the DOM classes from
        the XML parser that is used by Ant itself if you set the
        includeAntRuntime attribute to true (the default).  With Ant
        1.6.0 this has been changed as this behavior made it
        impossible to use a different XML parser in your tests.</p>

        <p>This means that you have to take care of the DOM classes
        explicitly starting with Ant 1.6.0.  If you don't need to set
        up a different XML parser for your tests, the easiest solution
        is to add</p>

        <source><![CDATA[
<pathelement path="${ant.home}/lib/xml-apis.jar:${ant.home}/lib/xercesImpl.jar"/>
]]></source>

        <p>to your task's &lt;classpath&gt;.</p>

      </answer>
    </faq>

    <faq id="xalan-jdk1.5">
      <question>
        <code>&lt;junitreport&gt;</code> doesn't work with JDK 1.5 but
        worked fine with JDK 1.4.
      </question>
      <answer>

        <p>While JDK 1.4.x contains a version of Xalan-J 2, JDK 1.5
        (and later?) have <a
        href="http://java.sun.com/j2se/1.5.0/compatibility.html#4959783">moved
        to XSLTC</a>.  Since this task uses Xalan's redirect
        extensions for its internal stylesheet, Ant prior to 1.6.2 didn't support
        XSLTC.  This means that you have to install <a
        href="http://xml.apache.org/xalan-j/">Xalan-J 2</a> in order
        to use this task with JDK 1.5 in older versions of Ant.</p>

        <p>Starting with Ant 1.6.2 <code>&lt;junitreport&gt;</code>
        supports JDK 1.5.</p>

      </answer>
    </faq>

    <faq id="oom-on-mac">
      <question>
        Ant runs into an infinite loop/throws an OutOufMemoryError
        when I compile my project under Mac OS X.
      </question>

      <answer>
        <p>Apple's Java VMs reside
        in <code>/System/Library/Frameworks/JavaVM.framework/Versions/X.Y.Z</code>
          and <code>JAVA_HOME</code> will usually be something
        like <code>/System/Library/Frameworks/JavaVM.framework/Versions/X.Y.Z/Home</code>.</p>

        <p>Inside this home directory there is a symbolic link
        named <code>shared_bundle</code> that links three levels up,
        i.e. to <code>/System/Library/Frameworks/JavaVM.framework</code>.</p>

        <p>If your build file contains a <code>fileset</code> like</p>
        <source><![CDATA[
<fileset dir="${java.home}" includes="**/*.jar"/>
]]></source>
        <p>Ant is going to follow the <code>shared_bundle</code>
        symlink and ends up recursing into all your installed VMs.
        Even worse, it will
        enter <code>/System/Library/Frameworks/JavaVM.framework/Versions/X.Y.Z/Home</code>
          and will once again follow the same symlink.</p>

        <p>Ant versions after Ant 1.7.1 will detect the infinite loop
        they are in, but the resulting fileset may still be too big to
        deal with, in particular if you have many different VM
        versions installed.  The problem is amplified by the fact that
        each installed version has a <code>shared_bundle</code>
        symlink in it.</p>

        <p>One solution is to not allow the fileset to follow symbolic
          links at all, like in</p>
        <source><![CDATA[
<fileset dir="${java.home}" includes="**/*.jar" followsymlinks="false"/>
]]></source>
        <p>another one excludes the <code>shared_bundle</code>
        directories:</p>
        <source><![CDATA[
<fileset dir="${java.home}" includes="**/*.jar" excludes="**/shared_bundle/**"/>
]]></source>

        <p>For Ant 1.7.1 and earlier
        excluding <code>shared_bundle</code> may not be enough since
        there is another symlink <code>bundle</code> that points to
        the <code>Home</code> directory and will cause infite
        recursions as well.</p>
      </answer>
    </faq>
  </faqsection>

</document>