diff --git a/webpage/docs/antnews.html b/webpage/docs/antnews.html index c02e4d206..996aad335 100644 --- a/webpage/docs/antnews.html +++ b/webpage/docs/antnews.html @@ -46,6 +46,8 @@
  • Resources
  • Ant FAQ +
    • +
  • Having Problems?

    • Download

    diff --git a/webpage/docs/external.html b/webpage/docs/external.html index ed08a5208..6a16bf21a 100644 --- a/webpage/docs/external.html +++ b/webpage/docs/external.html @@ -44,6 +44,8 @@
  • Resources
  • Ant FAQ +
    • +
  • Having Problems?

    • Download

    diff --git a/webpage/docs/faq.html b/webpage/docs/faq.html index a130cfe0b..413a9b7a0 100644 --- a/webpage/docs/faq.html +++ b/webpage/docs/faq.html @@ -44,6 +44,8 @@
  • Resources
  • Ant FAQ +
    • +
  • Having Problems?

    • Download

    diff --git a/webpage/docs/index.html b/webpage/docs/index.html index 6f5441ac5..6122b4d3d 100644 --- a/webpage/docs/index.html +++ b/webpage/docs/index.html @@ -46,6 +46,8 @@
  • Resources
  • Ant FAQ +
    • +
  • Having Problems?

    • Download

    diff --git a/webpage/docs/logos.html b/webpage/docs/logos.html index dbb15e605..70b3f0e0c 100644 --- a/webpage/docs/logos.html +++ b/webpage/docs/logos.html @@ -44,6 +44,8 @@
  • Resources
  • Ant FAQ +
    • +
  • Having Problems?

    • Download

    diff --git a/webpage/docs/problems.html b/webpage/docs/problems.html new file mode 100644 index 000000000..34f1aab23 --- /dev/null +++ b/webpage/docs/problems.html @@ -0,0 +1,346 @@ + + + + + + + + + + + + + + The Jakarta Site - Having Problems? + + + + + + + + +
    + +
    + + + + + + + + + + + + +
    +
    +
    +

    Ant

    + +

    Download

    + +

    Jakarta

    + +

    Get Involved

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

    + + + +
    + + Read the Manual + +
    +
    +

    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 proviude the behaviour 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. +

    +
    +
    + + + +
    + + Examine Debug Output + +
    +
    +

    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

    + + This will produce something which starts like the following:

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

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

    +

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

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

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

    +
    +
    + + + +
    + + Has it been fixed? + +
    +
    +

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

    +
    +
    + + + +
    + + Has it been reported? + +
    +
    +

    + 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 it has, 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. +

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

    +
    +
    + + + +
    + + Fixing the Bug + +
    +
    +

    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 into the Bug + Database as described above, attaching the patch. Using the Bug database has the advantage of tracking + the progress of your bug. +

    +
    +
    +
    +
    +
    +
    +
    +
    + Copyright © 1999-2001, Apache Software Foundation +
    +
    + + + + + + + diff --git a/webpage/docs/resources.html b/webpage/docs/resources.html index a5abec054..3aadb47f1 100644 --- a/webpage/docs/resources.html +++ b/webpage/docs/resources.html @@ -44,6 +44,8 @@
  • Resources
  • Ant FAQ +
    • +
  • Having Problems?

    • Download

    diff --git a/webpage/xdocs/problems.xml b/webpage/xdocs/problems.xml new file mode 100644 index 000000000..591c9d356 --- /dev/null +++ b/webpage/xdocs/problems.xml @@ -0,0 +1,164 @@ + + + + + Conor MacNeill + 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. +

    + + +

    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 when you have a problem is to see 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:

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

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

    + +

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

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

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

    +     + + +

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

    +     + + +

    + 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 it has, 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. +

    +     + + +

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

    +     + + +

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

    +     + + +
    + + +     diff --git a/webpage/xdocs/stylesheets/project.xml b/webpage/xdocs/stylesheets/project.xml index ddc41ad8f..e330b5e6f 100644 --- a/webpage/xdocs/stylesheets/project.xml +++ b/webpage/xdocs/stylesheets/project.xml @@ -21,6 +21,8 @@ href="/resources.html"/> +