| <?xml version="1.0"?> |
| <document> |
| |
| <properties> |
| <author email="bodewig@apache.org">Stefan Bodewig</author> |
| <title>Frequently Asked Questions</title> |
| </properties> |
| |
| <faqsection title="About this FAQ"> |
| <faq id="latest-version"> |
| <question>Where do I find the latest version of this |
| document?</question> |
| <answer> |
| <p>The latest version can always be found at Ant's homepage |
| <a href="http://ant.apache.org/faq.html">http://ant.apache.org/faq.html</a>.</p> |
| </answer> |
| </faq> |
| |
| <faq id="adding-faqs"> |
| <question>How can I contribute to this FAQ?</question> |
| <answer> |
| <p>The page you are looking it is generated from |
| <a href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/faq.xml">this</a> |
| document. If you want to add a new question, please submit |
| a patch against this document to one of Ant's mailing lists; |
| hopefully, the structure is self-explanatory.</p> |
| |
| <p>If you don't know how to create a patch, see the patches |
| section of <a href="http://jakarta.apache.org/site/source.html">this |
| page</a>.</p> |
| </answer> |
| </faq> |
| |
| <faq id="creating-faq"> |
| <question>How do you create the HTML version of this |
| FAQ?</question> |
| |
| <answer> |
| <p>We use |
| <a href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a> |
| to render the HTML version from the original XML file.</p> |
| |
| <p>The Velocity stylesheets used to process the XML files can |
| be found in the <code>xdocs/stylesheets</code> subdirectory of |
| Ant's CVS repository - the build file |
| <code>docs.xml</code> at the top level of the ant CVS |
| module is used to drive Anakia.</p> |
| |
| <p>This file assumes that you have the |
| <code>jakarta-site2</code> CVS module checked out as well, but |
| if you follow the instruction from Anakia's homepage, you |
| should get it to work without that. Just make sure all |
| required jars are in the task's classpath.</p> |
| </answer> |
| </faq> |
| |
| </faqsection> |
| |
| <faqsection title="General"> |
| <faq id="what-is-ant"> |
| <question>What is Apache Ant?</question> |
| <answer> |
| <p> Ant is a Java-based build tool. In theory, it is kind of |
| like Make, without Make's wrinkles and with the full |
| portability of pure Java code.</p> |
| </answer> |
| </faq> |
| |
| <faq id="ant-name"> |
| <question>Why do you call it Ant?</question> |
| <answer> |
| |
| <p>According to Ant's original author, James Duncan |
| Davidson, the name is an acronym for "Another Neat |
| Tool".</p> |
| |
| <p>Later explanations go along the lines of "ants |
| do an extremely good job at building things", or |
| "ants are very small and can carry a weight dozens of times |
| their own" - describing what Ant is intended to |
| be.</p> |
| </answer> |
| </faq> |
| |
| <faq id="history"> |
| <question>Tell us a little bit about Ant's history.</question> |
| <answer> |
| |
| <p>Initially, Ant was part of the Tomcat code base, when it was |
| donated to the Apache Software Foundation. It was |
| created by James Duncan Davidson, who is also the original |
| author of Tomcat. Ant was there to build Tomcat, nothing |
| else.</p> |
| |
| <p>Soon thereafter, several open source Java projects realized |
| that Ant could solve the problems they had with Makefiles. |
| Starting with the projects hosted at Jakarta and the old Java |
| Apache project, Ant spread like a virus and is now the build |
| tool of choice for a lot of projects.</p> |
| |
| <p>In January 2000, Ant was moved to a separate CVS module and |
| was promoted to a project of its own, independent of |
| Tomcat, and became Apache Ant.</p> |
| |
| <p>The first version of Ant that was exposed to a larger audience |
| was the one that shipped with Tomcat's 3.1 release on 19 April |
| 2000. This version has later been referred to as Ant |
| 0.3.1.</p> |
| |
| <p>The first official release of Ant as a stand-alone product was |
| Ant 1.1, released on 19 July 2000. The complete release |
| history:</p> |
| |
| <table> |
| <tr> |
| <th>Ant Version</th> |
| <th>Release Date</th> |
| </tr> |
| |
| <tr> |
| <td>1.1</td> |
| <td>19 July 2000</td> |
| </tr> |
| |
| <tr> |
| <td>1.2</td> |
| <td>24 October 2000</td> |
| </tr> |
| |
| <tr> |
| <td>1.3</td> |
| <td>3 March 2001</td> |
| </tr> |
| |
| <tr> |
| <td>1.4</td> |
| <td>3 September 2001</td> |
| </tr> |
| |
| <tr> |
| <td>1.4.1</td> |
| <td>11 October 2001</td> |
| </tr> |
| |
| <tr> |
| <td>1.5</td> |
| <td>10 July 2002</td> |
| </tr> |
| |
| <tr> |
| <td>1.5.1</td> |
| <td>3 October 2002</td> |
| </tr> |
| |
| <tr> |
| <td>1.5.2</td> |
| <td>3 March 2003</td> |
| </tr> |
| |
| <tr> |
| <td>1.5.3</td> |
| <td>9 April 2003</td> |
| </tr> |
| |
| <tr> |
| <td>1.5.4</td> |
| <td>12 August 2003</td> |
| </tr> |
| </table> |
| </answer> |
| </faq> |
| |
| </faqsection> |
| |
| <faqsection title="Installation"> |
| <faq id="no-gnu-tar"> |
| <question>I get checksum errors when I try to extract the |
| <code>tar.gz</code> distribution file. Why?</question> |
| <answer> |
| <p>Ant's distribution contains file names that are longer |
| than 100 characters, which is not supported by the standard |
| tar file format. Several different implementations of tar use |
| different and incompatible ways to work around this |
| restriction.</p> |
| |
| <p>Ant's <tar> task can create tar archives that use |
| the GNU tar extension, and this has been used when putting |
| together the distribution. If you are using a different |
| version of tar (for example, the one shipping with Solaris), |
| you cannot use it to extract the archive.</p> |
| |
| <p>The solution is to either install GNU tar, which can be |
| found <a href="http://www.gnu.org/software/tar/tar.html">here</a>, |
| or use the zip archive instead (you can extract it using |
| <code>jar xf</code>).</p> |
| </answer> |
| </faq> |
| </faqsection> |
| |
| <faqsection title="How do I ..."> |
| <faq id="adding-external-tasks"> |
| <question>How do I add an external task that I've written to the |
| page "External Tools and Task"?</question> |
| <answer> |
| |
| <p>Join and post a message to the dev or user mailing |
| list (one list is enough), including the following |
| information:</p> |
| |
| <ul> |
| <li>the name of the task/tool</li> |
| <li>a short description of the task/tool</li> |
| <li>a Compatibility: entry stating with which version(s) of |
| Ant the tool/task is compatible to</li> |
| <li>a URL: entry linking to the main page of the tool/task</li> |
| <li>a Contact: entry containing the email address or the URL |
| of a webpage for the person or list to contact for issues |
| related to the tool/task. <strong>Note that we'll add a |
| link on the page, so any email address added there is not |
| obfuscated and can (and probably will) be abused by robots |
| harvesting websites for addresses to spam.</strong></li> |
| <li>a License: entry containing the type of license for the |
| tool/task</li> |
| </ul> |
| |
| <p>The preferred format for this information is a patch to <a |
| href="http://cvs.apache.org/viewcvs.cgi/~checkout~/ant/xdocs/external.xml">this</a> |
| document.</p> |
| |
| </answer> |
| |
| </faq> |
| |
| <faq id="passing-cli-args"> |
| <question>How do I pass parameters from the command line to my |
| build file?</question> |
| <answer> |
| |
| <p>Use properties. Using <code>ant |
| -D<em>name</em>=<em>value</em></code> lets you define values for |
| properties on the Ant command line. These properties can then be |
| used within your build file as |
| any normal property: <code>${<em>name</em>}</code> will put in |
| <code><em>value</em></code>.</p> |
| |
| </answer> |
| </faq> |
| |
| <faq id="jikes-switches"> |
| <question>How can I use Jikes-specific command-line |
| switches?</question> |
| |
| <answer> |
| |
| <p>A couple of switches are supported via "magic" |
| properties:</p> |
| |
| <table> |
| <tr> |
| <th>switch</th> |
| <th>property</th> |
| <th>default</th> |
| </tr> |
| |
| <tr> |
| <td>+E</td> |
| <td>build.compiler.emacs</td> |
| <td>false == not set</td> |
| </tr> |
| |
| <tr> |
| <td>+P</td> |
| <td>build.compiler.pedantic</td> |
| <td>false == not set</td> |
| </tr> |
| |
| <tr> |
| <td>+F</td> |
| <td>build.compiler.fulldepend</td> |
| <td>false == not set</td> |
| </tr> |
| |
| <tr> |
| <td><strong>(Only for Ant < 1.4; replaced by the |
| <code><strong>nowarn</strong></code> |
| attribute of the <code><strong><javac></strong></code> |
| task after that.)</strong><br></br>-nowarn</td> |
| <td>build.compiler.warnings</td> |
| <td>true == not set</td> |
| </tr> |
| |
| </table> |
| |
| <p>With Ant >= 1.5, you can also use nested |
| <code><compilerarg></code> elements with the |
| <code><javac></code> task.</p> |
| |
| </answer> |
| </faq> |
| |
| <faq id="shell-redirect-1"> |
| <question>How do I include a < character in my command-line arguments?</question> |
| <answer> |
| <p>The short answer is "Use: <code>&lt;</code>".</p> |
| |
| <p>The long answer is that this probably won't do what you |
| want anyway (see <a href="#shell-redirect-2">the next |
| section</a>).</p> |
| </answer> |
| </faq> |
| |
| <faq id="shell-redirect-2"> |
| <question>How do I redirect standard input or standard output |
| in the <code><exec></code> task?</question> |
| <answer> |
| <p>Say you want to redirect the standard output stream of the |
| <code>m4</code> command to write to a file, something |
| like:</p> |
| |
| <source><![CDATA[ |
| shell-prompt> m4 foo.m4 > foo |
| ]]></source> |
| |
| <p>and try to translate it into</p> |
| |
| <source><![CDATA[ |
| <exec executable="m4"> |
| <arg value="foo.m4"/> |
| <arg value=">"/> |
| <arg value="foo"/> |
| </exec> |
| ]]></source> |
| |
| <p>This will not do what you expect. The output redirection is |
| performed by your shell, not the command itself, so this |
| should read:</p> |
| |
| <source><![CDATA[ |
| <exec executable="/bin/sh"> |
| <arg value="-c" /> |
| <arg value="m4 foo.m4 > foo" /> |
| </exec> |
| ]]></source> |
| |
| <p>Note that you must use the <code>value</code> attribute of |
| <code><arg></code> in the last element, in order to have |
| the command passed as a single, quoted argument. Alternatively, |
| you can use:</p> |
| <source><![CDATA[ |
| <exec executable="/bin/sh"> |
| <arg line='-c "m4 foo.m4 > foo"'/> |
| </exec> |
| ]]></source> |
| |
| <p>Note the double-quotes nested inside the single-quotes.</p> |
| |
| </answer> |
| </faq> |
| |
| <faq id="batch-shell-execute"> |
| <question>How do I execute a batch file or shell script from Ant?</question> |
| <answer> |
| |
| <p>On native Unix systems, you should be able to run shell scripts |
| directly. On systems running a Unix-type shell (for example, Cygwin |
| on Windows) execute the (command) shell instead - <code>cmd</code> |
| for batch files, <code>sh</code> for shell scripts - then pass the |
| batch file or shell script (plus any arguments to the script) |
| as a single command, using the <code>/c</code> or |
| <code>-c</code> switch, respectively. See |
| <a href="#shell-redirect-2">the above section</a> |
| for example <code><exec></code> tasks |
| executing <code>sh</code>. For batch files, use something like:</p> |
| <source><![CDATA[ |
| <exec dir="." executable="cmd" os="Windows NT"> |
| <arg line="/c test.bat"/> |
| </exec> |
| ]]></source> |
| |
| </answer> |
| </faq> |
| |
| <faq id="multi-conditions"> |
| <question>I want to execute a particular target only if |
| multiple conditions are true.</question> |
| |
| <answer> |
| <p>There are actually several answers to this question.</p> |
| |
| <p>If you have only one set and one unset property to test, |
| you can specify both an <code>if</code> and an <code>unless</code> |
| attribute for the target, and they will act as if they |
| are "anded" together.</p> |
| |
| <p>If you are using a version of Ant 1.3 or earlier, the |
| way to work with all other cases is to chain targets together |
| to determine the specific state you want to test for.</p> |
| |
| <p>To see how this works, assume you have three properties: |
| <code>prop1</code>, <code>prop2</code>, and <code>prop3</code>. |
| You want to test that <code>prop1</code> and <code>prop2</code> |
| are set, and that <code>prop3</code> is not. If the condition |
| holds true you want to echo "yes".</p> |
| |
| <p>Here is the implementation in Ant 1.3 and earlier:</p> |
| |
| <source><![CDATA[ |
| <target name="cond" depends="cond-if"/> |
| |
| <target name="cond-if" if="prop1"> |
| <antcall target="cond-if-2"/> |
| </target> |
| |
| <target name="cond-if-2" if="prop2"> |
| <antcall target="cond-if-3"/> |
| </target> |
| |
| <target name="cond-if-3" unless="prop3"> |
| <echo message="yes"/> |
| </target> |
| ]]></source> |
| |
| <p>Note: <code><antcall></code> tasks do <em>not</em> pass |
| property changes back up to the environment they were called |
| from, so you would'nt be able to, for example, set a |
| <code>result</code> property in the <code>cond-if-3</code> target, |
| then do |
| <code><echo message="result is ${result}"/></code> |
| in the <code>cond</code> target.</p> |
| |
| <p>Starting with Ant 1.4, you can use the |
| <code><condition></code> task.</p> |
| |
| <source><![CDATA[ |
| <target name="cond" depends="cond-if,cond-else"/> |
| |
| <target name="check-cond"> |
| <condition property="cond-is-true"> |
| <and> |
| <not> |
| <equals arg1="${prop1}" arg2="$${prop1}" /> |
| </not> |
| <not> |
| <equals arg1="${prop2}" arg2="$${prop2}" /> |
| </not> |
| <equals arg1="${prop3}" arg2="$${prop3}" /> |
| </and> |
| </condition> |
| </target> |
| |
| <target name="cond-if" depends="check-cond" if="cond-is-true"> |
| <echo message="yes"/> |
| </target> |
| |
| <target name="cond-else" depends="check-cond" unless="cond-is-true"> |
| <echo message="no"/> |
| </target> |
| ]]></source> |
| |
| <p>This version takes advantage of two things:</p> |
| |
| <ul> |
| <li>If a property <code>a</code> has not been set, |
| <code>${a}</code> will evaluate to <code>${a}</code>.</li> |
| |
| <li>To get a literal <code>$</code> in Ant, you have to |
| escape it with another <code>$</code> - this will also break |
| the special treatment of the <code>${</code> sequence.</li> |
| </ul> |
| |
| <p>Because testing for a literal <code>${property}</code> string |
| isn't all that readable or easy to understand, |
| post-1.4.1 Ant introduces the <code><isset></code> element |
| to the <code><condition></code> task.</p> |
| |
| <p>Here is the previous example done using |
| <code><isset></code>:</p> |
| |
| <source><![CDATA[ |
| <target name="check-cond"> |
| <condition property="cond-is-true"> |
| <and> |
| <isset property="prop1"/> |
| <isset property="prop2"/> |
| <not> |
| <isset property="prop3"/> |
| </not> |
| </and> |
| </condition> |
| </target> |
| ]]></source> |
| |
| <p>The last option is to use a scripting language to set the |
| properties. This can be particularly handy when you need much |
| finer control than the simple conditions shown here but, of |
| course, comes with the overhead of adding JAR files to support |
| the language, to say nothing of the added maintenance in requiring |
| two languages to implement a single system. See the |
| <a href="manual/OptionalTasks/script.html"> |
| <code><script></code> task documentation</a> for more |
| details.</p> |
| </answer> |
| </faq> |
| |
| <faq id="encoding"> |
| <question>How can I include national characters like German |
| umlauts in my build file?</question> |
| |
| <answer> |
| <p>You need to tell the XML parser which character encoding |
| your build file uses, this is done inside the <a |
| href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-prolog-dtd">XML |
| declaration</a>.</p> |
| |
| <p>By default the parser assumes you are using the UTF-8 |
| encoding instead of your platform's default. For most Western |
| European countries you should set the encoding to |
| <code>ISO-8859-1</code>. To do so, make the very first line |
| of you build file read like</p> |
| |
| <source><![CDATA[ |
| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| ]]></source> |
| </answer> |
| </faq> |
| |
| <faq id="use-zip-instead-of-jar"> |
| <question>How do I use <code>jar</code>'s <code>M</code> switch? |
| I don't want a MANIFEST.</question> |
| |
| <answer> |
| <p>A JAR archive is a ZIP file, so if you don't want a |
| MANIFEST you can simply use <code><zip></code>.</p> |
| |
| <p>If your file names contain national characters you should |
| know that Sun's <code>jar</code> utility like Ant's |
| <code><jar></code> uses UFT8 to encode their names while |
| <code><zip></code> uses your platforms default encoding. |
| Use the encoding attribute of <code><zip></code> if |
| necessary.</p> |
| </answer> |
| </faq> |
| </faqsection> |
| |
| <faqsection title="It doesn't work (as expected)"> |
| <faq id="always-recompiles"> |
| <question>Why does Ant always recompile all my Java files?</question> |
| <answer> |
| |
| <p>In order to find out which files should be compiled, Ant |
| compares the timestamps of the source files to those of the |
| resulting <code>.class</code> files. Opening all source files |
| to find out which package they belong to would be very |
| inefficient. Instead, Ant expects you to place your |
| source files in a directory hierarchy that mirrors your |
| package hierarchy and to point Ant to the root of this |
| directory tree with the <code>srcdir</code> attribute.</p> |
| |
| <p>Say you have <code><javac srcdir="src" |
| destdir="dest"/></code>. If Ant finds a file |
| <code>src/a/b/C.java</code>, it expects it to be in package |
| <code>a.b</code> so that the resulting <code>.class</code> |
| file is going to be <code>dest/a/b/C.class</code>.</p> |
| |
| <p>If your source-tree directory structure does not match your |
| package structure, Ant's heuristic won't work, and |
| it will recompile classes that are up-to-date. Ant is not the |
| only tool that expects a source-tree layout like this.</p> |
| |
| <p>If you have Java source files that aren't declared to |
| be part of any package, you can still use the <code><javac></code> |
| task to compile these files correctly - just set the |
| <code>srcdir</code> and <code>destdir</code> attributes to |
| the actual directory the source |
| files live in and the directory the class files should go into, |
| respectively.</p> |
| |
| </answer> |
| </faq> |
| |
| <faq id="defaultexcludes"> |
| |
| <question>I've used a <code><delete></code> task to |
| delete unwanted SourceSafe control files (CVS files, editor |
| backup files, etc.), but it doesn't seem to work; the files |
| never get deleted. What's wrong?</question> |
| |
| <answer> |
| <p>This is probably happening because, by default, Ant excludes |
| SourceSafe control files (<code>vssver.scc</code>) and certain other |
| files from FileSets.</p> |
| |
| <p>Here's what you probably did:</p> |
| |
| |
| <source><![CDATA[ |
| <delete> |
| <fileset dir="${build.src}" includes="**/vssver.scc"/> |
| </delete> |
| ]]></source> |
| |
| <p>You need to switch off the default exclusions, |
| and it will work:</p> |
| <source><![CDATA[ |
| <delete> |
| <fileset dir="${build.src}" includes="**/vssver.scc" |
| defaultexcludes="no"/> |
| </delete> |
| ]]></source> |
| |
| <p>For a complete listing of the patterns that are excluded |
| by default, see <a href="manual/dirtasks.html#defaultexcludes">the user |
| manual</a>.</p> |
| |
| </answer> |
| </faq> |
| |
| <faq id="stop-dependency"> |
| <question>I have a target I want to skip if a property is set, |
| so I have <code>unless="property"</code> as an attribute |
| of the target, but all the targets this target |
| depends on are still executed. Why?</question> |
| |
| <answer> |
| <p>The list of dependencies is generated by Ant before any of the |
| targets are run. This allows dependent targets, such as an |
| <code>init</code> target, to set properties that can control the |
| execution of the targets higher in the dependency graph. This |
| is a good thing.</p> |
| |
| <p>However, when your dependencies break down the |
| higher-level task |
| into several smaller steps, this behaviour becomes |
| counter-intuitive. There are a couple of solutions available: |
| </p> |
| |
| <ol> |
| <li>Put the same condition on each of the dependent targets.</li> |
| |
| <li>Execute the steps using <code><antcall></code>, |
| instead of specifying them inside the <code>depends</code> |
| attribute.</li> |
| </ol> |
| |
| </answer> |
| </faq> |
| |
| <faq id="include-order"> |
| <question>In my <code><fileset></code>, I've put in an |
| <code><exclude></code> of all files followed by an |
| <code><include></code> of just the files I want, but it |
| isn't giving me any files at all. What's wrong? |
| </question> |
| |
| <answer> |
| <p>The order of the <code><include></code> and |
| <code><exclude></code> tags within a <code><fileset></code> |
| is ignored when the FileSet is created. Instead, all of the |
| <code><include></code> elements are processed together, |
| followed by all of the <code><exclude></code> |
| elements. This means that the <code><exclude></code> |
| elements only apply to the file list produced by the |
| <code><include></code> elements.</p> |
| |
| <p>To get the files you want, focus on just the |
| <code><include></code> patterns that would be necessary |
| to get them. If you find you need to trim the list that the |
| <code><include></code> elements produce, then use |
| <code><exclude></code> elements.</p> |
| </answer> |
| </faq> |
| |
| <faq id="properties-not-trimmed"> |
| <question><code>ant</code> failed to build my program via javac |
| even when I put the needed jars in an external |
| <code>build.properties</code> file and reference them by |
| <code>pathelement</code> or <code>classpath refid</code>.</question> |
| |
| <answer> |
| |
| <p>When <code>ant</code> loads properties from an external |
| file it dosn't touch the value of properties, trailing blanks |
| will not be trimmed for example.</p> |
| |
| <p>If the value represents a file path, like a jar needed to |
| compile, the task which requires the value, javac for example |
| would fail to compile since it can't find the file due to |
| trailing spaces.</p> |
| </answer> |
| </faq> |
| |
| <faq id="winzip-lies"> |
| <question>Ant creates WAR files with a lower-case |
| <code>web-inf</code> or JAR files with a lower-case |
| <code>meta-inf</code> directory.</question> |
| |
| <answer> |
| <p>No it doesn't.</p> |
| |
| <p>You may have seen these lower-case directory names in |
| WinZIP, but WinZIP is trying to be helpful (and fails). If |
| WinZIP encounters a filename that is all upper-case, it |
| assumes it has come from an old DOS box and changes the case to |
| all lower-case for you.</p> |
| |
| <p>If you extract (or just check) the archive with jar, you |
| will see that the names have the correct case.</p> |
| |
| <p>With WinZIP (version 8.1 at least), this can be corrected in the |
| configuration. In the Options/Configuration menu, in the View tab, General |
| section, check the "Allow all upper case files names" box. The META-INF and |
| WEB-INF will look correct.</p> |
| </answer> |
| </faq> |
| </faqsection> |
| |
| <faqsection title="Ant and IDEs/Editors"> |
| <faq id="integration"> |
| <question>Is Ant supported by my IDE/Editor?</question> |
| <answer> |
| <p>See the <a href="external.html#IDE and Editor Integration">section |
| on IDE integration</a> on our External Tools and Tasks page.</p> |
| </answer> |
| </faq> |
| |
| <faq id="emacs-mode"> |
| <question>Why doesn't (X)Emacs/vi/MacOS X's project builder |
| correctly parse the error messages generated by Ant?</question> |
| <answer> |
| |
| <p>Ant adds a "banner" with the name of the current |
| task in front of all logging messages - and there are no built-in |
| regular expressions in your editor that would account for |
| this.</p> |
| |
| <p>You can disable this banner by invoking Ant with the |
| <code>-emacs</code> switch. To make Ant autodetect |
| Emacs' compile mode, put this into your |
| <code>.antrc</code> (contributed by Ville Skyttä).</p> |
| |
| <source><![CDATA[ |
| # Detect (X)Emacs compile mode |
| if [ "$EMACS" = "t" ] ; then |
| ANT_ARGS="$ANT_ARGS -emacs" |
| ANT_OPTS="$ANT_OPTS -Dbuild.compiler.emacs=true" |
| fi |
| ]]></source> |
| |
| <p>Alternatively, you can add the following snippet to your |
| <code>.emacs</code> to make Emacs understand Ant's |
| output.</p> |
| |
| <source><![CDATA[ |
| (require 'compile) |
| (setq compilation-error-regexp-alist |
| (append (list |
| ;; works for jikes |
| '("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):\\([0-9]+\\):[0-9]+:[0-9]+:" 1 2 3) |
| ;; works for javac |
| '("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):" 1 2)) |
| compilation-error-regexp-alist)) |
| ]]></source> |
| |
| <p>Yet another alternative that preserves most of Ant's |
| formatting is to pipe Ant's output through the following Perl |
| script by Dirk-Willem van Gulik:</p> |
| |
| <source><![CDATA[ |
| #!/usr/bin/perl |
| # |
| # May 2001 dirkx@apache.org - remove any |
| # [foo] lines from the output; keeping |
| # spacing more or less there. |
| # |
| $|=1; |
| while(<STDIN>) { |
| if (s/^(\s+)\[(\w+)\]//) { |
| if ($2 ne $last) { |
| print "$1\[$2\]"; |
| $s = ' ' x length($2); |
| } else { |
| print "$1 $s "; |
| }; |
| $last = $2; |
| }; |
| print; |
| }; |
| ]]></source> |
| |
| </answer> |
| </faq> |
| </faqsection> |
| |
| <faqsection title="Advanced Issues"> |
| <faq id="dtd"> |
| <question>Is there a DTD that I can use to validate my build |
| files?</question> |
| |
| <answer> |
| |
| <p>An incomplete DTD can be created by the |
| <code><antstructure></code> task - but this one |
| has a few problems:</p> |
| |
| <ul> |
| <li>It doesn't know about required attributes. Only |
| manual tweaking of this file can help here.</li> |
| |
| <li>It is not complete - if you add new tasks via |
| <code><taskdef></code> it won't know about it. See |
| <a href="http://www.sdv.fr/pages/casa/html/ant-dtd.en.html">this |
| page</a> by Michel Casabianca for a solution to this |
| problem. Note that the DTD you can download at this page |
| is based on Ant 0.3.1.</li> |
| |
| <li>It may even be an invalid DTD. As Ant allows tasks |
| writers to define arbitrary elements, name collisions will |
| happen quite frequently - if your version of Ant contains |
| the optional <code><test></code> and |
| <code><junit></code> tasks, there are two XML |
| elements named <code>test</code> (the task and the nested child |
| element of <code><junit></code>) with different attribute |
| lists. This problem cannot be solved; DTDs don't give a |
| syntax rich enough to support this.</li> |
| </ul> |
| </answer> |
| </faq> |
| |
| <faq id="xml-entity-include"> |
| <question>How do I include an XML snippet in my build file?</question> |
| <answer> |
| <p>You can use XML's way of including external files and let |
| the parser do the job for Ant:</p> |
| |
| <source><![CDATA[ |
| <?xml version="1.0"?> |
| |
| <!DOCTYPE project [ |
| <!ENTITY common SYSTEM "file:./common.xml"> |
| ]> |
| |
| <project name="test" default="test" basedir="."> |
| |
| <target name="setup"> |
| ... |
| </target> |
| |
| &common; |
| |
| ... |
| |
| </project> |
| ]]></source> |
| |
| <p>will literally include the contents of <code>common.xml</code> where |
| you've placed the <code>&common;</code> entity.</p> |
| |
| <p>In combination with a DTD, this would look like this:</p> |
| |
| <source><![CDATA[ |
| <!DOCTYPE project PUBLIC "-//ANT//DTD project//EN" "file:./ant.dtd" [ |
| <!ENTITY include SYSTEM "file:./header.xml"> |
| ]> |
| ]]></source> |
| |
| <p>Starting with Ant 1.6, there is a new |
| <code><import></code> task that can (also) be used to |
| include build file fragments. Unlike the snippets used with |
| entity includes, the referenced files have to be complete Ant |
| build files, though.</p> |
| |
| <p>The example above would become:</p> |
| <source><![CDATA[ |
| <?xml version="1.0"?> |
| <project name="test" default="test" basedir="."> |
| |
| <target name="setup"> |
| ... |
| </target> |
| |
| <import file="../common.xml"/> |
| |
| ... |
| |
| </project> |
| ]]></source> |
| |
| <p>Unlike entity includes, <code><import></code> will |
| let you use Ant properties in the file name.</p> |
| </answer> |
| </faq> |
| |
| <faq id="mail-logger"> |
| <question>How do I send an email with the result of my build |
| process?</question> |
| |
| <answer> |
| |
| <p>If you are using a nightly build of Ant 1.5 after |
| 2001-12-14, you can use the built-in MailLogger:</p> |
| |
| <source><![CDATA[ |
| ant -logger org.apache.tools.ant.listener.MailLogger |
| ]]></source> |
| |
| <p>See the <a href="http://cvs.apache.org/viewcvs/~checkout~/ant/docs/manual/listeners.html?content-type=text/html">Listeners |
| & Loggers</a> documentation for details on the properties |
| required.</p> |
| |
| <p>For older versions of Ant, you can use a custom |
| BuildListener that sends out an email |
| in the buildFinished() method. Will Glozer |
| <will.glozer@jda.com> has written such a listener based |
| on <a href="http://java.sun.com/products/javamail/">JavaMail</a>. |
| The source is:</p> |
| |
| <source><![CDATA[ |
| import java.io.*; |
| import java.util.*; |
| import javax.mail.*; |
| import javax.mail.internet.*; |
| import org.apache.tools.ant.*; |
| |
| /** |
| * A simple listener that waits for a build to finish and sends an email |
| * of the results. The settings are stored in "monitor.properties" and |
| * are fairly self explanatory. |
| * |
| * @author Will Glozer |
| * @version 1.05a 09/06/2000 |
| */ |
| public class BuildMonitor implements BuildListener { |
| protected Properties props; |
| |
| /** |
| * Create a new BuildMonitor. |
| */ |
| public BuildMonitor() throws Exception { |
| props = new Properties(); |
| InputStream is = getClass().getResourceAsStream("monitor.properties"); |
| props.load(is); |
| is.close(); |
| } |
| |
| public void buildStarted(BuildEvent e) { |
| } |
| |
| /** |
| * Determine the status of the build and the actions to follow, now that |
| * the build has completed. |
| * |
| * @param e Event describing the build status. |
| */ |
| public void buildFinished(BuildEvent e) { |
| Throwable th = e.getException(); |
| String status = (th != null) ? "failed" : "succeeded"; |
| |
| try { |
| String key = "build." + status; |
| if (props.getProperty(key + ".notify").equalsIgnoreCase("false")) { |
| return; |
| } |
| |
| Session session = Session.getDefaultInstance(props, null); |
| |
| MimeMessage message = new MimeMessage(session); |
| message.addRecipients(Message.RecipientType.TO, parseAddresses( |
| props.getProperty(key + ".email.to"))); |
| message.setSubject(props.getProperty(key + ".email.subject")); |
| |
| BufferedReader br = new BufferedReader(new FileReader( |
| props.getProperty("build.log"))); |
| StringWriter sw = new StringWriter(); |
| |
| String line = br.readLine(); |
| while (line != null) { |
| sw.write(line); |
| sw.write("\n"); |
| line = br.readLine(); |
| } |
| br.close(); |
| |
| message.setText(sw.toString(), "UTF-8"); |
| sw.close(); |
| |
| Transport transport = session.getTransport(); |
| transport.connect(); |
| transport.send(message); |
| transport.close(); |
| } catch (Exception ex) { |
| System.out.println("BuildMonitor failed to send email!"); |
| ex.printStackTrace(); |
| } |
| } |
| |
| /** |
| * Parse a comma separated list of internet email addresses. |
| * |
| * @param s The list of addresses. |
| * @return Array of Addresses. |
| */ |
| protected Address[] parseAddresses(String s) throws Exception { |
| StringTokenizer st = new StringTokenizer(s, ","); |
| Address[] addrs = new Address[st.countTokens()]; |
| |
| for (int i = 0; i < addrs.length; i++) { |
| addrs[i] = new InternetAddress(st.nextToken()); |
| } |
| return addrs; |
| } |
| |
| public void messageLogged(BuildEvent e) { |
| } |
| |
| public void targetStarted(BuildEvent e) { |
| } |
| |
| public void targetFinished(BuildEvent e) { |
| } |
| |
| public void taskStarted(BuildEvent e) { |
| } |
| |
| public void taskFinished(BuildEvent e) { |
| } |
| } |
| ]]></source> |
| |
| <p>With a <code>monitor.properties</code> like this:</p> |
| |
| <source><![CDATA[ |
| # configuration for build monitor |
| |
| mail.transport.protocol=smtp |
| mail.smtp.host=<host> |
| mail.from=Will Glozer <will.glozer@jda.com> |
| |
| build.log=build.log |
| |
| build.failed.notify=true |
| build.failed.email.to=will.glozer@jda.com |
| build.failed.email.subject=Nightly build failed! |
| |
| build.succeeded.notify=true |
| build.succeeded.email.to=will.glozer@jda.com |
| build.succeeded.email.subject=Nightly build succeeded! |
| ]]></source> |
| |
| <p><code>monitor.properties</code> should be placed right next |
| to your compiled <code>BuildMonitor.class</code>. To use it, |
| invoke Ant like:</p> |
| |
| <source><![CDATA[ |
| ant -listener BuildMonitor -logfile build.log |
| ]]></source> |
| |
| <p>Make sure that <code>mail.jar</code> from JavaMail and |
| <code>activation.jar</code> from the |
| <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">Java |
| Beans Activation Framework</a> are in your <code>CLASSPATH</code>.</p> |
| |
| </answer> |
| </faq> |
| |
| <faq id="listener-properties"> |
| <question>How do I get at the properties that Ant was running |
| with from inside BuildListener?</question> |
| |
| <answer> |
| <p>You can get at a hashtable with all the properties that Ant |
| has been using through the BuildEvent parameter. For |
| example:</p> |
| |
| <source><![CDATA[ |
| public void buildFinished(BuildEvent e) { |
| Hashtable table = e.getProject().getProperties(); |
| String buildpath = (String)table.get("build.path"); |
| ... |
| } |
| ]]></source> |
| |
| <p>This is more accurate than just reading the same property |
| files that your project does, since it will give the correct |
| results for properties that were specified on the Ant command line.</p> |
| </answer> |
| </faq> |
| |
| </faqsection> |
| |
| <faqsection title="Known Problems"> |
| <faq id="remove-cr"> |
| <question><chmod> or <exec> doesn't work in Ant |
| 1.3 on Unix</question> |
| <answer> |
| |
| <p>The <code>antRun</code> script in <code>ANT_HOME/bin</code> |
| has DOS instead of Unix line endings; you must remove the |
| carriage-return characters from this file. This can be done by |
| using Ant's <code><fixcrlf></code> task |
| or something like:</p> |
| |
| <source><![CDATA[ |
| tr -d '\r' < $ANT_HOME/bin/antRun > /tmp/foo |
| mv /tmp/foo $ANT_HOME/bin/antRun |
| ]]></source> |
| </answer> |
| </faq> |
| |
| <faq id="javadoc-cannot-execute"> |
| <question>JavaDoc failed: java.io.IOException: javadoc: cannot execute</question> |
| <answer> |
| <p>There is a bug in the Solaris reference implementation of |
| the JDK (see <a href="http://developer.java.sun.com/developer/bugParade/bugs/4230399.html">http://developer.java.sun.com/developer/bugParade/bugs/4230399.html</a>). |
| This also appears to be true under Linux. Moving the JDK to |
| the front of the PATH fixes the problem.</p> |
| </answer> |
| </faq> |
| |
| <faq id="delegating-classloader"> |
| <question><style> or <junit> ignores my |
| <classpath></question> |
| |
| <answer> |
| <p>These tasks don't ignore your classpath setting, you |
| are facing a common problem with delegating classloaders.</p> |
| |
| <p>First of all let's state that Ant adds all |
| <code>.jar</code> files from <code>ANT_HOME/lib</code> to |
| <code>CLASSPATH</code>, therefore "in |
| <code>CLASSPATH</code>" shall mean "either in your |
| <code>CLASSPATH</code> environment variable or |
| <code>ANT_HOME/lib</code>" for the rest of this |
| answer.</p> |
| |
| <p>Technically the sentence above isn't true for Ant 1.6 |
| and later anymore, but the result is the same. For the sake |
| of this discussion, <code>CLASSPATH</code> and |
| <code>ANT_HOME/lib</code> are identical.</p> |
| |
| <p>This question collects a common type of problem: A task |
| needs an external library and it has a nested classpath |
| element so that you can point it to this external library, but |
| that doesn't work unless you put the external library into the |
| <code>CLASSPATH</code>.</p> |
| |
| <p>The root of the problem is that the class that needs the |
| external library is on the <code>CLASSPATH</code>.</p> |
| |
| <p>When you specify a nested <code><classpath></code> in |
| Ant, Ant creates a new class loader that uses the path you |
| have specified. It then tries to load additional classes from |
| this classloader.</p> |
| |
| <p>In most cases - for example the two cases above - Ant |
| doesn't load the external library directly, it is the loaded |
| class that does so.</p> |
| |
| <p>In the case of <code><junit></code> it is the task |
| implementation itself and in the case of |
| <code><style></code> it is the implementation of the |
| <code>org.apache.tools.ant.taskdefs.XSLTLiaison</code> |
| class.</p> |
| |
| <p>Ant's class loader implementation uses Java's |
| delegation model, see <a |
| href="http://java.sun.com/products/jdk/1.2/docs/api/java/lang/ClassLoader.html">http://java.sun.com/products/jdk/1.2/docs/api/java/lang/ClassLoader.html</a> |
| the paragraph</p> |
| |
| <blockquote>The <code>ClassLoader</code> class uses a |
| delegation model to search for classes and resources. Each |
| instance of <code>ClassLoader</code> has an associated parent |
| class loader. When called upon to find a class or resource, a |
| <code>ClassLoader</code> instance will delegate the search for |
| the class or resource to its parent class loader before |
| attempting to find the class or resource itself. The virtual |
| machine's built-in class loader, called the bootstrap |
| class loader, does not itself have a parent but may serve as |
| the parent of a <code>ClassLoader</code> |
| instance.</blockquote> |
| |
| <p>This means, Ant's class loader will consult the |
| bootstrap class loader first, which tries to load classes from |
| <code>CLASSPATH</code>. The bootstrap class loader |
| doesn't know anything about Ant's class loader or |
| even the path you have specified.</p> |
| |
| <p>If the bootstrap class loader can load the class Ant has |
| asked it to load, this class will try to load the external |
| library from <code>CLASSPATH</code> as well - it doesn't |
| know anything else - and will not find it unless the library |
| is in <code>CLASSPATH</code> as well.</p> |
| |
| <p>To solve this, you have two major options:</p> |
| |
| <ol> |
| <li>put all external libraries you need in |
| <code>CLASSPATH</code> as well this is not what you want, |
| otherwise you wouldn't have found this FAQ entry.</li> |
| |
| <li>remove the class that loads the external library from |
| the <code>CLASSPATH</code>.</li> |
| </ol> |
| |
| <p><strong>Using The Second Option with Ant 1.5.4 and |
| Earlier:</strong></p> |
| |
| <p>The easiest way to do this is to remove |
| <code>optional.jar</code> from <code>ANT_HOME/lib</code>. If |
| you do so, you will have to <code><taskdef></code> all |
| optional tasks and use nested <code><classpath></code> |
| elements in the <code><taskdef></code> tasks that point |
| to the new location of <code>optional.jar</code>. Also, |
| don't forget to add the new location of |
| <code>optional.jar</code> to the |
| <code><classpath></code> of your |
| <code><style></code> or <code><junit></code> |
| task.</p> |
| |
| <p>If you want to avoid to <code><taskdef></code> all |
| optional tasks you need, the only other option is to remove |
| the classes that should not be loaded via the bootstrap class |
| loader from <code>optional.jar</code> and put them into a |
| separate archive. Add this separate archive to the |
| <code><classpath></code> of your |
| <code><style></code> or <code><junit></code> task |
| - and make sure the separate archive is not in |
| <code>CLASSPATH</code>.</p> |
| |
| <p>In the case of <code><junit></code> you'd have |
| to remove all classes that are in the |
| <code>org/apache/tools/ant/taskdefs/optional/junit</code> |
| directory, in the <code><style></code> case it is one of |
| the <code>*Liaison</code> classes in |
| <code>org/apache/tools/ant/taskdefs/optional</code>.</p> |
| |
| <p><strong>Using The Second Option with Ant 1.6 and |
| later:</strong></p> |
| |
| <p>In Ant 1.6 <code>optional.jar</code> has been split into |
| multiple jars, each one containing classes with the same |
| dependencies on external libraries. You can move the |
| "offending" jar out of ANT_HOME/lib. For the |
| <code><junit></code> task it would be |
| <code>ant-junit.jar</code> and for <code><style></code> |
| it would be <code>ant-trax.jar</code>, |
| <code>ant-xalan1.jar</code> or <code>ant-xslp.jar</code> - |
| depending on the processor you use.</p> |
| |
| <p>If you use the option to break up <code>optional.jar</code> |
| for <code><junit></code> or remove |
| <code>ant-junit.jar</code>, you still have to use a |
| <code><taskdef></code> with a nested |
| <code><classpath></code> to define the junit task.</p> |
| </answer> |
| </faq> |
| |
| <faq id="winxp-jdk14-ant14"> |
| <question>When running Ant 1.4 on Windows XP and JDK 1.4, I get |
| various errors when trying to <code><exec></code>, fork |
| <code><java></code> or access environment |
| variables.</question> |
| |
| <answer> |
| |
| <p>Ant < 1.5 doesn't recognize Windows XP as a flavor |
| of Windows that runs <code>CMD.EXE</code> instead of |
| <code>COMMAND.COM</code>. JDK 1.3 will tell Ant that Windows |
| XP is Windows 2000 so the problem doesn't show up |
| there.</p> |
| |
| <p>Apart from upgrading to Ant 1.5 or better, setting the |
| environment variable <code>ANT_OPTS</code> to |
| <code>-Dos.name=Windows_NT</code> prior to invoking Ant has |
| been confirmed as a workaround.</p> |
| </answer> |
| </faq> |
| |
| <faq id="1.5-cygwin-sh"> |
| <question>The <code>ant</code> wrapper script of Ant 1.5 fails |
| for Cygwin if <code>ANT_HOME</code> is set to a Windows style |
| path.</question> |
| <answer> |
| |
| <p>This problem has been reported only hours after Ant 1.5 has |
| been released, see <a |
| href="http://issues.apache.org/bugzilla/show_bug.cgi?id=10664">Bug |
| 10664</a> and all its duplicates.</p> |
| |
| <p>A fixed version of the wrapper script can be found <a |
| href="http://ant.apache.org/old-releases/v1.5/errata/">here</a>. |
| Simply replace your script with this version.</p> |
| </answer> |
| </faq> |
| |
| <faq id="1.5.2-zip-broken"> |
| <question><code><zip></code> is broken in Ant 1.5.2.</question> |
| <answer> |
| |
| <p>Yes, it is.</p> |
| |
| <p>The problem reported by most people - see <a |
| href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17648">Bug |
| 17648</a> and all its duplicates - is that Ant creates |
| archives that a partially unreadable by WinZIP. Luckily |
| <code>jar</code> deals with the archives and so the generated |
| jars/wars/ears will most likely work for you anyway.</p> |
| |
| <p>There are additional problems, see bugs <a |
| href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17780">Bug |
| 17780</a>, <a |
| href="http://issues.apache.org/bugzilla/show_bug.cgi?id=17871">Bug |
| 17871</a> and <a |
| href="http://issues.apache.org/bugzilla/show_bug.cgi?id=18403">Bug |
| 18403</a>. All of them are supposed to be fixed with Ant |
| 1.5.3 (and only 18403 should exist in 1.5.3beta1).</p> |
| </answer> |
| </faq> |
| |
| </faqsection> |
| |
| </document> |
