- If you are having problems with Ant, this page details some steps you can take
- to try and resolve the problem. If you can't resolve the problem then this page will help
- you collect some of the relevant information to provide a bug report. This information will help
- the Ant developers understand and resolve the problem. Of course, not all of the steps here will
- make sense for every problem you encounter. These are just some suggestions to
- point you in the right direction.
-
-
+ This page details some steps you can take to try and resolve
+ any problems you may be having with 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.
+
+
|
Read the Manual
@@ -111,16 +110,19 @@
|
- The first step to take when you have a problem is to read the
- manual entry for the task or concept that is giving you trouble. Check particularly the meaning of
- attributes and nested elements. Perhaps an attribute would provide the behavior you require. If you
- have problems with the manual, then you can submit a documentation bug report (see below) to help us
- improve the Ant documentation.
-
-
+ The first step to take when you have a problem with Ant is to read
+ the manual 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.
+
+
|
-
+
|
Examine Debug Output
@@ -128,14 +130,15 @@
|
- The first step when you have a problem is to see what Ant is doing. Try running Ant with
- The verbose flag
- ant -verbose
- or
- ant -v
+ 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 verbose flag:
+ ant -verbose
+ or
+ ant -v
- This will produce something which starts like the following:
-
+ This will produce output that starts like the following:
+
 |
@@ -144,24 +147,22 @@
|
-
-Ant version 1.4alpha compiled on August 6 2001
-Buildfile: build.xml
-Detected Java version: 1.3 in: f:\jdk1.3\jre
-Detected OS: Windows NT
-parsing buildfile \jakarta-ant\build.xml with
-URI = file:/jakarta-ant/build.xml
-Project base dir set to: \jakarta-ant
- [property] Loading \jakarta-ant\.ant.properties
- [property] Unable to find property file: \jakarta-ant\.ant.properties
- [property] Loading \conor\.ant.properties
- [property] Override ignored for debug
-
-prepare:
-
-check_for_optional_packages:
-...
- |
+
+
+Ant version 1.4.1 compiled on October 11 2001
+Buildfile: build.xml
+Detected Java version: 1.3 in: D:\usr\local\java\jdk13\jre
+Detected OS: Windows NT
+parsing buildfile D:\ant\build.xml
+with URI = file:D:/ant/build.xml
+Project base dir set to: D:\ant
+ [property] Loading Environment env.
+ [property] Loading D:\ant\conf.properties
+Build sequence for target 'debug' is [debug]
+Complete build sequence is [debug, gensrc, compile, jar, test]
+. . .
+
+ |
|
@@ -171,21 +172,31 @@ check_for_optional_packages:
-
- You may be able to see in this trace what ant is doing and why it takes a particular
- course of action. If you need even more information you can use the -debug
- flag rather than -verbose. This will generally produce so much output that
- you may want to save the output and analyze it in an editor.
+ 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
+ ‑debug flag rather than
+ ‑verbose.
+ 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
+ ‑logfile <filename> flag, or using
+ redirection.
- So, 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 will give you an idea of what is going on. For
- example, the <javac> task logs the reasons why it chooses to compile particular
- classes and the equivalent command it is using. The following trace (which has been edited
- and reformatted for clarity) shows javac adding one class but skipping another. This is followed
- by the compiler arguments and a summary of all the classes to be compiled.
+ 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 <javac> 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
+ <javac> 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.
-
+
|
@@ -194,24 +205,18 @@ check_for_optional_packages:
|
-
- [javac] org\apache\tools\ant\listener\Log4jListener.java added as
- \build\classes\org\apache\tools\ant\listener\Log4jListener.class
- is outdated.
- [javac] org\apache\tools\ant\Location.java omitted as
- \build\classes\org\apache\tools\ant\Location.class is up to date.
- ...
- [javac] Compiling 1 source file to \jakarta-ant\build\classes
- [javac] Using modern compiler
- [javac] Compilation args: -d \jakarta-ant\build\classes -classpath
- \jakarta-ant\build\classes;F:\jdk1.3\lib\tools.jar;
- \Ant\lib\optional.jar;\Ant\lib\log4j.jar;
- \Ant\lib\junit.jar;\Ant\lib\jaxp.jar;
- \Ant\lib\crimson.jar;\Ant\lib\ant.jar
- -sourcepath \jakarta-ant\src\main -g:none -O
- [javac] File to be compiled:
- \src\main\org\apache\tools\ant\listener\Log4jListener.java
- |
+
+
+[javac] Test.java omitted as D:\classes\Test.class is up to date.
+[javac] Unset.java added as D:\classes\Unset.class is outdated.
+[javac] Compiling 1 source file to D:\classes
+[javac] Using classic compiler
+[javac] Compilation args: -d D:\classes -classpath D:\classes;
+D:\jdk118\classes.zip; -sourcepath D:\src\java -g:none
+[javac] File to be compiled:
+ D:\src\java\Unset.java
+
+ |
|
@@ -221,19 +226,22 @@ check_for_optional_packages:
-
- 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 <javac> task above does. If
- you are having a problem, it is often useful to run the command directly in the same way Ant is doing
- and see if the problem persists. The problem may lie in the command being run by Ant, or 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.
+ 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 <javac> 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.
-
+
|
-
+
|
Has it been fixed?
@@ -241,23 +249,29 @@ check_for_optional_packages:
|
-
- After examining the debug output, you still believe that the problem you are having may be caused by Ant.
- Chances are that someone else may have already encountered this problem and perhaps it has been
- fixed. The next step, therefore, may be to try a nightly build of Ant to see if the
- problem has been fixed. Nightly builds for Ant are available from the
- Jakarta web site. While Ant nightly
- builds are typically quite stable and are used by
- Gump to build many other Jakarta projects, these builds should be treated as experimental. You can
- install and verify whether your problem has been fixed. Note that nightly builds do not build many of the
- optional tasks the come with Ant. A snapshot of these optional tasks is occasionally uploaded to the nightly
- download area. Note that even
- this snapshot does not contain every optional task.
+ 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, may be to try a nightly build
+ of Ant to see if the problem has been fixed. Nightly builds for Ant
+ are available from the
+
+ Jakarta web site. While Ant nightly builds are typically quite
+ stable and are used by
+ Gump
+ to build many other Jakarta projects, these builds should
+ nonetheless be treated as experimental. Note that nightly builds
+ do not build many of the optional tasks the come with Ant.
+ A snapshot of these optional tasks is occasionally uploaded to
+ the nightly download
+
+ area. However, even this snapshot does not contain every
+ optional task.
-
+
|
-
+
|
Has it been reported?
@@ -265,73 +279,94 @@ check_for_optional_packages:
|
-
- If the current nightly build doesn't resolve your problem, it is possible that someone else has reported
- the issue. It is time to look at the Apache Bug Database.
- This system is easy to use and it will let you search the
-
- currently open
- .
- and resolved bugs to see if your problem has already been reported.
- If your problem has been reported, you can see whether any of the developers have commented,
- suggesting workarounds or the reason for the bug, etc. You may have more information to add (see about
- creating bug reports below), in which case, go right ahead and add it. If you can't add more information
- you may just want to vote for this bug, and perhaps add yourself to the CC list to follow the progress of
- this bug.
-
-
+ If the current nightly build doesn't resolve your problem, it is
+ possible that someone else has reported the issue. It is time to
+ look at the
+ Apache Bug Database. This system is easy to use, and it will
+ let you search the
+ currently open and resolved bugs to see if your problem has
+ already been reported. If your problem has been reported, you can
+ see whether any of the developers have commented, suggesting
+ workarounds, or the reason for the bug, etc. Or you may have
+ information to add (see about creating and modifying bug reports
+ below), in which case, go right ahead and add the information.
+ If you don't have any additional information, you may just want
+ to vote for this bug, and perhaps
+ add yourself to the CC list to follow the progress
+ of this bug.
+
+
|
-
+
|
- Filing a Bug report
+ Filing a Bug Report
|
- By this time you may have decided that there is a bug in Ant. You have a few choices at this
- point. You can send an email to the ant-user mailing list to see if others have encountered your issue
- and how they may have worked around it. If after some discussion, you still feel you have a bug, it
- is time to create a bug report. This is a simple operation in the Bug Database. Please try to provide
- as much information as possible to assist the developers in resolving the bug. Please try to enter correct
- values for the various inputs when creating the bug. Once the bug is created you can add attachments to
- the bug report.
-
- What information should you include in your bug report? The easiest bugs to fix are those which are most
- easily reproducible, so if you can, it is really helpful to produce a small test case that exhibits the
- problem. In this case, you would attach the build file and other files necessary to reproduce the problem
- probably packed together in an archive. If you can't produce a test case, you should try to include a
- snippet from your build file and the relevant sections from the debug out from Ant. Try to include the
- header information where Ant states the version, the OS and VM information etc. As the debug output is
- likely to be very large, you should try to remove the output which is not relevant. Once the bug is
- entered into the Bug Database, you will be kept informed about progress on the bug. If you receive email
- asking for further information, please try to respond as it will aid in the resolution of your bug.
-
-
+ By this time, you may have decided that there is an unreported
+ bug in Ant. You have a few choices at this point. You can send
+ an email to the ant-user mailing list to see if
+ others have encountered your issue and find out how they may
+ have worked around it. If after some discussion, you feel it
+ is time to create
+ a bug report, this is a simple operation in the bug database.
+ Please try to provide as much information as possible in order
+ to assist the developers in resolving the bug. Please try to enter
+ correct values for the various inputs when creating the bug, such
+ as which version of Ant you are running, and on which platform,
+ etc. Once the bug is created, you can also add attachments to
+ the bug report.
+
+ What information should you include in your bug report? The
+ easiest bugs to fix are those that are most easily reproducible,
+ so it is really helpful if you can produce a small test case that
+ exhibits the problem. In this case, you would attach the build file
+ and any other files necessary to reproduce the problem, probably
+ packed together in an archive. If you can't produce a test case,
+ you should try to include a snippet from your build file and the
+ relevant sections from the verbose or debug output from Ant. Try
+ to include the header information where Ant states the version,
+ the OS and VM information, etc. As debug output is likely to be
+ very large, it's best to remove any output that is not
+ relevant. Once the bug is entered into the bug database, you
+ will be kept informed by email about progress on the bug. If
+ you receive email asking for further information, please try to
+ respond, as it will aid in the resolution of your bug.
+
+
|
-
+
|
- Asking for an enhancement
+ Asking for an Enhancement
|
- Sometimes, you may find that Ant just doesn't do what you want. It isn't a bug, as such, since Ant
- is working the way it is supposed to. Perhaps it is something that hasn't been thought of yet, or
- a completely new task. For these situations you will want to raise an enhancement request.
- Enhancement requests are managed using the same Apache Bug Database described above.
- These are just a different type of report. If you look in the database, you will see that one of
- the severity settings for a bug is "Enhancement". So, just fill the bug report in, and
- in the description, state how you would like to have Ant enhanced. Again you should check whether
- there are any existing enhancment requests that cover your needs. If so, just add your vote to these.
+ Sometimes, you may find that Ant just doesn't do what you need it
+ to. It isn't a bug, as such, since Ant is working the way it is
+ supposed to work. Perhaps it is some additional functionality for
+ a task that hasn't been thought of yet, or maybe a completely new
+ task. For these situations, you will
+ want to raise an enhancement request. Enhancement requests
+ are managed using the same Apache Bug Database described above.
+ These are just a different type of bug report. If you look in the
+ bug database, you will see that one of the severity settings for
+ a bug is "Enhancement". Just fill the bug report in,
+ set the severity of the bug to "Enhancement", and
+ state in the description how you would like to have Ant enhanced.
+ Again, you should first check whether there are any existing
+ enhancment requests that cover your needs. If so, just add your
+ vote to these.
-
+
|
-
+
|
Fixing the Bug
@@ -339,37 +374,56 @@ check_for_optional_packages:
|
- If you aren't satisfied just filing a bug report, you can try to find and fix the problem yourself. The
- best way to do that is by working against the latest code from CVS. Alternatively, you can work with the
- source code from the source distributions available on the Jakarta website. If you are going to tackle the
- issues at this level, you may want to discuss details on the ant-dev mailing list. Once you have a fix
- for the problem, you may either submit the patch to the ant-dev mailing list or enter into the Bug
- Database as described above, attaching the patch. Using the Bug database has the advantage of tracking
- the progress of your bug.
-
-
+ If you aren't satisfied with just filing a bug report, you can
+ try to find the cause of the problem and provide a fix yourself.
+ The best way to do that is by working with the latest code from CVS.
+ Alternatively, you can work with the source code available from the
+
+ source distributions. If you
+ are going to tackle the problem at this level, you may want to
+ discuss some details first on the ant-dev mailing
+ list. Once you have a fix for the problem, you may submit
+ the fix as a patch to either the ant-dev mailing
+ list, or enter the bug database as described above and attach the
+ patch to the bug report. Using the bug database has the advantage
+ of being able to track the progress of your patch.
+
+ If you have a patch to submit and are sending it to the
+ ant-dev mailing list, prefix "[PATCH]"
+ to your message subject. Please include any relevant bug numbers.
+ Patch files should be created with the ‑u
+ option of the
+ diff or cvs diff command. For
+ example:
+
+ diff -u Javac.java.orig Javac.java > javac.diffs
+
+ or, if you have source from CVS:
+
+ cvs diff -u Javac.java > javac.diffs
+
+ Note: You should give your patch files meaningful names.
+ This makes it easier for developers who need to apply a number
+ of different patch files.
+
|
-
+
-
-
+
|
|
-
- Copyright © 2000-2002, Apache Software Foundation
-
+
+ Copyright © 2000-2002, Apache Software Foundation
+
|
|
+ 
-