youys
/
ant
Not watched
1
0
Fork 1
Code
Releases 0 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tree: 9130ea784d
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '9130ea784d'
${ noResults }
ant/docs/faq.html

2006 lines
86 KiB
Raw Blame History 

  1. 

  2. 

  3. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

  4.         <html lang="en">

  5.     <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->

  6.     <head>

  7.       <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

  8.         <title>Apache Ant - Frequently Asked Questions</title>

  9.         <link type="text/css" href="./page.css" rel="stylesheet">

  10.           <meta name="author" content="Stefan Bodewig">

  11.   <meta name="email" content="bodewig@apache.org">

  12.       </head>

  13. 

  14.     <body>

  15.       <p class="navpath">

  16.         <script src="./breadcrumbs.js" language="JavaScript" type="text/javascript"></script>

  17.       </p>

  18. 

  19.       <div class="logobar">

  20.         <table width="100%" border="0" cellspacing="0" cellpadding="0">

  21.           <tr>

  22.             <td align="left"><img border="0" alt="Apache Ant site" src="./images/group-logo.gif"></td>

  23.             <td align="center" width="100%"><img alt="Apache Ant logo" border="0" src="./images/project-logo.gif"></td>

  24.             <td align="right">

  25.               <form target="_blank" onsubmit="q.value = query.value + ' site:ant.apache.org'" action="http://www.google.com/search" method="get">

  26.                 <table summary="search" border="0" cellspacing="0" cellpadding="0" bgcolor="#4C6C8F">

  27.                   <tr>

  28.                     <td colspan="3"><img height="10" width="1" alt="" src="./images/spacer.gif"></td>

  29.                   </tr>

  30.                   <tr>

  31.                     <td><img height="1" width="1" alt="" src="./images/spacer.gif"></td>

  32.                     <td nowrap="nowrap" class="searchcaption">

  33.                       <input name="q" type="hidden">

  34.                       <input size="15" id="query" type="text">

  35.                       <img height="1" width="5" alt="" src="./images/spacer.gif">

  36.                       <input name="Search" value="Search" type="submit">

  37.                       <br>

  38.                       the Apache Ant site

  39.                     </td>

  40.                     <td><img height="1" width="1" alt="" src="./images/spacer.gif"></td>

  41.                   </tr>

  42.                   <tr>

  43.                     <td><img alt="" border="0" height="10" width="9" src="./images/search-left.gif"></td>

  44.                     <td><img height="1" width="1" alt="" src="./images/spacer.gif"></td>

  45.                     <td><img alt="" border="0" height="10" width="9" src="./images/search-right.gif"></td>

  46.                   </tr>

  47.                 </table>

  48.               </form>

  49.             </td>

  50.           </tr>

  51.         </table>

  52.       </div>

  53. 

  54.                   <div class="tab">

  55.               <table summary="tab bar" border="0" cellpadding="0" cellspacing="0">

  56.                 <tr>

  57.                                   <td width="8"><img alt="" height="5" width="8" src="./images/spacer.gif"></td><td valign="bottom">

  58.                       <table summary="selected tab" style="height: 1.5em" border="0" cellpadding="0" cellspacing="0">

  59.                         <tr>

  60.                         <td valign="top" width="5" bgcolor="#4C6C8F"><img height="5" width="5" alt="" src="./images/tabSel-left.gif"></td><td valign="middle" bgcolor="#4C6C8F"><font color="#ffffff" size="2" face="Arial, Helvetica, Sans-serif"><b>Home</b></font></td><td valign="top" width="5" bgcolor="#4C6C8F"><img height="5" width="5" alt="" src="./images/tabSel-right.gif"></td>

  61.                         </tr>

  62.                       </table>

  63.                     </td>

  64.                                     <td width="5"><img alt="" height="8" width="8" src="./images/spacer.gif"></td><td valign="bottom">

  65.                       <table summary="non selected tab" style="height: 1.4em" border="0" cellpadding="0" cellspacing="0">

  66.                         <tr>

  67.                           <td valign="top" width="5" bgcolor="#B2C4E0"><img height="5" width="5" alt="" src="./images/tab-left.gif"></td><td valign="middle" bgcolor="#B2C4E0"><a href="./projects/index.html"><font size="2" face="Arial, Helvetica, Sans-serif">Projects</font></a></td><td valign="top" width="5" bgcolor="#B2C4E0"><img height="5" width="5" alt="" src="./images/tab-right.gif"></td>

  68.                         </tr>

  69.                       </table>

  70.                     </td>

  71.                             </tr>

  72.               </table>

  73.             </div>

  74. 

  75.       <div class="bluebar"></div>

  76.                     

  77.   <div class="menucontainer">

  78.     <div align="center">

  79.       <a href="http://ApacheCon.Com/"><img width="135" height="50"

  80.              border="0" style="background-color: white"

  81.              src="http://apache.org/images/ac2005eu_135x50.gif"

  82.              alt="ApacheCon!" title="Come to ApacheCon!"/></a>

  83.     </div>

  84.     <div class="menu">

  85.       <ul>

  86.               <li class="menuheader">Apache Ant

  87.           <ul>

  88.                             <li>

  89.                                     <a href="./index.html">Welcome</a>

  90.                                 </li>

  91.                             <li>

  92.                                     <a href="./license.html">License</a>

  93.                                 </li>

  94.                             <li>

  95.                                     <a href="./antnews.html">News</a>

  96.                                 </li>

  97.                       </ul>

  98.         </li>

  99.               <li class="menuheader">Documentation

  100.           <ul>

  101.                             <li>

  102.                                     <a href="./manual/index.html">Manual</a>

  103.                                 </li>

  104.                             <li>

  105.                                     <a href="./projects.html">Related Projects</a>

  106.                                 </li>

  107.                             <li>

  108.                                     <a href="./external.html">External Tools and Tasks</a>

  109.                                 </li>

  110.                             <li>

  111.                                     <a href="./resources.html">Resources</a>

  112.                                 </li>

  113.                             <li>

  114.                               <span class="sel">Frequently Asked Questions</span>

  115.                               </li>

  116.                             <li>

  117.                                     <a href="http://wiki.apache.org/ant/FrontPage">Wiki</a>

  118.                                 </li>

  119.                             <li>

  120.                                     <a href="./problems.html">Having Problems?</a>

  121.                                 </li>

  122.                       </ul>

  123.         </li>

  124.               <li class="menuheader">Download

  125.           <ul>

  126.                             <li>

  127.                                     <a href="http://ant.apache.org/bindownload.cgi">Binary Distributions</a>

  128.                                 </li>

  129.                             <li>

  130.                                     <a href="http://ant.apache.org/srcdownload.cgi">Source Distributions</a>

  131.                                 </li>

  132.                       </ul>

  133.         </li>

  134.               <li class="menuheader">Contributing

  135.           <ul>

  136.                             <li>

  137.                                     <a href="./mail.html">Mailing Lists</a>

  138.                                 </li>

  139.                             <li>

  140.                                     <a href="./cvs.html">CVS Repositories</a>

  141.                                 </li>

  142.                             <li>

  143.                                     <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Ant">Bug Database</a>

  144.                                 </li>

  145.                             <li>

  146.                                     <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Ant&amp;bug_severity=enhancement">Enhancement Requests</a>

  147.                                 </li>

  148.                             <li>

  149.                                     <a href="http://www.apache.org/foundation/contributing.html">Donations</a>

  150.                                 </li>

  151.                       </ul>

  152.         </li>

  153.               <li class="menuheader">Project Management

  154.           <ul>

  155.                             <li>

  156.                                     <a href="./contributors.html">Contributors</a>

  157.                                 </li>

  158.                             <li>

  159.                                     <a href="./mission.html">Apache Ant Mission</a>

  160.                                 </li>

  161.                             <li>

  162.                                     <a href="./bylaws.html">Project Bylaws</a>

  163.                                 </li>

  164.                             <li>

  165.                                     <a href="./legal.html">Legal</a>

  166.                                 </li>

  167.                       </ul>

  168.         </li>

  169.             </ul>

  170.     </div>

  171.     <img style="float: left" height="10" width="10" border="0" alt="" src="./images/menu-left.gif">

  172.     <img style="float: right" height="10" width="10" border="0" alt="" src="./images/menu-right.gif">

  173.   </div>

  174.       <div class="lightbluebar">&nbsp;</div>

  175.   <div class="main">

  176.   <div class="content">

  177.     <h1 class="title">Frequently Asked Questions</h1>

  178.     

  179.         <h3 class="section">Questions</h3>

  180.                 <h4 class="toc">About this FAQ</h4>

  181.         <ul>

  182.                 <li><a href="#latest-version">

  183.   Where do I find the latest version of this

  184.         document?

  185.       </a></li>

  186.                 <li><a href="#adding-faqs">

  187.   How can I contribute to this FAQ?

  188.       </a></li>

  189.                 <li><a href="#creating-faq">

  190.   How do you create the HTML version of this

  191.         FAQ?

  192.       </a></li>

  193.             </ul>

  194.                 <h4 class="toc">General</h4>

  195.         <ul>

  196.                 <li><a href="#what-is-ant">

  197.   What is Apache Ant?

  198.       </a></li>

  199.                 <li><a href="#ant-name">

  200.   Why do you call it Ant?

  201.       </a></li>

  202.                 <li><a href="#history">

  203.   Tell us a little bit about Ant's history.

  204.       </a></li>

  205.             </ul>

  206.                 <h4 class="toc">Installation</h4>

  207.         <ul>

  208.                 <li><a href="#no-gnu-tar">

  209.   I get checksum errors when I try to extract the

  210.       <code>tar.gz</code> distribution file. Why?

  211.       </a></li>

  212.                 <li><a href="#RedHat_ES_3">

  213.   How do you get ant-1.6.x (or any version later than

  214.       1.5.2) to work on on RedHat ES 3?

  215.       </a></li>

  216.             </ul>

  217.                 <h4 class="toc">How do I ...</h4>

  218.         <ul>

  219.                 <li><a href="#implement-os-specific-configuration">

  220.   How do I realize os--specific configurations?

  221.       </a></li>

  222.                 <li><a href="#adding-external-tasks">

  223.   How do I add an external task that I've written to the

  224.       page "External Tools and Tasks"?

  225.       </a></li>

  226.                 <li><a href="#create-extensions">

  227.   How do I create new tasks?

  228.       </a></li>

  229.                 <li><a href="#passing-cli-args">

  230.   How do I pass parameters from the command line to my

  231.         build file?

  232.       </a></li>

  233.                 <li><a href="#jikes-switches">

  234.   How can I use Jikes-specific command-line

  235.         switches?

  236.       </a></li>

  237.                 <li><a href="#shell-redirect-1">

  238.   How do I include a &lt; character in my command-line arguments?

  239.       </a></li>

  240.                 <li><a href="#shell-redirect-2">

  241.   How do I redirect standard input or standard output

  242.         in the <code>&lt;exec&gt;</code> task?

  243.       </a></li>

  244.                 <li><a href="#batch-shell-execute">

  245.   How do I execute a batch file or shell script from Ant?

  246.       </a></li>

  247.                 <li><a href="#multi-conditions">

  248.   I want to execute a particular target only if

  249.         multiple conditions are true.

  250.       </a></li>

  251.                 <li><a href="#encoding">

  252.   How can I include national characters like German

  253.         umlauts in my build file?

  254.       </a></li>

  255.                 <li><a href="#use-zip-instead-of-jar">

  256.   How do I use <code>jar</code>'s <code>M</code> switch?

  257.       I don't want a MANIFEST.

  258.       </a></li>

  259.                 <li><a href="#propertyvalue-as-name-for-property">

  260.   How can I do something like <code>&lt;property name="prop"

  261.       value="${${anotherprop}}"/&gt;</code> (double expanding the property)?

  262.       </a></li>

  263.             </ul>

  264.                 <h4 class="toc">It doesn't work (as expected)</h4>

  265.         <ul>

  266.                 <li><a href="#genral-advice">

  267.   General Advice

  268.       </a></li>

  269.                 <li><a href="#always-recompiles">

  270.   Why does Ant always recompile all my Java files?

  271.       </a></li>

  272.                 <li><a href="#defaultexcludes">

  273.   I've used a <code>&lt;delete&gt;</code> task to

  274.       delete unwanted SourceSafe control files (CVS files, editor

  275.       backup files, etc.), but it doesn't seem to work; the files

  276.       never get deleted. What's wrong?

  277.       </a></li>

  278.                 <li><a href="#stop-dependency">

  279.   I have a target I want to skip if a property is set,

  280.       so I have <code>unless="property"</code> as an attribute

  281.       of the target, but all the targets this target

  282.       depends on are still executed. Why?

  283.       </a></li>

  284.                 <li><a href="#include-order">

  285.   In my <code>&lt;fileset&gt;</code>, I've put in an

  286.       <code>&lt;exclude&gt;</code> of all files followed by an

  287.       <code>&lt;include&gt;</code> of just the files I want, but it

  288.       isn't giving me any files at all. What's wrong?

  289.       

  290.       </a></li>

  291.                 <li><a href="#properties-not-trimmed">

  292.   <code>ant</code> failed to build my program via javac

  293.       even when I put the needed jars in an external

  294.       <code>build.properties</code> file and reference them by

  295.       <code>pathelement</code> or <code>classpath refid</code>.

  296.       </a></li>

  297.                 <li><a href="#winzip-lies">

  298.   Ant creates WAR files with a lower-case

  299.         <code>web-inf</code> or JAR files with a lower-case

  300.         <code>meta-inf</code> directory.

  301.       </a></li>

  302.                 <li><a href="#NoClassDefFoundError">

  303.   I installed Ant 1.6.x and now get

  304.         <code>Exception in thread "main" java.lang.NoClassDefFoundError:

  305.         </code>

  306.       

  307.       </a></li>

  308.                 <li><a href="#InstantiationException">

  309.   I installed Ant 1.6.x and now get

  310.         <code>java.lang.InstantiationException: org.apache.tools.ant.Main</code>

  311.       

  312.       </a></li>

  313.                 <li><a href="#mangled-manifest">

  314.   

  315.         Whenever I use the Ant jar or manifest related tasks, long lines in

  316.         my manifest are wrapped at 70 characters and the resulting jar does 

  317.         not work in my application server. Why does Ant do this?

  318.       

  319.       </a></li>

  320.             </ul>

  321.                 <h4 class="toc">Ant and IDEs/Editors</h4>

  322.         <ul>

  323.                 <li><a href="#integration">

  324.   Is Ant supported by my IDE/Editor?

  325.       </a></li>

  326.                 <li><a href="#emacs-mode">

  327.   Why doesn't (X)Emacs/vi/MacOS X's project builder

  328.       correctly parse the error messages generated by Ant?

  329.       </a></li>

  330.             </ul>

  331.                 <h4 class="toc">Advanced Issues</h4>

  332.         <ul>

  333.                 <li><a href="#dtd">

  334.   Is there a DTD that I can use to validate my build

  335.       files?

  336.       </a></li>

  337.                 <li><a href="#xml-entity-include">

  338.   How do I include an XML snippet in my build file?

  339.       </a></li>

  340.                 <li><a href="#mail-logger">

  341.   How do I send an email with the result of my build

  342.         process?

  343.       </a></li>

  344.                 <li><a href="#listener-properties">

  345.   How do I get at the properties that Ant was running

  346.       with from inside BuildListener?

  347.       </a></li>

  348.             </ul>

  349.                 <h4 class="toc">Known Problems</h4>

  350.         <ul>

  351.                 <li><a href="#remove-cr">

  352.   &lt;chmod&gt; or &lt;exec&gt; doesn't work in Ant

  353.         1.3 on Unix

  354.       </a></li>

  355.                 <li><a href="#javadoc-cannot-execute">

  356.   JavaDoc failed: java.io.IOException: javadoc: cannot execute

  357.       </a></li>

  358.                 <li><a href="#delegating-classloader">

  359.   &lt;style&gt; or &lt;junit&gt; ignores my

  360.       &lt;classpath&gt;

  361.       </a></li>

  362.                 <li><a href="#delegating-classloader-1.5">

  363.   &lt;style&gt; or &lt;junit&gt; ignores my

  364.       &lt;classpath&gt; - Ant 1.5.x version

  365.       </a></li>

  366.                 <li><a href="#delegating-classloader-1.6">

  367.   &lt;style&gt; or &lt;junit&gt; ignores my

  368.       &lt;classpath&gt; - Ant 1.6.x version

  369.       </a></li>

  370.                 <li><a href="#winxp-jdk14-ant14">

  371.   When running Ant 1.4 on Windows XP and JDK 1.4, I get

  372.       various errors when trying to <code>&lt;exec&gt;</code>, fork

  373.       <code>&lt;java&gt;</code> or access environment

  374.       variables.

  375.       </a></li>

  376.                 <li><a href="#1.5-cygwin-sh">

  377.   The <code>ant</code> wrapper script of Ant 1.5 fails

  378.       for Cygwin if <code>ANT_HOME</code> is set to a Windows style

  379.       path.

  380.       </a></li>

  381.                 <li><a href="#1.5.2-zip-broken">

  382.   <code>&lt;zip&gt;</code> is broken in Ant 1.5.2.

  383.       </a></li>

  384.                 <li><a href="#unknownelement.taskcontainer">

  385.   

  386.         Why do my custom task containers see Unknown Elements in Ant 1.6

  387.         - they worked in Ant 1.5?

  388.       

  389.       </a></li>

  390.                 <li><a href="#java.exception.stacktrace">

  391.   

  392.         The program I run via &lt;java&gt; throws an exception but I

  393.         can't seem to get the full stack trace.

  394.       

  395.       </a></li>

  396.                 <li><a href="#junit-no-runtime-xml">

  397.   

  398.         Using format="xml", &lt;junit&gt; fails with a

  399.         <code>NoClassDefFoundError</code> if forked.

  400.       

  401.       </a></li>

  402.                 <li><a href="#xalan-jdk1.5">

  403.   

  404.         <code>&lt;junitreport&gt;</code> doesn't work with JDK 1.5 but

  405.         worked fine with JDK 1.4.

  406.       

  407.       </a></li>

  408.             </ul>

  409.     

  410.       <h3 class="section">Answers</h3>

  411.                     <p class="faq">

  412.       <a name="latest-version"></a>

  413.       Where do I find the latest version of this

  414.         document?

  415.     </p>

  416.                   <p>The latest version can always be found at Ant's homepage

  417.           <a href="http://ant.apache.org/faq.html">http://ant.apache.org/faq.html</a>.</p>

  418.                     <p class="faq">

  419.       <a name="adding-faqs"></a>

  420.       How can I contribute to this FAQ?

  421.     </p>

  422.                   <p>The page you are looking it is generated from

  423.           <a href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/faq.xml">this</a>

  424.           document.  If you want to add a new question, please submit

  425.           a patch against this document to one of Ant's mailing lists;

  426.           hopefully, the structure is self-explanatory.</p>

  427.                         <p>If you don't know how to create a patch, see the patches

  428.           section of <a href="http://jakarta.apache.org/site/source.html">this

  429.           page</a>.</p>

  430.                     <p class="faq">

  431.       <a name="creating-faq"></a>

  432.       How do you create the HTML version of this

  433.         FAQ?

  434.     </p>

  435.                   <p>We use

  436.         <a href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a>

  437.         to render the HTML version from the original XML file.</p>

  438.                         <p>The Velocity stylesheets used to process the XML files can

  439.         be found in the <code>xdocs/stylesheets</code> subdirectory of

  440.         Ant's CVS repository - the build file

  441.         <code>docs.xml</code> at the top level of the ant CVS

  442.         module is used to drive Anakia.</p>

  443.                         <p>This file assumes that you have the

  444.         <code>jakarta-site2</code> CVS module checked out as well, but

  445.         if you follow the instruction from Anakia's homepage, you

  446.         should get it to work without that.  Just make sure all

  447.         required jars are in the task's classpath.</p>

  448.                                 <p class="faq">

  449.       <a name="what-is-ant"></a>

  450.       What is Apache Ant?

  451.     </p>

  452.                   <p> Ant is a Java-based build tool. In theory, it is kind of

  453.         like Make, without Make's wrinkles and with the full

  454.         portability of pure Java code.</p>

  455.                     <p class="faq">

  456.       <a name="ant-name"></a>

  457.       Why do you call it Ant?

  458.     </p>

  459.                   <p>According to Ant's original author, James Duncan

  460.         Davidson, the name is an acronym for "Another Neat

  461.         Tool".</p>

  462.                         <p>Later explanations go along the lines of "ants

  463.         do an extremely good job at building things", or

  464.         "ants are very small and can carry a weight dozens of times

  465.         their own" - describing what Ant is intended to

  466.         be.</p>

  467.                     <p class="faq">

  468.       <a name="history"></a>

  469.       Tell us a little bit about Ant's history.

  470.     </p>

  471.                   <p>Initially, Ant was part of the Tomcat code base, when it was

  472.         donated to the Apache Software Foundation. It was

  473.         created by James Duncan Davidson, who is also the original

  474.         author of Tomcat. Ant was there to build Tomcat, nothing

  475.         else.</p>

  476.                         <p>Soon thereafter, several open source Java projects realized

  477.         that Ant could solve the problems they had with Makefiles.

  478.         Starting with the projects hosted at Jakarta and the old Java

  479.         Apache project, Ant spread like a virus and is now the build

  480.         tool of choice for a lot of projects.</p>

  481.                         <p>In January 2000, Ant was moved to a separate CVS module and

  482.         was promoted to a project of its own, independent of

  483.         Tomcat, and became Apache Ant.</p>

  484.                         <p>The first version of Ant that was exposed to a larger audience

  485.         was the one that shipped with Tomcat's 3.1 release on 19 April

  486.         2000.  This version has later been referred to as Ant

  487.         0.3.1.</p>

  488.                         <p>The first official release of Ant as a stand-alone product was

  489.         Ant 1.1, released on 19 July 2000.  The complete release

  490.         history:</p>

  491.                               <table class="ForrestTable" cellspacing="1" cellpadding="4">

  492.               <tr>

  493.                       <th colspan="1" rowspan="1"

  494.       valign="top" align="left">

  495.           Ant Version

  496.       </th>

  497.                           <th colspan="1" rowspan="1"

  498.       valign="top" align="left">

  499.           Release Date

  500.       </th>

  501.       </tr>

  502.                   <tr>

  503.                       <td colspan="1" rowspan="1"

  504.       valign="top" align="left">

  505.           1.1

  506.       </td>

  507.                           <td colspan="1" rowspan="1"

  508.       valign="top" align="left">

  509.           19 July 2000

  510.       </td>

  511.       </tr>

  512.                   <tr>

  513.                       <td colspan="1" rowspan="1"

  514.       valign="top" align="left">

  515.           1.2

  516.       </td>

  517.                           <td colspan="1" rowspan="1"

  518.       valign="top" align="left">

  519.           24 October 2000

  520.       </td>

  521.       </tr>

  522.                   <tr>

  523.                       <td colspan="1" rowspan="1"

  524.       valign="top" align="left">

  525.           1.3

  526.       </td>

  527.                           <td colspan="1" rowspan="1"

  528.       valign="top" align="left">

  529.           3 March 2001

  530.       </td>

  531.       </tr>

  532.                   <tr>

  533.                       <td colspan="1" rowspan="1"

  534.       valign="top" align="left">

  535.           1.4

  536.       </td>

  537.                           <td colspan="1" rowspan="1"

  538.       valign="top" align="left">

  539.           3 September 2001

  540.       </td>

  541.       </tr>

  542.                   <tr>

  543.                       <td colspan="1" rowspan="1"

  544.       valign="top" align="left">

  545.           1.4.1

  546.       </td>

  547.                           <td colspan="1" rowspan="1"

  548.       valign="top" align="left">

  549.           11 October 2001

  550.       </td>

  551.       </tr>

  552.                   <tr>

  553.                       <td colspan="1" rowspan="1"

  554.       valign="top" align="left">

  555.           1.5

  556.       </td>

  557.                           <td colspan="1" rowspan="1"

  558.       valign="top" align="left">

  559.           10 July 2002

  560.       </td>

  561.       </tr>

  562.                   <tr>

  563.                       <td colspan="1" rowspan="1"

  564.       valign="top" align="left">

  565.           1.5.1

  566.       </td>

  567.                           <td colspan="1" rowspan="1"

  568.       valign="top" align="left">

  569.           3 October 2002

  570.       </td>

  571.       </tr>

  572.                   <tr>

  573.                       <td colspan="1" rowspan="1"

  574.       valign="top" align="left">

  575.           1.5.2

  576.       </td>

  577.                           <td colspan="1" rowspan="1"

  578.       valign="top" align="left">

  579.           3 March 2003

  580.       </td>

  581.       </tr>

  582.                   <tr>

  583.                       <td colspan="1" rowspan="1"

  584.       valign="top" align="left">

  585.           1.5.3

  586.       </td>

  587.                           <td colspan="1" rowspan="1"

  588.       valign="top" align="left">

  589.           9 April 2003

  590.       </td>

  591.       </tr>

  592.                   <tr>

  593.                       <td colspan="1" rowspan="1"

  594.       valign="top" align="left">

  595.           1.5.4

  596.       </td>

  597.                           <td colspan="1" rowspan="1"

  598.       valign="top" align="left">

  599.           12 August 2003

  600.       </td>

  601.       </tr>

  602.                   <tr>

  603.                       <td colspan="1" rowspan="1"

  604.       valign="top" align="left">

  605.           1.6.0

  606.       </td>

  607.                           <td colspan="1" rowspan="1"

  608.       valign="top" align="left">

  609.           18 December 2003

  610.       </td>

  611.       </tr>

  612.                   <tr>

  613.                       <td colspan="1" rowspan="1"

  614.       valign="top" align="left">

  615.           1.6.1

  616.       </td>

  617.                           <td colspan="1" rowspan="1"

  618.       valign="top" align="left">

  619.           12 February 2004

  620.       </td>

  621.       </tr>

  622.                   <tr>

  623.                       <td colspan="1" rowspan="1"

  624.       valign="top" align="left">

  625.           1.6.2

  626.       </td>

  627.                           <td colspan="1" rowspan="1"

  628.       valign="top" align="left">

  629.           16 July 2004

  630.       </td>

  631.       </tr>

  632.                   <tr>

  633.                       <td colspan="1" rowspan="1"

  634.       valign="top" align="left">

  635.           1.6.3

  636.       </td>

  637.                           <td colspan="1" rowspan="1"

  638.       valign="top" align="left">

  639.           28 April 2005

  640.       </td>

  641.       </tr>

  642.                   <tr>

  643.                       <td colspan="1" rowspan="1"

  644.       valign="top" align="left">

  645.           1.6.4

  646.       </td>

  647.                           <td colspan="1" rowspan="1"

  648.       valign="top" align="left">

  649.           19 May 2005

  650.       </td>

  651.       </tr>

  652.                   <tr>

  653.                       <td colspan="1" rowspan="1"

  654.       valign="top" align="left">

  655.           1.6.5

  656.       </td>

  657.                           <td colspan="1" rowspan="1"

  658.       valign="top" align="left">

  659.           2 June 2005

  660.       </td>

  661.       </tr>

  662.           </table>

  663.                                 <p class="faq">

  664.       <a name="no-gnu-tar"></a>

  665.       I get checksum errors when I try to extract the

  666.       <code>tar.gz</code> distribution file. Why?

  667.     </p>

  668.                   <p>Ant's distribution contains file names that are longer

  669.         than 100 characters, which is not supported by the standard

  670.         tar file format. Several different implementations of tar use

  671.         different and incompatible ways to work around this

  672.         restriction.</p>

  673.                         <p>Ant's &lt;tar&gt; task can create tar archives that use

  674.         the GNU tar extension, and this has been used when putting

  675.         together the distribution. If you are using a different

  676.         version of tar (for example, the one shipping with Solaris),

  677.         you cannot use it to extract the archive.</p>

  678.                         <p>The solution is to either install GNU tar, which can be

  679.         found <a href="http://www.gnu.org/software/tar/tar.html">here</a>,

  680.         or use the zip archive instead (you can extract it using

  681.         <code>jar xf</code>).</p>

  682.                     <p class="faq">

  683.       <a name="RedHat_ES_3"></a>

  684.       How do you get ant-1.6.x (or any version later than

  685.       1.5.2) to work on on RedHat ES 3?

  686.     </p>

  687.                   <p>Redhat ES 3.0 comes installed with ant 1.5.2. Even if you

  688.         have your PATH and ANT_HOME variables set correctly to a later

  689.         version of ant, you will always be forced to use the

  690.         preinstalled version.</p>

  691.                         <p>To use a later version of ant on this OS you could do the

  692.         following:</p>

  693.                         <pre class="code">

  694. $ ant -version

  695. Apache Ant version 1.5.2-23 compiled on November 12 2003

  696. $ su -

  697. # rpm -e ant ant-libs

  698. # exit

  699. $ hash -r

  700. $ ant -version

  701. Apache Ant version 1.6.2 compiled on July 16 2004

  702. </pre>

  703.                                 <p class="faq">

  704.       <a name="implement-os-specific-configuration"></a>

  705.       How do I realize os--specific configurations?

  706.     </p>

  707.                   <p>The core idea is using property files which name accords to the

  708.         os-name. Then simply use the build-in property <tt>os.name</tt>.</p>

  709.                         <p>For better use you should also provide a file with defaul values.

  710.         But be careful with the correct os-names. For test simply &lt;echo&gt;

  711.         the ${os.name} on all machines and you can be sure to use the right

  712.         file names.</p>

  713.                         <pre class="code">

  714.           &lt;property file=&quot;${os.name}.properties&quot;/&gt;

  715.           &lt;property file=&quot;default.properties&quot;/&gt;

  716. </pre>

  717.                     <p class="faq">

  718.       <a name="adding-external-tasks"></a>

  719.       How do I add an external task that I've written to the

  720.       page "External Tools and Tasks"?

  721.     </p>

  722.                   <p>Join and post a message to the dev or user mailing

  723.         list (one list is enough), including the following

  724.         information:</p>

  725.                         <ul>

  726.           <li>the name of the task/tool</li>

  727.           <li>a short description of the task/tool</li>

  728.           <li>a Compatibility: entry stating with which version(s) of

  729.           Ant the tool/task is compatible to</li>

  730.           <li>a URL: entry linking to the main page of the tool/task</li>

  731.           <li>a Contact: entry containing the email address or the URL

  732.           of a webpage for the person or list to contact for issues

  733.           related to the tool/task.  <strong>Note that we'll add a

  734.           link on the page, so any email address added there is not

  735.           obfuscated and can (and probably will) be abused by robots

  736.           harvesting websites for addresses to spam.</strong></li>

  737.           <li>a License: entry containing the type of license for the

  738.           tool/task</li>

  739.         </ul>

  740.                         <p>The preferred format for this information is a patch to <a href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/external.xml">this</a>

  741.         document.</p>

  742.                         <p>If you have written something bigger than a 'simple plugin' to Ant it

  743.         may be better to add the link to <a href="projects.html">projects.html</a>.

  744.         The procedure to add it is the same. The file to patch is <a href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/projects.xml">this</a>

  745.         document. The syntax of that file is the same.</p>

  746.                     <p class="faq">

  747.       <a name="create-extensions"></a>

  748.       How do I create new tasks?

  749.     </p>

  750.                   <p>Apart from a lot of information on using Ant, the 

  751.         <a href="manual/index.html">Manual</a> also contains information 

  752.         on how to extend Ant with new tasks. This information 

  753.         can be found under "Developing with Ant".</p>

  754.                         <p>Chances are that someone else already created the task you

  755.         want to create, it may be wise to see 

  756.         <a href="external.html">External Tools and Tasks</a> and

  757.         <a href="projects.html">Related Projects</a> first.</p>

  758.                     <p class="faq">

  759.       <a name="passing-cli-args"></a>

  760.       How do I pass parameters from the command line to my

  761.         build file?

  762.     </p>

  763.                   <p>Use properties. Using <code>ant

  764.         -D<em>name</em>=<em>value</em></code> lets you define values for

  765.         properties on the Ant command line. These properties can then be

  766.         used within your build file as

  767.         any normal property: <code>${<em>name</em>}</code> will put in

  768.         <code><em>value</em></code>.</p>

  769.                     <p class="faq">

  770.       <a name="jikes-switches"></a>

  771.       How can I use Jikes-specific command-line

  772.         switches?

  773.     </p>

  774.                   <p>A couple of switches are supported via "magic"

  775.           properties:</p>

  776.                               <table class="ForrestTable" cellspacing="1" cellpadding="4">

  777.               <tr>

  778.                       <th colspan="1" rowspan="1"

  779.       valign="top" align="left">

  780.           switch

  781.       </th>

  782.                           <th colspan="1" rowspan="1"

  783.       valign="top" align="left">

  784.           property

  785.       </th>

  786.                           <th colspan="1" rowspan="1"

  787.       valign="top" align="left">

  788.           default

  789.       </th>

  790.       </tr>

  791.                   <tr>

  792.                       <td colspan="1" rowspan="1"

  793.       valign="top" align="left">

  794.           +E

  795.       </td>

  796.                           <td colspan="1" rowspan="1"

  797.       valign="top" align="left">

  798.           build.compiler.emacs

  799.       </td>

  800.                           <td colspan="1" rowspan="1"

  801.       valign="top" align="left">

  802.           false == not set

  803.       </td>

  804.       </tr>

  805.                   <tr>

  806.                       <td colspan="1" rowspan="1"

  807.       valign="top" align="left">

  808.           +P

  809.       </td>

  810.                           <td colspan="1" rowspan="1"

  811.       valign="top" align="left">

  812.           build.compiler.pedantic

  813.       </td>

  814.                           <td colspan="1" rowspan="1"

  815.       valign="top" align="left">

  816.           false == not set

  817.       </td>

  818.       </tr>

  819.                   <tr>

  820.                       <td colspan="1" rowspan="1"

  821.       valign="top" align="left">

  822.           +F

  823.       </td>

  824.                           <td colspan="1" rowspan="1"

  825.       valign="top" align="left">

  826.           build.compiler.fulldepend

  827.       </td>

  828.                           <td colspan="1" rowspan="1"

  829.       valign="top" align="left">

  830.           false == not set

  831.       </td>

  832.       </tr>

  833.                   <tr>

  834.                       <td colspan="1" rowspan="1"

  835.       valign="top" align="left">

  836.           <strong>(Only for Ant &lt; 1.4; replaced by the

  837.                 <code><strong>nowarn</strong></code>

  838.                 attribute of the <code><strong>&lt;javac&gt;</strong></code>

  839.                 task after that.)</strong><br />-nowarn

  840.       </td>

  841.                           <td colspan="1" rowspan="1"

  842.       valign="top" align="left">

  843.           build.compiler.warnings

  844.       </td>

  845.                           <td colspan="1" rowspan="1"

  846.       valign="top" align="left">

  847.           true == not set

  848.       </td>

  849.       </tr>

  850.           </table>

  851.                         <p>With Ant &gt;= 1.5, you can also use nested

  852.           <code>&lt;compilerarg&gt;</code> elements with the

  853.           <code>&lt;javac&gt;</code> task.</p>

  854.                     <p class="faq">

  855.       <a name="shell-redirect-1"></a>

  856.       How do I include a &lt; character in my command-line arguments?

  857.     </p>

  858.                   <p>The short answer is "Use: <code>&amp;lt;</code>".</p>

  859.                         <p>The long answer is that this probably won't do what you

  860.         want anyway (see <a href="#shell-redirect-2">the next

  861.         section</a>).</p>

  862.                     <p class="faq">

  863.       <a name="shell-redirect-2"></a>

  864.       How do I redirect standard input or standard output

  865.         in the <code>&lt;exec&gt;</code> task?

  866.     </p>

  867.                   <p>Say you want to redirect the standard output stream of the

  868.         <code>m4</code> command to write to a file, something

  869.         like:</p>

  870.                         <pre class="code">

  871. shell-prompt&gt; m4 foo.m4 &gt; foo

  872. </pre>

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

  874.                         <pre class="code">

  875. &lt;exec executable=&quot;m4&quot;&gt;

  876.   &lt;arg value=&quot;foo.m4&quot;/&gt;

  877.   &lt;arg value=&quot;&amp;gt;&quot;/&gt;

  878.   &lt;arg value=&quot;foo&quot;/&gt;

  879. &lt;/exec&gt;

  880. </pre>

  881.                         <p>This will not do what you expect.  The output redirection is

  882.         performed by your shell, not the command itself, so this

  883.         should read:</p>

  884.                         <pre class="code">

  885. &lt;exec executable=&quot;/bin/sh&quot;&gt;

  886.   &lt;arg value=&quot;-c&quot; /&gt;

  887.   &lt;arg value=&quot;m4 foo.m4 &amp;gt; foo&quot; /&gt;

  888. &lt;/exec&gt;

  889. </pre>

  890.                         <p>Note that you must use the <code>value</code> attribute of

  891.         <code>&lt;arg&gt;</code> in the last element, in order to have

  892.         the command passed as a single, quoted argument. Alternatively,

  893.         you can use:</p>

  894.                         <pre class="code">

  895. &lt;exec executable=&quot;/bin/sh&quot;&gt;

  896.   &lt;arg line='-c &quot;m4 foo.m4 &amp;gt; foo&quot;'/&gt;

  897. &lt;/exec&gt;

  898. </pre>

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

  900.                     <p class="faq">

  901.       <a name="batch-shell-execute"></a>

  902.       How do I execute a batch file or shell script from Ant?

  903.     </p>

  904.                   <p>On native Unix systems, you should be able to run shell scripts

  905.            directly. On systems running a Unix-type shell (for example, Cygwin

  906.            on Windows) execute the (command) shell instead - <code>cmd</code>

  907.            for batch files, <code>sh</code> for shell scripts - then pass the

  908.            batch file or shell script (plus any arguments to the script)

  909.            as a single command, using the <code>/c</code> or

  910.            <code>-c</code> switch, respectively. See

  911.            <a href="#shell-redirect-2">the above section</a>

  912.            for example <code>&lt;exec&gt;</code> tasks

  913.            executing <code>sh</code>. For batch files, use something like:</p>

  914.                         <pre class="code">

  915. &lt;exec dir=&quot;.&quot; executable=&quot;cmd&quot; os=&quot;Windows NT&quot;&gt;

  916.   &lt;arg line=&quot;/c test.bat&quot;/&gt;

  917. &lt;/exec&gt;

  918. </pre>

  919.                     <p class="faq">

  920.       <a name="multi-conditions"></a>

  921.       I want to execute a particular target only if

  922.         multiple conditions are true.

  923.     </p>

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

  925.                         <p>If you have only one set and one unset property to test,

  926.         you can specify both an <code>if</code> and an <code>unless</code>

  927.         attribute for the target, and they will act as if they

  928.         are "anded" together.</p>

  929.                         <p>If you are using a version of Ant 1.3 or earlier, the

  930.         way to work with all other cases is to chain targets together

  931.         to determine the specific state you want to test for.</p>

  932.                         <p>To see how this works, assume you have three properties:

  933.         <code>prop1</code>, <code>prop2</code>, and <code>prop3</code>.

  934.         You want to test that <code>prop1</code> and <code>prop2</code>

  935.         are set, and that <code>prop3</code> is not. If the condition

  936.         holds true you want to echo "yes".</p>

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

  938.                         <pre class="code">

  939. &lt;target name=&quot;cond&quot; depends=&quot;cond-if&quot;/&gt;

  940. 

  941. &lt;target name=&quot;cond-if&quot; if=&quot;prop1&quot;&gt;

  942.   &lt;antcall target=&quot;cond-if-2&quot;/&gt;

  943. &lt;/target&gt;

  944. 

  945. &lt;target name=&quot;cond-if-2&quot; if=&quot;prop2&quot;&gt;

  946.   &lt;antcall target=&quot;cond-if-3&quot;/&gt;

  947. &lt;/target&gt;

  948. 

  949. &lt;target name=&quot;cond-if-3&quot; unless=&quot;prop3&quot;&gt;

  950.   &lt;echo message=&quot;yes&quot;/&gt;

  951. &lt;/target&gt;

  952. </pre>

  953.                         <p>Note: <code>&lt;antcall&gt;</code> tasks do <em>not</em> pass

  954.         property changes back up to the environment they were called

  955.         from, so you wouldn't be able to, for example, set a

  956.         <code>result</code> property in the <code>cond-if-3</code> target,

  957.         then do

  958.         <code>&lt;echo message="result is ${result}"/&gt;</code>

  959.         in the <code>cond</code> target.</p>

  960.                         <p>Starting with Ant 1.4, you can use the

  961.         <code>&lt;condition&gt;</code> task.</p>

  962.                         <pre class="code">

  963. &lt;target name=&quot;cond&quot; depends=&quot;cond-if,cond-else&quot;/&gt;

  964. 

  965. &lt;target name=&quot;check-cond&quot;&gt;

  966.   &lt;condition property=&quot;cond-is-true&quot;&gt;

  967.     &lt;and&gt;

  968.       &lt;not&gt;

  969.         &lt;equals arg1=&quot;${prop1}&quot; arg2=&quot;$${prop1}&quot; /&gt;

  970.       &lt;/not&gt;

  971.       &lt;not&gt;

  972.         &lt;equals arg1=&quot;${prop2}&quot; arg2=&quot;$${prop2}&quot; /&gt;

  973.       &lt;/not&gt;

  974.       &lt;equals arg1=&quot;${prop3}&quot; arg2=&quot;$${prop3}&quot; /&gt;

  975.     &lt;/and&gt;

  976.   &lt;/condition&gt;

  977. &lt;/target&gt;

  978. 

  979. &lt;target name=&quot;cond-if&quot; depends=&quot;check-cond&quot; if=&quot;cond-is-true&quot;&gt;

  980.   &lt;echo message=&quot;yes&quot;/&gt;

  981. &lt;/target&gt;

  982. 

  983. &lt;target name=&quot;cond-else&quot; depends=&quot;check-cond&quot; unless=&quot;cond-is-true&quot;&gt;

  984.   &lt;echo message=&quot;no&quot;/&gt;

  985. &lt;/target&gt;

  986. </pre>

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

  988.                         <ul>

  989.           <li>If a property <code>a</code> has not been set,

  990.           <code>${a}</code> will evaluate to <code>${a}</code>.</li>

  991. 

  992.           <li>To get a literal <code>$</code> in Ant, you have to

  993.           escape it with another <code>$</code> - this will also break

  994.           the special treatment of the <code>${</code> sequence.</li>

  995.         </ul>

  996.                         <p>Because testing for a literal <code>${property}</code> string

  997.         isn't all that readable or easy to understand,

  998.         post-1.4.1 Ant introduces the <code>&lt;isset&gt;</code> element

  999.         to the <code>&lt;condition&gt;</code> task.</p>

  1000.                         <p>Here is the previous example done using

  1001.         <code>&lt;isset&gt;</code>:</p>

  1002.                         <pre class="code">

  1003. &lt;target name=&quot;check-cond&quot;&gt;

  1004.   &lt;condition property=&quot;cond-is-true&quot;&gt;

  1005.     &lt;and&gt;

  1006.       &lt;isset property=&quot;prop1&quot;/&gt;

  1007.       &lt;isset property=&quot;prop2&quot;/&gt;

  1008.       &lt;not&gt;

  1009.         &lt;isset property=&quot;prop3&quot;/&gt;

  1010.       &lt;/not&gt;

  1011.     &lt;/and&gt;

  1012.   &lt;/condition&gt;

  1013. &lt;/target&gt;

  1014. </pre>

  1015.                         <p>The last option is to use a scripting language to set the

  1016.         properties. This can be particularly handy when you need much

  1017.         finer control than the simple conditions shown here but, of

  1018.         course, comes with the overhead of adding JAR files to support

  1019.         the language, to say nothing of the added maintenance in requiring

  1020.         two languages to implement a single system. See the

  1021.         <a href="manual/OptionalTasks/script.html">

  1022.         <code>&lt;script&gt;</code> task documentation</a> for more

  1023.         details.</p>

  1024.                     <p class="faq">

  1025.       <a name="encoding"></a>

  1026.       How can I include national characters like German

  1027.         umlauts in my build file?

  1028.     </p>

  1029.                   <p>You need to tell the XML parser which character encoding

  1030.         your build file uses, this is done inside the <a href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-prolog-dtd">XML

  1031.         declaration</a>.</p>

  1032.                         <p>By default the parser assumes you are using the UTF-8

  1033.         encoding instead of your platform's default.  For most Western

  1034.         European countries you should set the encoding to

  1035.         <code>ISO-8859-1</code>.  To do so, make the very first line

  1036.         of you build file read like</p>

  1037.                         <pre class="code">

  1038. &lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot; ?&gt;

  1039. </pre>

  1040.                     <p class="faq">

  1041.       <a name="use-zip-instead-of-jar"></a>

  1042.       How do I use <code>jar</code>'s <code>M</code> switch?

  1043.       I don't want a MANIFEST.

  1044.     </p>

  1045.                   <p>A JAR archive is a ZIP file, so if you don't want a

  1046.         MANIFEST you can simply use <code>&lt;zip&gt;</code>.</p>

  1047.                         <p>If your file names contain national characters you should

  1048.         know that Sun's <code>jar</code> utility like Ant's

  1049.         <code>&lt;jar&gt;</code> uses UTF-8 to encode their names while

  1050.         <code>&lt;zip&gt;</code> uses your platforms default encoding.

  1051.         Use the encoding attribute of <code>&lt;zip&gt;</code> if

  1052.         necessary.</p>

  1053.                     <p class="faq">

  1054.       <a name="propertyvalue-as-name-for-property"></a>

  1055.       How can I do something like <code>&lt;property name="prop"

  1056.       value="${${anotherprop}}"/&gt;</code> (double expanding the property)?

  1057.     </p>

  1058.                   <p>Without any external help you can not.</p>

  1059.                         <p>With &lt;script/&gt;, which needs external libraries, you can do</p>

  1060.                         <pre class="code">

  1061. &lt;script language=&quot;javascript&quot;&gt;

  1062.     propname = project.getProperty(&quot;anotherprop&quot;);

  1063.     project.setNewProperty(&quot;prop&quot;, propname);

  1064. &lt;/script&gt;

  1065. </pre>

  1066.                         <p>With AntContrib (external task library) you can do <code>

  1067.          &lt;propertycopy name="prop" from="${anotherprop}"/&gt;</code>.</p>

  1068.                         <p>With Ant 1.6 you can simulate the AntContribs &lt;propertycopy&gt;

  1069.          and avoid the need of an external library:</p>

  1070.                         <pre class="code">

  1071. &lt;macrodef name=&quot;propertycopy&quot;&gt;

  1072.   &lt;attribute name=&quot;name&quot;/&gt;

  1073.   &lt;attribute name=&quot;from&quot;/&gt;

  1074.   &lt;sequential&gt;

  1075.     &lt;property name=&quot;@{name}&quot; value=&quot;${@{from}}&quot;/&gt;

  1076.   &lt;/sequential&gt;

  1077. &lt;/macrodef&gt;

  1078. </pre>

  1079.                                 <p class="faq">

  1080.       <a name="genral-advice"></a>

  1081.       General Advice

  1082.     </p>

  1083.                   <p>There are many reasons why Ant doesn't behave as

  1084.         expected, not all of them are due to Ant bugs.  See our <a href="problems.html">Having Problems?</a> page for hints that

  1085.         may help pinning down the reasons for your problem.</p>

  1086.                     <p class="faq">

  1087.       <a name="always-recompiles"></a>

  1088.       Why does Ant always recompile all my Java files?

  1089.     </p>

  1090.                   <p>In order to find out which files should be compiled, Ant

  1091.         compares the timestamps of the source files to those of the

  1092.         resulting <code>.class</code> files.  Opening all source files

  1093.         to find out which package they belong to would be very

  1094.         inefficient. Instead, Ant expects you to place your

  1095.         source files in a directory hierarchy that mirrors your

  1096.         package hierarchy and to point Ant to the root of this

  1097.         directory tree with the <code>srcdir</code> attribute.</p>

  1098.                         <p>Say you have <code>&lt;javac srcdir="src"

  1099.         destdir="dest"/&gt;</code>.  If Ant finds a file

  1100.         <code>src/a/b/C.java</code>, it expects it to be in package

  1101.         <code>a.b</code> so that the resulting <code>.class</code>

  1102.         file is going to be <code>dest/a/b/C.class</code>.</p>

  1103.                         <p>If your source-tree directory structure does not match your

  1104.         package structure, Ant's heuristic won't work, and

  1105.         it will recompile classes that are up-to-date.  Ant is not the

  1106.         only tool that expects a source-tree layout like this.</p>

  1107.                         <p>If you have Java source files that aren't declared to

  1108.         be part of any package, you can still use the <code>&lt;javac&gt;</code>

  1109.         task to compile these files correctly - just set the

  1110.         <code>srcdir</code> and <code>destdir</code> attributes to

  1111.         the actual directory the source

  1112.         files live in and the directory the class files should go into,

  1113.         respectively.</p>

  1114.                     <p class="faq">

  1115.       <a name="defaultexcludes"></a>

  1116.       I've used a <code>&lt;delete&gt;</code> task to

  1117.       delete unwanted SourceSafe control files (CVS files, editor

  1118.       backup files, etc.), but it doesn't seem to work; the files

  1119.       never get deleted. What's wrong?

  1120.     </p>

  1121.                   <p>This is probably happening because, by default, Ant excludes

  1122.         SourceSafe control files (<code>vssver.scc</code>) and certain other

  1123.         files from FileSets.</p>

  1124.                         <p>Here's what you probably did:</p>

  1125.                         <pre class="code">

  1126. &lt;delete&gt;

  1127.   &lt;fileset dir=&quot;${build.src}&quot; includes=&quot;**/vssver.scc&quot;/&gt;

  1128. &lt;/delete&gt;

  1129. </pre>

  1130.                         <p>You need to switch off the default exclusions,

  1131.            and it will work:</p>

  1132.                         <pre class="code">

  1133. &lt;delete&gt;

  1134.   &lt;fileset dir=&quot;${build.src}&quot; includes=&quot;**/vssver.scc&quot;

  1135.            defaultexcludes=&quot;no&quot;/&gt;

  1136. &lt;/delete&gt;

  1137. </pre>

  1138.                         <p>For a complete listing of the patterns that are excluded

  1139.         by default, see <a href="manual/dirtasks.html#defaultexcludes">the user

  1140.         manual</a>.</p>

  1141.                     <p class="faq">

  1142.       <a name="stop-dependency"></a>

  1143.       I have a target I want to skip if a property is set,

  1144.       so I have <code>unless="property"</code> as an attribute

  1145.       of the target, but all the targets this target

  1146.       depends on are still executed. Why?

  1147.     </p>

  1148.                   <p>The list of dependencies is generated by Ant before any of the

  1149.         targets are run. This allows dependent targets, such as an

  1150.         <code>init</code> target, to set properties that can control the

  1151.                execution of the targets higher in the dependency graph. This

  1152.               is a good thing.</p>

  1153.                         <p>However, when your dependencies break down the

  1154.         higher-level task

  1155.         into several smaller steps, this behaviour becomes

  1156.         counter-intuitive. There are a couple of solutions available:

  1157.         </p>

  1158.                         <ol>

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

  1160. 

  1161.           <li>Execute the steps using <code>&lt;antcall&gt;</code>,

  1162.           instead of specifying them inside the <code>depends</code>

  1163.           attribute.</li>

  1164.         </ol>

  1165.                     <p class="faq">

  1166.       <a name="include-order"></a>

  1167.       In my <code>&lt;fileset&gt;</code>, I've put in an

  1168.       <code>&lt;exclude&gt;</code> of all files followed by an

  1169.       <code>&lt;include&gt;</code> of just the files I want, but it

  1170.       isn't giving me any files at all. What's wrong?

  1171.       

  1172.     </p>

  1173.                   <p>The order of the <code>&lt;include&gt;</code> and

  1174.         <code>&lt;exclude&gt;</code> tags within a <code>&lt;fileset&gt;</code>

  1175.         is ignored when the FileSet is created. Instead, all of the

  1176.         <code>&lt;include&gt;</code> elements are processed together,

  1177.         followed by all of the <code>&lt;exclude&gt;</code>

  1178.         elements. This means that the <code>&lt;exclude&gt;</code>

  1179.         elements only apply to the file list produced by the

  1180.         <code>&lt;include&gt;</code> elements.</p>

  1181.                         <p>To get the files you want, focus on just the

  1182.         <code>&lt;include&gt;</code> patterns that would be necessary

  1183.         to get them. If you find you need to trim the list that the

  1184.         <code>&lt;include&gt;</code> elements produce, then use

  1185.         <code>&lt;exclude&gt;</code> elements.</p>

  1186.                     <p class="faq">

  1187.       <a name="properties-not-trimmed"></a>

  1188.       <code>ant</code> failed to build my program via javac

  1189.       even when I put the needed jars in an external

  1190.       <code>build.properties</code> file and reference them by

  1191.       <code>pathelement</code> or <code>classpath refid</code>.

  1192.     </p>

  1193.                   <p>When <code>ant</code> loads properties from an external

  1194.         file it doesn't touch the value of properties, trailing blanks

  1195.         will not be trimmed for example.</p>

  1196.                         <p>If the value represents a file path, like a jar needed to

  1197.         compile, the task which requires the value, javac for example

  1198.         would fail to compile since it can't find the file due to

  1199.         trailing spaces.</p>

  1200.                     <p class="faq">

  1201.       <a name="winzip-lies"></a>

  1202.       Ant creates WAR files with a lower-case

  1203.         <code>web-inf</code> or JAR files with a lower-case

  1204.         <code>meta-inf</code> directory.

  1205.     </p>

  1206.                   <p>No it doesn't.</p>

  1207.                         <p>You may have seen these lower-case directory names in

  1208.         WinZIP, but WinZIP is trying to be helpful (and fails).  If

  1209.         WinZIP encounters a filename that is all upper-case, it

  1210.         assumes it has come from an old DOS box and changes the case to

  1211.         all lower-case for you.</p>

  1212.                         <p>If you extract (or just check) the archive with jar, you

  1213.         will see that the names have the correct case.</p>

  1214.                         <p>With WinZIP (version 8.1 at least), this can be corrected in the

  1215.         configuration.  In the Options/Configuration menu, in the View tab, General

  1216.         section, check the "Allow all upper case files names" box.  The META-INF and

  1217.         WEB-INF will look correct.</p>

  1218.                     <p class="faq">

  1219.       <a name="NoClassDefFoundError"></a>

  1220.       I installed Ant 1.6.x and now get

  1221.         <code>Exception in thread "main" java.lang.NoClassDefFoundError:

  1222.         </code>

  1223.       

  1224.     </p>

  1225.                   <p>

  1226.           The cause of this is that there is an old version of ant somewhere in the

  1227.           class path or configuration.

  1228.         </p>

  1229.                         <p>

  1230.           A version of this problem happens with jars that are in the classpath

  1231.           that include an embedded copy of ant classes.

  1232.           An example of this is some copies of weblogic.jar.

  1233.         </p>

  1234.                         <p>

  1235.         One can check if this is the case by doing (on unix/sh):

  1236.         <code><pre>

  1237.         unset CLASSPATH

  1238.         ant -version

  1239.         </pre>

  1240.         </code>

  1241.         </p>

  1242.                     <p class="faq">

  1243.       <a name="InstantiationException"></a>

  1244.       I installed Ant 1.6.x and now get

  1245.         <code>java.lang.InstantiationException: org.apache.tools.ant.Main</code>

  1246.       

  1247.     </p>

  1248.                   <p>

  1249.           The cause of this is that there is an old version of ant somewhere in the

  1250.           class path or configuration.

  1251.         </p>

  1252.                         <p>

  1253.           A version of this problem may be seen on some linux systems.

  1254.           Some linux systems (Fedora Core 2 for example), comes with a version

  1255.           of ant pre-installed. There is a configuration file called

  1256.           <code>/etc/ant.conf</code> which if present, the ant shell

  1257.           script will 'dot' include. On Fedora Core 2, the /etc/ant.conf

  1258.           file resets the <code>ANT_HOME</code> environment variable to

  1259.           <code>/usr/share/ant</code>. This causes the problem that

  1260.           an old version of ant (1.5.x in this cause) will be used

  1261.           with a new version of the ant script file.

  1262.         </p>

  1263.                         <p>

  1264.           One can check if this is the case by doing

  1265.           <code>ant --noconfig -version</code>.

  1266.         </p>

  1267.                     <p class="faq">

  1268.       <a name="mangled-manifest"></a>

  1269.       

  1270.         Whenever I use the Ant jar or manifest related tasks, long lines in

  1271.         my manifest are wrapped at 70 characters and the resulting jar does 

  1272.         not work in my application server. Why does Ant do this?

  1273.       

  1274.     </p>

  1275.                   <p>

  1276.           Ant implements the Java 

  1277.           <a href="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html">Jar 

  1278.           file specification</a>. Please refer to the notes section where it 

  1279.           discusses the maximum allowable length of a line and the concept of

  1280.           continuation characters.

  1281.         </p>

  1282.                         <p>

  1283.           If a jar file produced by Ant does not work in your appserver, and 

  1284.           that failure is due to the wrapped manifest, then you need

  1285.           to consult your appserver provider, as it is a bug in their 

  1286.           appserver. Far more likely, however, is a problem in your 

  1287.           specification of your classpath. It is not Ant's wrapping of your

  1288.           classpath that is the problem.

  1289.         </p>

  1290.                         <p>

  1291.           Do not raise a bug about this issue until you have checked to ensure 

  1292.           that the problem is not due to your classpath specification.  

  1293.         </p>

  1294.                                 <p class="faq">

  1295.       <a name="integration"></a>

  1296.       Is Ant supported by my IDE/Editor?

  1297.     </p>

  1298.                   <p>See the <a href="external.html#IDE and Editor Integration">section

  1299.         on IDE integration</a> on our External Tools and Tasks page.</p>

  1300.                     <p class="faq">

  1301.       <a name="emacs-mode"></a>

  1302.       Why doesn't (X)Emacs/vi/MacOS X's project builder

  1303.       correctly parse the error messages generated by Ant?

  1304.     </p>

  1305.                   <p>Ant adds a "banner" with the name of the current

  1306.         task in front of all logging messages - and there are no built-in

  1307.         regular expressions in your editor that would account for

  1308.         this.</p>

  1309.                         <p>You can disable this banner by invoking Ant with the

  1310.         <code>-emacs</code> switch.  To make Ant autodetect

  1311.         Emacs' compile mode, put this into your

  1312.         <code>.antrc</code> (contributed by Ville Skyttä).</p>

  1313.                         <pre class="code">

  1314. # Detect (X)Emacs compile mode

  1315. if [ &quot;$EMACS&quot; = &quot;t&quot; ] ; then

  1316.   ANT_ARGS=&quot;$ANT_ARGS -emacs&quot;

  1317.   ANT_OPTS=&quot;$ANT_OPTS -Dbuild.compiler.emacs=true&quot;

  1318. fi

  1319. </pre>

  1320.                         <p>Alternatively, you can add the following snippet to your

  1321.         <code>.emacs</code> to make Emacs understand Ant's

  1322.         output.</p>

  1323.                         <pre class="code">

  1324. (require 'compile)

  1325. (setq compilation-error-regexp-alist

  1326.   (append (list

  1327.      ;; works for jikes

  1328.      '(&quot;^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):\\([0-9]+\\):[0-9]+:[0-9]+:&quot; 1 2 3)

  1329.      ;; works for javac

  1330.      '(&quot;^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):&quot; 1 2))

  1331.   compilation-error-regexp-alist))

  1332. </pre>

  1333.                         <p>Yet another alternative that preserves most of Ant's

  1334.         formatting is to pipe Ant's output through the following Perl

  1335.         script by Dirk-Willem van Gulik:</p>

  1336.                         <pre class="code">

  1337. #!/usr/bin/perl

  1338. #

  1339. # May 2001 dirkx@apache.org - remove any

  1340. # [foo] lines from the output; keeping

  1341. # spacing more or less there.

  1342. #

  1343. $|=1;

  1344. while(&lt;STDIN&gt;) {

  1345.         if (s/^(\s+)\[(\w+)\]//) {

  1346.                 if ($2 ne $last) {

  1347.                         print &quot;$1\[$2\]&quot;;

  1348.                         $s = ' ' x length($2);

  1349.                 } else {

  1350.                         print &quot;$1 $s &quot;;

  1351.                 };

  1352.                 $last = $2;

  1353.         };

  1354.         print;

  1355. };

  1356. </pre>

  1357.                                 <p class="faq">

  1358.       <a name="dtd"></a>

  1359.       Is there a DTD that I can use to validate my build

  1360.       files?

  1361.     </p>

  1362.                   <p>An incomplete DTD can be created by the

  1363.           <code>&lt;antstructure&gt;</code> task - but this one

  1364.           has a few problems:</p>

  1365.                         <ul>

  1366.             <li>It doesn't know about required attributes.  Only

  1367.             manual tweaking of this file can help here.</li>

  1368. 

  1369.             <li>It is not complete - if you add new tasks via

  1370.             <code>&lt;taskdef&gt;</code> it won't know about it.  See

  1371.             <a href="http://www.sdv.fr/pages/casa/html/ant-dtd.en.html">this

  1372.             page</a> by Michel Casabianca for a solution to this

  1373.             problem.  Note that the DTD you can download at this page

  1374.             is based on Ant 0.3.1.</li>

  1375. 

  1376.             <li>It may even be an invalid DTD.  As Ant allows tasks

  1377.             writers to define arbitrary elements, name collisions will

  1378.             happen quite frequently - if your version of Ant contains

  1379.             the optional <code>&lt;test&gt;</code> and

  1380.             <code>&lt;junit&gt;</code> tasks, there are two XML

  1381.             elements named <code>test</code> (the task and the nested child

  1382.             element of <code>&lt;junit&gt;</code>) with different attribute

  1383.             lists.  This problem cannot be solved; DTDs don't give a

  1384.             syntax rich enough to support this.</li>

  1385.           </ul>

  1386.                     <p class="faq">

  1387.       <a name="xml-entity-include"></a>

  1388.       How do I include an XML snippet in my build file?

  1389.     </p>

  1390.                   <p>You can use XML's way of including external files and let

  1391.         the parser do the job for Ant:</p>

  1392.                         <pre class="code">

  1393. &lt;?xml version=&quot;1.0&quot;?&gt;

  1394. 

  1395. &lt;!DOCTYPE project [

  1396.     &lt;!ENTITY common SYSTEM &quot;file:./common.xml&quot;&gt;

  1397. ]&gt;

  1398. 

  1399. &lt;project name=&quot;test&quot; default=&quot;test&quot; basedir=&quot;.&quot;&gt;

  1400. 

  1401.   &lt;target name=&quot;setup&quot;&gt;

  1402.     ...

  1403.   &lt;/target&gt;

  1404. 

  1405.   &amp;common;

  1406. 

  1407.   ...

  1408. 

  1409. &lt;/project&gt;

  1410. </pre>

  1411.                         <p>will literally include the contents of <code>common.xml</code> where

  1412.         you've placed the <code>&amp;common;</code> entity.</p>

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

  1414.                         <pre class="code">

  1415. &lt;!DOCTYPE project PUBLIC &quot;-//ANT//DTD project//EN&quot; &quot;file:./ant.dtd&quot; [

  1416.    &lt;!ENTITY include SYSTEM &quot;file:./header.xml&quot;&gt;

  1417. ]&gt;

  1418. </pre>

  1419.                         <p>Starting with Ant 1.6, there is a new

  1420.         <code>&lt;import&gt;</code> task that can (also) be used to

  1421.         include build file fragments.  Unlike the snippets used with

  1422.         entity includes, the referenced files have to be complete Ant

  1423.         build files, though.</p>

  1424.                         <p>The example above would become:</p>

  1425.                         <pre class="code">

  1426. &lt;?xml version=&quot;1.0&quot;?&gt;

  1427. &lt;project name=&quot;test&quot; default=&quot;test&quot; basedir=&quot;.&quot;&gt;

  1428. 

  1429.   &lt;target name=&quot;setup&quot;&gt;

  1430.     ...

  1431.   &lt;/target&gt;

  1432. 

  1433.   &lt;import file=&quot;./common.xml&quot;/&gt;

  1434. 

  1435.   ...

  1436. 

  1437. &lt;/project&gt;

  1438. </pre>

  1439.                         <p>Unlike entity includes, <code>&lt;import&gt;</code> will

  1440.         let you use Ant properties in the file name.</p>

  1441.                     <p class="faq">

  1442.       <a name="mail-logger"></a>

  1443.       How do I send an email with the result of my build

  1444.         process?

  1445.     </p>

  1446.                   <p>If you are using a nightly build of Ant 1.5 after

  1447.         2001-12-14, you can use the built-in MailLogger:</p>

  1448.                         <pre class="code">

  1449.          ant -logger org.apache.tools.ant.listener.MailLogger

  1450. </pre>

  1451.                         <p>See the <a href="http://cvs.apache.org/viewcvs/~checkout~/ant/docs/manual/listeners.html?content-type=text/html">Listeners

  1452.         &amp; Loggers</a> documentation for details on the properties

  1453.         required.</p>

  1454.                         <p>For older versions of Ant, you can use a custom

  1455.         BuildListener that sends out an email

  1456.         in the buildFinished() method.  Will Glozer

  1457.         &lt;will.glozer@jda.com&gt; has written such a listener based

  1458.         on <a href="http://java.sun.com/products/javamail/">JavaMail</a>.

  1459.         The source is:</p>

  1460.                         <pre class="code">

  1461. import java.io.*;

  1462. import java.util.*;

  1463. import javax.mail.*;

  1464. import javax.mail.internet.*;

  1465. import org.apache.tools.ant.*;

  1466. 

  1467. /**

  1468.  * A simple listener that waits for a build to finish and sends an email

  1469.  * of the results.  The settings are stored in &quot;monitor.properties&quot; and

  1470.  * are fairly self explanatory.

  1471.  *

  1472.  * @author      Will Glozer

  1473.  * @version     1.05a 09/06/2000

  1474.  */

  1475. public class BuildMonitor implements BuildListener {

  1476.     protected Properties props;

  1477. 

  1478.     /**

  1479.      * Create a new BuildMonitor.

  1480.      */

  1481.     public BuildMonitor() throws Exception {

  1482.         props = new Properties();

  1483.         InputStream is = getClass().getResourceAsStream(&quot;monitor.properties&quot;);

  1484.         props.load(is);

  1485.         is.close();

  1486.     }

  1487. 

  1488.     public void buildStarted(BuildEvent e) {

  1489.     }

  1490. 

  1491.     /**

  1492.      * Determine the status of the build and the actions to follow, now that

  1493.      * the build has completed.

  1494.      *

  1495.      * @param       e       Event describing the build status.

  1496.      */

  1497.     public void buildFinished(BuildEvent e) {

  1498.         Throwable th = e.getException();

  1499.         String status = (th != null) ? &quot;failed&quot; : &quot;succeeded&quot;;

  1500. 

  1501.         try {

  1502.             String key = &quot;build.&quot; + status;

  1503.             if (props.getProperty(key + &quot;.notify&quot;).equalsIgnoreCase(&quot;false&quot;)) {

  1504.                     return;

  1505.             }

  1506. 

  1507.             Session session = Session.getDefaultInstance(props, null);

  1508. 

  1509.             MimeMessage message = new MimeMessage(session);

  1510.             message.addRecipients(Message.RecipientType.TO, parseAddresses(

  1511.                 props.getProperty(key + &quot;.email.to&quot;)));

  1512.             message.setSubject(props.getProperty(key + &quot;.email.subject&quot;));

  1513. 

  1514.             BufferedReader br = new BufferedReader(new FileReader(

  1515.                 props.getProperty(&quot;build.log&quot;)));

  1516.             StringWriter sw = new StringWriter();

  1517. 

  1518.             String line = br.readLine();

  1519.             while (line != null) {

  1520.                 sw.write(line);

  1521.                 sw.write(&quot;\n&quot;);

  1522.                 line = br.readLine();

  1523.             }

  1524.             br.close();

  1525. 

  1526.             message.setText(sw.toString(), &quot;UTF-8&quot;);

  1527.             sw.close();

  1528. 

  1529.             Transport transport = session.getTransport();

  1530.             transport.connect();

  1531.             transport.send(message);

  1532.             transport.close();

  1533.         } catch (Exception ex) {

  1534.             System.out.println(&quot;BuildMonitor failed to send email!&quot;);

  1535.             ex.printStackTrace();

  1536.         }

  1537.     }

  1538. 

  1539.     /**

  1540.      * Parse a comma separated list of internet email addresses.

  1541.      *

  1542.      * @param       s       The list of addresses.

  1543.      * @return      Array of Addresses.

  1544.      */

  1545.     protected Address[] parseAddresses(String s) throws Exception {

  1546.         StringTokenizer st = new StringTokenizer(s, &quot;,&quot;);

  1547.         Address[] addrs = new Address[st.countTokens()];

  1548. 

  1549.         for (int i = 0; i &lt; addrs.length; i++) {

  1550.             addrs[i] = new InternetAddress(st.nextToken());

  1551.         }

  1552.         return addrs;

  1553.     }

  1554. 

  1555.     public void messageLogged(BuildEvent e) {

  1556.     }

  1557. 

  1558.     public void targetStarted(BuildEvent e) {

  1559.     }

  1560. 

  1561.     public void targetFinished(BuildEvent e) {

  1562.     }

  1563. 

  1564.     public void taskStarted(BuildEvent e) {

  1565.     }

  1566. 

  1567.     public void taskFinished(BuildEvent e) {

  1568.     }

  1569. }

  1570. </pre>

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

  1572.                         <pre class="code">

  1573. # configuration for build monitor

  1574. 

  1575. mail.transport.protocol=smtp

  1576. mail.smtp.host=&lt;host&gt;

  1577. mail.from=Will Glozer &lt;will.glozer@jda.com&gt;

  1578. 

  1579. build.log=build.log

  1580. 

  1581. build.failed.notify=true

  1582. build.failed.email.to=will.glozer@jda.com

  1583. build.failed.email.subject=Nightly build failed!

  1584. 

  1585. build.succeeded.notify=true

  1586. build.succeeded.email.to=will.glozer@jda.com

  1587. build.succeeded.email.subject=Nightly build succeeded!

  1588. </pre>

  1589.                         <p><code>monitor.properties</code> should be placed right next

  1590.         to your compiled <code>BuildMonitor.class</code>.  To use it,

  1591.         invoke Ant like:</p>

  1592.                         <pre class="code">

  1593. ant -listener BuildMonitor -logfile build.log

  1594. </pre>

  1595.                         <p>Make sure that <code>mail.jar</code> from JavaMail and

  1596.         <code>activation.jar</code> from the

  1597.         <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">Java

  1598.         Beans Activation Framework</a> are in your <code>CLASSPATH</code>.</p>

  1599.                     <p class="faq">

  1600.       <a name="listener-properties"></a>

  1601.       How do I get at the properties that Ant was running

  1602.       with from inside BuildListener?

  1603.     </p>

  1604.                   <p>You can get at a hashtable with all the properties that Ant

  1605.         has been using through the BuildEvent parameter. For

  1606.         example:</p>

  1607.                         <pre class="code">

  1608. public void buildFinished(BuildEvent e) {

  1609.     Hashtable table = e.getProject().getProperties();

  1610.     String buildpath = (String)table.get(&quot;build.path&quot;);

  1611.     ...

  1612. }

  1613. </pre>

  1614.                         <p>This is more accurate than just reading the same property

  1615.         files that your project does, since it will give the correct

  1616.         results for properties that were specified on the Ant command line.</p>

  1617.                                 <p class="faq">

  1618.       <a name="remove-cr"></a>

  1619.       &lt;chmod&gt; or &lt;exec&gt; doesn't work in Ant

  1620.         1.3 on Unix

  1621.     </p>

  1622.                   <p>The <code>antRun</code> script in <code>ANT_HOME/bin</code>

  1623.         has DOS instead of Unix line endings; you must remove the

  1624.         carriage-return characters from this file.  This can be done by

  1625.         using Ant's <code>&lt;fixcrlf&gt;</code> task

  1626.         or something like:</p>

  1627.                         <pre class="code">

  1628. tr -d '\r' &lt; $ANT_HOME/bin/antRun &gt; /tmp/foo

  1629. mv /tmp/foo $ANT_HOME/bin/antRun

  1630. </pre>

  1631.                     <p class="faq">

  1632.       <a name="javadoc-cannot-execute"></a>

  1633.       JavaDoc failed: java.io.IOException: javadoc: cannot execute

  1634.     </p>

  1635.                   <p>There is a bug in the Solaris reference implementation of

  1636.         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>).

  1637.         This also appears to be true under Linux. Moving the JDK to

  1638.         the front of the PATH fixes the problem.</p>

  1639.                     <p class="faq">

  1640.       <a name="delegating-classloader"></a>

  1641.       &lt;style&gt; or &lt;junit&gt; ignores my

  1642.       &lt;classpath&gt;

  1643.     </p>

  1644.                   <p>These tasks don't ignore your classpath setting, you

  1645.         are facing a common problem with delegating classloaders.</p>

  1646.                         <p>This question collects a common type of problem: A task

  1647.         needs an external library and it has a nested classpath

  1648.         element so that you can point it to this external library, but

  1649.         that doesn't work unless you put the external library

  1650.         into the <code>CLASSPATH</code> or place it in

  1651.         <code>ANT_HOME/lib</code>.</p>

  1652.                         <p>Some background is necessary before we can discuss

  1653.         solutions for <a href="#delegating-classloader-1.5">Ant

  1654.         1.5.x</a> and <a href="#delegating-classloader-1.6">Ant

  1655.         1.6.x</a>.</p>

  1656.                         <p>When you specify a nested <code>&lt;classpath&gt;</code> in

  1657.         Ant, Ant creates a new class loader that uses the path you

  1658.         have specified.  It then tries to load additional classes from

  1659.         this classloader.</p>

  1660.                         <p>In most cases - for example using &lt;style&gt; or

  1661.         &lt;junit&gt; - Ant doesn't load the external library

  1662.         directly, it is the loaded class that does so.</p>

  1663.                         <p>In the case of <code>&lt;junit&gt;</code> it is the task

  1664.         implementation itself and in the case of

  1665.         <code>&lt;style&gt;</code> it is the implementation of the

  1666.         <code>org.apache.tools.ant.taskdefs.XSLTLiaison</code>

  1667.         class.</p>

  1668.                         <p>Ant's class loader implementation uses Java's

  1669.         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>

  1670.         the paragraph</p>

  1671.                         <blockquote>The <code>ClassLoader</code> class uses a

  1672.         delegation model to search for classes and resources. Each

  1673.         instance of <code>ClassLoader</code> has an associated parent

  1674.         class loader.  When called upon to find a class or resource, a

  1675.         <code>ClassLoader</code> instance will delegate the search for

  1676.         the class or resource to its parent class loader before

  1677.         attempting to find the class or resource itself. The virtual

  1678.         machine's built-in class loader, called the bootstrap

  1679.         class loader, does not itself have a parent but may serve as

  1680.         the parent of a <code>ClassLoader</code>

  1681.         instance.</blockquote>

  1682.                         <p>The possible solutions depend on the version of Ant you

  1683.         use, see the next sections.</p>

  1684.                     <p class="faq">

  1685.       <a name="delegating-classloader-1.5"></a>

  1686.       &lt;style&gt; or &lt;junit&gt; ignores my

  1687.       &lt;classpath&gt; - Ant 1.5.x version

  1688.     </p>

  1689.                   <p>Please read <a href="#delegating-classloader">the previous

  1690.         entry</a> before you go ahead.</p>

  1691.                         <p>First of all let's state that Ant's wrapper script

  1692.         (<code>ant</code> or <code>ant.bat</code>) adds all

  1693.         <code>.jar</code> files from <code>ANT_HOME/lib</code> to

  1694.         <code>CLASSPATH</code>, therefore "in

  1695.         <code>CLASSPATH</code>" shall mean "either in your

  1696.         <code>CLASSPATH</code> environment variable or

  1697.         <code>ANT_HOME/lib</code>" for the rest of this

  1698.         answer.</p>

  1699.                         <p>The root of the problem is that the class that needs the

  1700.         external library is on the <code>CLASSPATH</code>.</p>

  1701.                         <p>Let's see what happens when you load the &lt;junit&gt;

  1702.         task.  Ant's class loader will consult the

  1703.         bootstrap class loader first, which tries to load classes from

  1704.         <code>CLASSPATH</code>.  The bootstrap class loader

  1705.         doesn't know anything about Ant's class loader or

  1706.         even the path you have specified.</p>

  1707.                         <p>If the bootstrap class loader can load the class Ant has

  1708.         asked it to load (which it can if <code>optional.jar</code> is

  1709.         part of <code>CLASSPATH</code>), this class will try to load

  1710.         the external library from <code>CLASSPATH</code> as well - it

  1711.         doesn't know anything else - and will not find it unless

  1712.         the library is in <code>CLASSPATH</code> as well.</p>

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

  1714.                         <ol>

  1715.           <li>put all external libraries you need in

  1716.           <code>CLASSPATH</code> as well this is not what you want,

  1717.           otherwise you wouldn't have found this FAQ entry.</li>

  1718. 

  1719.           <li>remove the class that loads the external library from

  1720.           the <code>CLASSPATH</code>.</li>

  1721.         </ol>

  1722.                         <p>The easiest way to do this is to remove

  1723.         <code>optional.jar</code> from <code>ANT_HOME/lib</code>.  If

  1724.         you do so, you will have to <code>&lt;taskdef&gt;</code> all

  1725.         optional tasks and use nested <code>&lt;classpath&gt;</code>

  1726.         elements in the <code>&lt;taskdef&gt;</code> tasks that point

  1727.         to the new location of <code>optional.jar</code>.  Also,

  1728.         don't forget to add the new location of

  1729.         <code>optional.jar</code> to the

  1730.         <code>&lt;classpath&gt;</code> of your

  1731.         <code>&lt;style&gt;</code> or <code>&lt;junit&gt;</code>

  1732.         task.</p>

  1733.                         <p>If you want to avoid to <code>&lt;taskdef&gt;</code> all

  1734.         optional tasks you need, the only other option is to remove

  1735.         the classes that should not be loaded via the bootstrap class

  1736.         loader from <code>optional.jar</code> and put them into a

  1737.         separate archive. Add this separate archive to the

  1738.         <code>&lt;classpath&gt;</code> of your

  1739.         <code>&lt;style&gt;</code> or <code>&lt;junit&gt;</code> task

  1740.         - and make sure the separate archive is not in

  1741.         <code>CLASSPATH</code>.</p>

  1742.                         <p>In the case of <code>&lt;junit&gt;</code> you'd have

  1743.         to remove all classes that are in the

  1744.         <code>org/apache/tools/ant/taskdefs/optional/junit</code>

  1745.         directory, in the <code>&lt;style&gt;</code> case it is one of

  1746.         the <code>*Liaison</code> classes in

  1747.         <code>org/apache/tools/ant/taskdefs/optional</code>.</p>

  1748.                         <p>If you use the option to break up <code>optional.jar</code>

  1749.         for <code>&lt;junit&gt;</code> or remove

  1750.         <code>ant-junit.jar</code>, you still have to use a

  1751.         <code>&lt;taskdef&gt;</code> with a nested

  1752.         <code>&lt;classpath&gt;</code> to define the junit task.</p>

  1753.                     <p class="faq">

  1754.       <a name="delegating-classloader-1.6"></a>

  1755.       &lt;style&gt; or &lt;junit&gt; ignores my

  1756.       &lt;classpath&gt; - Ant 1.6.x version

  1757.     </p>

  1758.                   <p>Please read <a href="#delegating-classloader">the general

  1759.         entry</a> before you go ahead.</p>

  1760.                         <p>The wrapper script of Ant 1.6.x no longer adds the contents

  1761.         of <code>ANT_HOME/lib</code> to <code>CLASSPATH</code>,

  1762.         instead Ant will create a classloader on top of the bootstrap

  1763.         classloader - let's call it the coreloader for the rest of

  1764.         this answer - which holds the contents of

  1765.         <code>ANT_HOME/lib</code>.  Ant's core and its tasks will be

  1766.         loaded through this classloader and not the bootstrap

  1767.         classloader.</p>

  1768.                         <p>This causes some small but notable differences between Ant

  1769.         1.5.x and 1.6.x.  Most importantly, a third-party task that is

  1770.         part of <code>CLASSPATH</code> will no longer work in Ant

  1771.         1.6.x since the task now can't find Ant's classes.  In a sense

  1772.         this is the same problem this entry is about, only

  1773.         <code>ant.jar</code> has become the external library in

  1774.         question now.</p>

  1775.                         <p>This coreloader also holds the contents of

  1776.         <code>~/.ant/lib</code> and any file or directory that has

  1777.         been specified using Ant's <code>-lib</code> command line

  1778.         argument.</p>

  1779.                         <p>Let's see what happens when you load the &lt;junit&gt;

  1780.         task.  Ant's class loader will consult the bootstrap

  1781.         class loader first, which tries to load classes from

  1782.         <code>CLASSPATH</code>.  The bootstrap class loader

  1783.         doesn't know anything about Ant's class loader or

  1784.         even the path you have specified.  If it fails to find the

  1785.         class using the bootstrap classloader it will try the

  1786.         coreloader next.  Again, the coreloader doesn't know anything

  1787.         about your path.</p>

  1788.                         <p>If the coreloader can load the class Ant has asked it to

  1789.         load (which it can if <code>ant-junit.jar</code> is in

  1790.         <code>ANT_HOME/lib</code>), this class will try to load the

  1791.         external library from coreloader as well - it doesn't

  1792.         know anything else - and will not find it unless the library

  1793.         is in <code>CLASSPATH</code> or the coreloader as well.</p>

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

  1795.                         <ol>

  1796.           <li>put all external libraries you need in

  1797.           <code>CLASSPATH</code> as well this is not what you want,

  1798.           otherwise you wouldn't have found this FAQ entry.</li>

  1799. 

  1800.           <li>put all external libraries you need in

  1801.           <code>ANT_HOME/lib</code> or <code>.ant/lib</code>.  This

  1802.           probably still isn't what you want, but you might reconsider

  1803.           the <code>.ant/lib</code> option.</li>

  1804. 

  1805.           <li>Always start Ant with the <code>-lib</code> command line

  1806.           switch and point to your external libraries (or the

  1807.           directories holding them).</li>

  1808. 

  1809.           <li>remove the class that loads the external library from

  1810.           the coreloader.</li>

  1811.         </ol>

  1812.                         <p>In Ant 1.6 <code>optional.jar</code> has been split into

  1813.         multiple jars, each one containing classes with the same

  1814.         dependencies on external libraries.  You can move the

  1815.         "offending" jar out of <code>ANT_HOME/lib</code>.  For the

  1816.         <code>&lt;junit&gt;</code> task it would be

  1817.         <code>ant-junit.jar</code> and for <code>&lt;style&gt;</code>

  1818.         it would be <code>ant-trax.jar</code>,

  1819.         <code>ant-xalan1.jar</code> or <code>ant-xslp.jar</code> -

  1820.         depending on the processor you use.</p>

  1821.                         <p>If you do so, you will have to <code>&lt;taskdef&gt;</code>

  1822.         all optional tasks that need the external libary and use

  1823.         nested <code>&lt;classpath&gt;</code> elements in the

  1824.         <code>&lt;taskdef&gt;</code> tasks that point to the new

  1825.         location of <code>ant-*.jar</code>.  Also, don't forget

  1826.         to add the new location of <code>ant-*.jar</code> to the

  1827.         <code>&lt;classpath&gt;</code> of your

  1828.         <code>&lt;style&gt;</code> or <code>&lt;junit&gt;</code>

  1829.         task.</p>

  1830.                         <p>For example</p>

  1831.                         <pre class="code">

  1832.     &lt;taskdef name=&quot;junit&quot;

  1833.             class=&quot;org.apache.tools.ant.taskdefs.optional.junit.JUnitTask&quot;&gt;

  1834.       &lt;classpath&gt;

  1835.         &lt;pathelement location=&quot;HOME-OF/junit.jar&quot;/&gt;

  1836.         &lt;pathelement location=&quot;NEW-HOME-OF/ant-junit.jar&quot;/&gt;

  1837.       &lt;/classpath&gt;

  1838.     &lt;/taskdef&gt;

  1839. </pre>

  1840.                     <p class="faq">

  1841.       <a name="winxp-jdk14-ant14"></a>

  1842.       When running Ant 1.4 on Windows XP and JDK 1.4, I get

  1843.       various errors when trying to <code>&lt;exec&gt;</code>, fork

  1844.       <code>&lt;java&gt;</code> or access environment

  1845.       variables.

  1846.     </p>

  1847.                   <p>Ant &lt; 1.5 doesn't recognize Windows XP as a flavor

  1848.         of Windows that runs <code>CMD.EXE</code> instead of

  1849.         <code>COMMAND.COM</code>.  JDK 1.3 will tell Ant that Windows

  1850.         XP is Windows 2000 so the problem doesn't show up

  1851.         there.</p>

  1852.                         <p>Apart from upgrading to Ant 1.5 or better, setting the

  1853.         environment variable <code>ANT_OPTS</code> to

  1854.         <code>-Dos.name=Windows_NT</code> prior to invoking Ant has

  1855.         been confirmed as a workaround.</p>

  1856.                     <p class="faq">

  1857.       <a name="1.5-cygwin-sh"></a>

  1858.       The <code>ant</code> wrapper script of Ant 1.5 fails

  1859.       for Cygwin if <code>ANT_HOME</code> is set to a Windows style

  1860.       path.

  1861.     </p>

  1862.                   <p>This problem has been reported only hours after Ant 1.5 has

  1863.         been released, see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=10664">Bug

  1864.         10664</a> and all its duplicates.</p>

  1865.                         <p>A fixed version of the wrapper script can be found <a href="http://ant.apache.org/old-releases/v1.5/errata/">here</a>.

  1866.         Simply replace your script with this version.</p>

  1867.                     <p class="faq">

  1868.       <a name="1.5.2-zip-broken"></a>

  1869.       <code>&lt;zip&gt;</code> is broken in Ant 1.5.2.

  1870.     </p>

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

  1872.                         <p>The problem reported by most people - see <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17648">Bug

  1873.         17648</a> and all its duplicates - is that Ant creates

  1874.         archives that a partially unreadable by WinZIP.  Luckily

  1875.         <code>jar</code> deals with the archives and so the generated

  1876.         jars/wars/ears will most likely work for you anyway.</p>

  1877.                         <p>There are additional problems, see bugs <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17780">Bug

  1878.         17780</a>, <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17871">Bug

  1879.         17871</a> and <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=18403">Bug

  1880.         18403</a>.  All of them are supposed to be fixed with Ant

  1881.         1.5.3 (and only 18403 should exist in 1.5.3beta1).</p>

  1882.                     <p class="faq">

  1883.       <a name="unknownelement.taskcontainer"></a>

  1884.       

  1885.         Why do my custom task containers see Unknown Elements in Ant 1.6

  1886.         - they worked in Ant 1.5?

  1887.       

  1888.     </p>

  1889.                   <p>

  1890.           The objects added in TaskContainer.addTask(Task task)

  1891.           have changed from  Tasks to UnknownElements.

  1892.         </p>

  1893.                         <p>

  1894.           There was a number of valid reasons for this change. But the backward

  1895.           compatibility problems were not noticed until after Ant 1.6.0 was

  1896.           released.

  1897.         </p>

  1898.                         <p>

  1899.           Your container class will need to be modified to check if the Task

  1900.           is an UnknownElement and call perform on it to

  1901.           convert it to a Task and to execute it.

  1902.           (see apache.tools.ant.taskdefs.Sequential)

  1903.         </p>

  1904.                         <p>

  1905.           If you want to do more processing on the task,

  1906.           you need to use the techniques in apache.tools.ant.taskdefs.Antlib#execute()

  1907.           This does make use of one 1.6 method call (UE#getRealObject()),

  1908.           you need to use UE#getTask() instead - this will

  1909.           return null for non tasks (types like fileset id=x).

  1910.         </p>

  1911.                         <p>

  1912.           So.. iterate over the tasks, if they are UEs, convert them to

  1913.           tasks, using UE#maybeConfigure and UE#getTask()

  1914.         </p>

  1915.                         <pre class="code">

  1916.         for (Iterator i = tasks.iterator(); i.hasNext();) {

  1917.            Task t = (Task) i.next();

  1918.            if (t instanceof UnknownElement) {

  1919.               ((UnknownElement) t).maybeConfigure();

  1920.               t = ((UnknownElement) t).getTask();

  1921.               if (t == null) {

  1922.                   continue;

  1923.               }

  1924.            }

  1925.            // .... original Custom code

  1926.         }

  1927.         </pre>

  1928.                         <p>

  1929.           This approach should work for ant1.5 and ant1.6.

  1930.         </p>

  1931.                     <p class="faq">

  1932.       <a name="java.exception.stacktrace"></a>

  1933.       

  1934.         The program I run via &lt;java&gt; throws an exception but I

  1935.         can't seem to get the full stack trace.

  1936.       

  1937.     </p>

  1938.                   <p>This is a know bug that has been fixed after the release of

  1939.         Ant 1.6.1.</p>

  1940.                         <p>As a workaround, run your &lt;java&gt; task with

  1941.         <code>fork="true"</code> and Ant will display the full

  1942.         trace.</p>

  1943.                     <p class="faq">

  1944.       <a name="junit-no-runtime-xml"></a>

  1945.       

  1946.         Using format="xml", &lt;junit&gt; fails with a

  1947.         <code>NoClassDefFoundError</code> if forked.

  1948.       

  1949.     </p>

  1950.                   <p>The XML formatter needs the <a href="http://www.w3.org/DOM/">DOM classes</a> to work.  If you

  1951.         are using JDK 1.4 or later they are included with your Java

  1952.         Runtime and this problem won't occur.  If you are running JDK

  1953.         1.3 or earlier, the DOM classes have to be on your

  1954.         &lt;junit&gt; task's &lt;classpath&gt;.</p>

  1955.                         <p>Prior to Ant 1.6.0 Ant would include the DOM classes from

  1956.         the XML parser that is used by Ant itself if you set the

  1957.         includeAntRuntime attribute to true (the default).  With Ant

  1958.         1.6.0 this has been changed as this behavior made it

  1959.         impossible to use a different XML parser in your tests.</p>

  1960.                         <p>This means that you have to take care of the DOM classes

  1961.         explicitly starting with Ant 1.6.0.  If you don't need to set

  1962.         up a different XML parser for your tests, the easiest solution

  1963.         is to add</p>

  1964.                         <pre class="code">

  1965. &lt;pathelement path=&quot;${ant.home}/lib/xml-apis.jar:${ant.home}/lib/xercesImpl.jar&quot;/&gt;

  1966. </pre>

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

  1968.                     <p class="faq">

  1969.       <a name="xalan-jdk1.5"></a>

  1970.       

  1971.         <code>&lt;junitreport&gt;</code> doesn't work with JDK 1.5 but

  1972.         worked fine with JDK 1.4.

  1973.       

  1974.     </p>

  1975.                   <p>While JDK 1.4.x contains a version of Xalan-J 2, JDK 1.5

  1976.         (and later?) have <a href="http://java.sun.com/j2se/1.5.0/compatibility.html#4959783">moved

  1977.         to XSLTC</a>.  Since this task uses Xalan's redirect

  1978.         extensions for its internal stylesheet, Ant doesn't support

  1979.         XSLTC yet.  This means that you have to install <a href="http://xml.apache.org/xalan-j/">Xalan-J 2</a> in order

  1980.         to use this task with JDK 1.5.</p>

  1981.                         <p>Starting with Ant 1.6.2 <code>&lt;junitreport&gt;</code>

  1982.         supports JDK 1.5.</p>

  1983.                     </div>

  1984.   </div>

  1985. 

  1986.         <p class="copyright">

  1987.         Copyright &copy; 2000-2005&nbsp;The Apache Software Foundation. All rights reserved.

  1988.         <script type="text/javascript" language="JavaScript"><!--

  1989.                 document.write(" - "+"Last Published: " + document.lastModified);

  1990.               //  -->

  1991.         </script>

  1992.       </p>

  1993.     </body>

  1994.   </html>

  1995. 

  1996. 

  1997. 

  1998. 

  1999. 

  2000. 

  2001. 

  2002. 

  2003. 

  2004.
Please read the following content carefully:

Dear OpenI User

Thank you for your continuous support to the Openl Qizhi Community AI Collaboration Platform. In order to protect your usage rights and ensure network security, we updated the Openl Qizhi Community AI Collaboration Platform Usage Agreement in January 2024. The updated agreement specifies that users are prohibited from using intranet penetration tools. After you click "Agree and continue", you can continue to use our services. Thank you for your cooperation and understanding.

For more agreement content, please refer to the《Openl Qizhi Community AI Collaboration Platform Usage Agreement》

Agree and continue
Disagree, exit