| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <document> |
| |
| <properties> |
| <author email="">Conor MacNeill</author> |
| <title>Having Problems?</title> |
| </properties> |
| |
| <body> |
| <section name="Having Problems?"> |
| <p> |
| This page details some steps you can take to try and resolve |
| any problems you may be having with Apache Ant. If you find you can't |
| resolve the problem, then this page will help you collect some of |
| the relevant information to provide in a bug report. This information |
| will help the Ant developers understand and resolve the problem. |
| Of course, not all the steps here will make sense for every problem |
| you may encounter - these are just some suggestions to point |
| you in the right direction. |
| </p> |
| |
| <subsection name="Ensure that you are actually running the version of Ant that you think you do"> |
| <p>Many tools include a version of Ant and some Operating |
| Systems even install it by default now, so you may have a |
| version of Ant installed that you haven't been aware of.</p> |
| |
| <p>One of the first things to do is to run |
| <br></br><br></br> |
| <font face="verdana" size="-1">ant -version</font> |
| <br></br><br></br> |
| and |
| <br></br><br></br> |
| <font face="verdana" size="-1">ant -diagnostics</font> |
| <br></br><br></br> |
| to be sure. Also, we highly recommend that you run Ant with |
| an empty CLASSPATH. If any other version of Ant can be |
| loaded from the CLASSPATH, many types of errors may happen |
| because of incompatible classes being loaded.</p> |
| |
| <p>See <a href="faq.html">the FAQ</a> for <a |
| href="faq.html#NoClassDefFoundError">some</a> <a |
| href="faq.html#InstantiationException">examples</a>, but many |
| other problems are a result of an old version of Ant on your |
| system as well.</p> |
| |
| </subsection> |
| |
| <subsection name="Read the Manual"> |
| <p> |
| The first step to take when you have a problem with Ant is to read |
| the <a href="manual/index.html">manual</a> entry for the task or |
| concept that is giving you trouble. In particular, check the |
| meaning of a task's attributes and nested elements. Perhaps an |
| attribute is available that would provide the behavior you require. |
| If you have problems with the manual itself, you can submit a |
| documentation bug report (see below) to help us improve the Ant |
| documentation. |
| </p> |
| </subsection> |
| <subsection name="Examine Debug Output"> |
| <p> |
| If you're still having a problem, the next step is to try and |
| gather additional information about what Ant is doing. |
| Try running Ant with the <code>verbose</code> flag: |
| <br></br><br></br> |
| <font face="verdana" size="-1">ant -verbose</font> |
| <br></br><br></br> |
| or |
| <br></br><br></br> |
| <font face="verdana" size="-1">ant -v</font> |
| <br></br><br></br> |
| |
| This will produce output that starts like the following:</p> |
| <table> |
| <tr> |
| <td> |
| Ant version 1.4.1 compiled on October 11 2001<br></br> |
| Buildfile: build.xml<br></br> |
| Detected Java version: 1.3 in: D:\usr\local\java\jdk13\jre<br></br> |
| Detected OS: Windows NT<br></br> |
| parsing buildfile D:\ant\build.xml |
| with URI = file:D:/ant/build.xml<br></br> |
| Project base dir set to: D:\ant<br></br> |
|   [property] Loading Environment env.<br></br> |
|   [property] Loading D:\ant\conf.properties<br></br> |
| Build sequence for target 'debug' is [debug]<br></br> |
| Complete build sequence is [debug, gensrc, compile, jar, test]<br></br> |
| . . .<br></br> |
| </td> |
| </tr> |
| </table> |
| <p> |
| You should be able to see from the trace more about what Ant |
| is doing and why it's taking a particular course of action. |
| If you need even more information, you can use the |
| <code>-debug</code> flag rather than |
| <code>-verbose</code>. |
| This will generally produce so much |
| output that you may want to save the output to a file and |
| analyze it in an editor. You can save the output using the |
| <code>-logfile <filename></code> flag, or |
| using redirection. |
| </p> |
| <p> |
| Once you have all this debug information, how can you use it |
| to solve your problem? That will depend on the task in question |
| and the nature of your problem. Each task logs different aspects |
| of its operation, but it should give you an idea of what is going |
| on. For example, the <code><javac></code> task logs the |
| reasons why it |
| chooses to compile particular class files and not others, along |
| with which compiler it is using and the arguments it will pass |
| to that compiler. The following partial trace shows why |
| <code><javac></code> is adding one class file but |
| skipping another. |
| This is followed by which compiler it will be using, the |
| arguments that will get passed to the compiler, |
| and a list of all the class files to be compiled. |
| </p> |
| <table> |
| <tr> |
| <td> |
| [javac] Test.java omitted as D:\classes\Test.class is up to date.<br></br> |
| [javac] Unset.java added as D:\classes\Unset.class is outdated.<br></br> |
| [javac] Compiling 1 source file to D:\classes<br></br> |
| [javac] Using classic compiler<br></br> |
| [javac] Compilation args: -d D:\classes -classpath D:\classes;<br></br> |
| D:\jdk118\classes.zip; -sourcepath D:\src\java -g:none<br></br> |
| [javac] File to be compiled:<br></br> |
| D:\src\java\Unset.java<br></br> |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| In many cases, Ant tasks are wrappers around OS commands or |
| other Java classes. In debug mode, many of these tasks will |
| print out the equivalent command line, as the |
| <code><javac></code> task |
| output does. If you are having a problem, it is often useful to |
| run the command directly from the command line, in the same way |
| Ant is running it, and see if the problem occurs from there |
| as well. The problem may be in the command that is being run, |
| or it may be in the way the Ant task is running the command. |
| You can also see the effect of changing attribute values on the |
| generated command line. This can help you to understand whether |
| you are using the correct attributes and values. |
| </p> |
| </subsection> |
| |
| <subsection name="Has It Been Fixed?"> |
| <p> |
| After examining the debug output, if you still believe that the |
| problem you are having is caused by Ant, chances are that someone |
| else may have already encountered this problem, and perhaps it has |
| been fixed. The next step, therefore, would be to download the |
| sources of ant, see <a href="svn.html">svn</a>. |
| </p> |
| <p> |
| <a href="http://vmgump.apache.org/gump/public/index.html">Gump</a> |
| is building ant every night and using the ant built from the |
| latest source to build a long list of open source projects. However, |
| the version of ant built by gump is not available for download. Even |
| if it were, it would not include most of the optional tasks. |
| </p> |
| <p> |
| We currently do not have nightly builds including the optional tasks. |
| </p> |
| </subsection> |
| |
| |
| |
| </section> |
| <section name="bugs"> |
| <p>If you are convinced that you have identified an unfixed bug, please turn to |
| our document concerning the <a href="bugs.html">bug database</a>.</p> |
| </section> |
| |
| </body> |
| </document> |