From 7eb48e1642540a16e744c2f0ffa4864a2ebea119 Mon Sep 17 00:00:00 2001 From: Diane Holt Date: Sat, 2 Mar 2002 02:49:05 +0000 Subject: [PATCH] Make it so the text can adjust to window width ('cause scrolling back&forth is a PITA :) (Also all the usual grammar/spelling/wording/etc. edits.) PR: Obtained from: Submitted by: Reviewed by: git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271663 13f79535-47bb-0310-9956-ffa450edef68 --- docs/problems.html | 390 ++++++++++++++++++++++++++------------------- 1 file changed, 222 insertions(+), 168 deletions(-) diff --git a/docs/problems.html b/docs/problems.html index 57bcbf681..b2e2e94cc 100644 --- a/docs/problems.html +++ b/docs/problems.html @@ -18,12 +18,9 @@ - -
- + + - Apache Ant -
@@ -91,19 +88,21 @@
- Having Problems? + Having problems?
-

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 @@ - + @@ -171,21 +172,31 @@ check_for_optional_packages: 
-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]
+. . .
+ +
-

- 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: - + @@ -221,19 +226,22 @@ 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
+ +
-

- 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 +
- - -