diff --git a/docs/faq.html b/docs/faq.html index eff31e819..db9402bf4 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -180,20 +180,24 @@ build file?
  • - How can I use Jikes specific command line + How can I use Jikes-specific command-line switches?
  • - How do I include a < character in my command line arguments? + How do I include a < character in my command-line arguments?
  • How do I redirect standard input or standard output in the <exec> task? +
    • +
  • + How do I execute a batch file or shell script from Ant?
  • - I've made a <delete> task to delete unwanted - sourcesafe control files (CVS files, editor backup files), but - it doesn't seem to work. The files never get deleted. What's + I've used a <delete> 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?
  • @@ -201,16 +205,16 @@ multiple conditions are true.
  • - I have a target I want to skip if a variable is set, - so I have unless="variable" as an attribute - of the target. The trouble is that all of the targets that this target + I have a target I want to skip if a property is set, + so I have unless="property" as an attribute + of the target, but all the targets this target depends on are still executed. Why?
  • - In my fileset, I've put in an + In my <fileset>, I've put in an <exclude> of all files followed by an <include> of just the files I want, but it - isn't giving me anything at all. What's wrong? + isn't giving me any files at all. What's wrong?
    • @@ -231,7 +235,7 @@
  • Why doesn't (X)Emacs/vi/MacOS X's project builder - parse the error messages generated by Ant correctly? + correctly parse the error messages generated by Ant?
    • @@ -240,7 +244,7 @@
    - Advanced issues + Advanced Issues
    @@ -268,14 +272,14 @@ @@ -394,13 +398,13 @@ @@ -417,25 +421,25 @@
    - Known problems + Known Problems
    -

    Ant is a Java based build tool. In theory it is kind of - like "make" without makes wrinkles and with the full +

    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.

    -

    According to Ant's original author James Duncan +

    According to Ant's original author, James Duncan Davidson, the name is an acronym for "Another Neat Tool".

    -

    Later explanations go along the lines of "Ants are - doing an extremely good job at building things" or - "Ants are very small and can carry a weight a dozen times - of their own" - describing what Ant is intended to +

    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.

    -

    Initially Ant was part of the Tomcat code base when it was - donated to the Apache Software Foundation - it has been - created by James Duncan Davidson, who also is the original +

    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.

    -

    Soon thereafter several open source Java projects realized - that Ant could solve the problems they had with makefiles. +

    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 now is the build + Apache project, Ant spread like a virus and is now the build tool of choice for a lot of projects.

    -

    In January 2000 Ant was moved to a separate CVS module and +

    In January 2000, Ant was moved to a separate CVS module and was promoted to a project of its own, independent of - Tomcat. Ant became Apache Ant.

    -

    The first version of Ant that was exposed a lager audience + Tomcat, and became Apache Ant.

    +

    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 referenced to as Ant + 2000. This version has later been referred to as Ant 0.3.1.

    -

    The first official release of Ant as a stand alone product was - Ant 1.1 released on 19 July 2000. The complete release +

    The first official release of Ant as a stand-alone product was + Ant 1.1, released on 19 July 2000. The complete release history:

    @@ -550,7 +554,7 @@ version of tar (for example, the one shipping with Solaris), you cannot use it to extract the archive.

    The solution is to either install GNU tar, which can be - found here + found here, or use the zip archive instead (you can extract it using jar xf).

    @@ -572,18 +576,26 @@ compares the timestamps of the source files to those of the resulting .class files. Opening all source files to find out which package they belong to would be very - inefficient - instead of this, Ant expects you to place your + 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 srcdir attribute.

    Say you have <javac srcdir="src" - destdir="dest" />. If Ant finds a file - src/a/b/C.java it expects it to be in package + destdir="dest"/>. If Ant finds a file + src/a/b/C.java, it expects it to be in package a.b so that the resulting .class file is going to be dest/a/b/C.class.

    -

    If your setup is different, 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.

    +

    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.

    +

    If you have Java source files that aren't declared to + be part of any package, you can still use the <javac> + task to compile these files correctly - just set the + srcdir and destdir attributes to + the actual directory the source + files live in and the directory the class files should go into, + respectively.

    @@ -600,11 +612,12 @@
    -

    Use properties: ant - -D<name>=<value> lets you define values for - properties. These can then be used within your build file as - any normal property: ${<name>} will put in - <value>.

    +

    Use properties. Using ant + -Dname=value 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: ${name} will put in + value.

    @@ -614,14 +627,14 @@
    - How can I use Jikes specific command line + How can I use Jikes-specific command-line switches?
    -

    A couple of switches are supported via magic +

    A couple of switches are supported via "magic" properties:

    @@ -708,8 +721,10 @@
    - only for Ant < 1.4, replaced by the nowarn - attribute of javac after that -nowarn + (Only for Ant < 1.4; replaced by the + nowarn + attribute of the <javac> + task after that.)
    -nowarn     		- How do I include a < character in my command line arguments? + How do I include a < character in my command-line arguments?
    -

    The short answer is "Use &lt;".

    -

    The long answer is, that this probably won't do what you - want anyway, see the next - section.

    +

    The short answer is "Use: &lt;".

    +

    The long answer is that this probably won't do what you + want anyway (see the next + section).

    @@ -763,7 +778,7 @@

    Say you want to redirect the standard input stream of the cat command to read from a file, something - like

    + like:

    @@ -810,7 +825,7 @@ shell-prompt> cat < foo
    -

    This will not do what you expect. The input-redirection is +

    This will not do what you expect. The input redirection is performed by your shell, not the command itself, so this should read:

    @@ -837,8 +852,78 @@ shell-prompt> cat < foo
    -

    Note, that you must use the value attribute of - <arg> in the last element.

    +

    Note that you must use the value attribute of + <arg> in the last element, in order to have + the command passed as a single, quoted argument. Alternatively, + you can use:

    +
    + + + + + + + + + + + + + + + + + 
    +<exec executable="/bin/sh">
+  <arg line='-c "cat &lt; foo"'/>
+</exec>
+
    +
    +

    Note the double-quotes nested inside the single-quotes.

    + + + + + + + +
    + + + How do I execute a batch file or shell script from Ant? + + +
    +
    +

    Execute the command shell instead, then pass the batch file or + shell script as a single command, using the /c or + -c switch, respectively. See + the above section + for example <exec> tasks + executing sh. On Windows, use something like:

    +
    + + + + + + + + + + + + + + + + + 
    +<exec dir="." executable="cmd.exe" os="Windows NT">
+  <arg line="/c test.bat"/>
+</exec>
+
    +
    @@ -848,17 +933,18 @@ shell-prompt> cat < foo - I've made a <delete> task to delete unwanted - sourcesafe control files (CVS files, editor backup files), but - it doesn't seem to work. The files never get deleted. What's + I've used a <delete> 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?
    -

    This is probably happening because by default, Ant excludes - SourceSafe control files (vssver.scc) and other +

    This is probably happening because, by default, Ant excludes + SourceSafe control files (vssver.scc) and certain other files from FileSets.

    Here's what you probably did:

    @@ -884,7 +970,8 @@ shell-prompt> cat < foo
    -

    You need to switch off the default exclusions and it will work:

    +

    You need to switch off the default exclusions, + and it will work:

    @@ -910,7 +997,7 @@ shell-prompt> cat < foo

    For a complete listing of the patterns that are excluded - by default, see the user + by default, see the user manual.

    @@ -930,16 +1017,16 @@ shell-prompt> cat < foo

    There are actually several answers to this question.

    If you have only one set and one unset property to test, - you can put both an if and an unless - attribute into the target. The target will act as if they + you can specify both an if and an unless + attribute for the target, and they will act as if they are "anded" together.

    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 wish to test for.

    -

    To see how this works, assume you have three properties, + to determine the specific state you want to test for.

    +

    To see how this works, assume you have three properties: prop1, prop2, and prop3. You want to test that prop1 and prop2 - are set, but that prop3 is not. If the condition + are set, and that prop3 is not. If the condition holds true you want to echo "yes".

    Here is the implementation in Ant 1.3 and earlier:

    @@ -975,9 +1062,13 @@ shell-prompt> cat < foo
    -

    Note that <antcall> tasks do not pass +

    Note: <antcall> tasks do not pass property changes back up to the environment they were called - from.

    + from, so you would'nt be able to, for example, set a + result property in the cond-if-3 target, + then do + <echo message="result is ${result}"/> + in the cond target.

    Starting with Ant 1.4, you can use the <condition> task.

    @@ -1030,9 +1121,10 @@ shell-prompt> cat < foo
  • To get a literal $ in Ant, you have to escape it with another $ - this will also break - the special treatment of the sequence ${.
    • + the special treatment of the ${ sequence. -

    This is neither readable, nor easy to understand, therefore +

    Because testing for a literal ${property} string + isn't all that readable or easy to understand, post-1.4.1 Ant introduces the <isset> element to the <condition> task.

    Here is the previous example done using @@ -1070,10 +1162,13 @@ shell-prompt> cat < foo

    The last option is to use a scripting language to set the properties. This can be particularly handy when you need much - better control than the simple conditions shown here, but of - course comes with the overhead of adding JAR files to support + 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.

    + two languages to implement a single system. See the + + <script> task documentation for more + details.

    @@ -1083,9 +1178,9 @@ shell-prompt> cat < foo - I have a target I want to skip if a variable is set, - so I have unless="variable" as an attribute - of the target. The trouble is that all of the targets that this target + I have a target I want to skip if a property is set, + so I have unless="property" as an attribute + of the target, but all the targets this target depends on are still executed. Why? @@ -1093,18 +1188,19 @@ shell-prompt> cat < foo

    The list of dependencies is generated by Ant before any of the - targets are run. This allows dependent targets such as an - init target to set properties that can control the - execution of the targets higher in the dependency graph. This - is a good thing.

    -

    When your dependencies actually break down the higher level task - into several simpler steps, though, this behaviour becomes - counterintuitive. There are a couple of solutions available: + targets are run. This allows dependent targets, such as an + init target, to set properties that can control the + execution of the targets higher in the dependency graph. This + is a good thing.

    +

    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:

    1. Put the same condition on each of the dependent targets.
      2. -
    2. Execute the steps using <antcall> +
    3. Execute the steps using <antcall>, instead of specifying them inside the depends attribute.
    @@ -1117,10 +1213,10 @@ shell-prompt> cat < foo - In my fileset, I've put in an + In my <fileset>, I've put in an <exclude> of all files followed by an <include> of just the files I want, but it - isn't giving me anything at all. What's wrong? + isn't giving me any files at all. What's wrong? @@ -1128,8 +1224,8 @@ shell-prompt> cat < foo

    The order of the <include> and - <exclude> tags within a fileset is ignored - when the fileset is created. Instead, all of the + <exclude> tags within a <fileset> + is ignored when the FileSet is created. Instead, all of the <include> elements are processed together, followed by all of the <exclude> elements. This means that the <exclude> @@ -1137,8 +1233,9 @@ shell-prompt> cat < foo <include> elements.

    To get the files you want, focus on just the <include> patterns that would be necessary - to get them. If you need to trim the list that the includes - would produce, use excludes.

    + to get them. If you find you need to trim the list that the + <include> elements + produce, then use <exclude> elements.

    @@ -1155,7 +1252,7 @@ shell-prompt> cat < foo

    See the section - on IDE integration on our external tools page.

    + on IDE integration on our External Tools and Tasks page.

    @@ -1166,18 +1263,18 @@ shell-prompt> cat < foo Why doesn't (X)Emacs/vi/MacOS X's project builder - parse the error messages generated by Ant correctly? + correctly parse the error messages generated by Ant?

    Ant adds a "banner" with the name of the current - task in front of all messages - and there are no built-in - regular expressions in your Editor that would account for + task in front of all logging messages - and there are no built-in + regular expressions in your editor that would account for this.

    You can disable this banner by invoking Ant with the - -emacs switch. Alternatively you can add the + -emacs switch. Alternatively, you can add the following snippet to your .emacs to make Emacs understand Ant's output.

    @@ -1285,9 +1382,9 @@ while(<STDIN>) { happen quite frequently - if your version of Ant contains the optional <test> and <junit> tasks, there are two XML - elements named test (the task and the nested child element - of <junit>) with different attribute - lists. This problem cannot be solved, DTDs don't give a + elements named test (the task and the nested child + element of <junit>) with different attribute + lists. This problem cannot be solved; DTDs don't give a syntax rich enough to support this.
    @@ -1386,8 +1483,8 @@ while(<STDIN>) {
    -

    If you are using a nightly-build of Ant 1.5 after - 2001-12-14, you can use the built-in MailLogger.

    +

    If you are using a nightly build of Ant 1.5 after + 2001-12-14, you can use the built-in MailLogger:

    @@ -1409,15 +1506,15 @@ while(<STDIN>) {
    -

    See the Listener - & Logger documentation for details on the properties +

    See the Listeners + & Loggers documentation for details on the properties required.

    -

    For older versions of Ant you can use a custom - BuildListener, that sends out an email +

    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 JavaMail, - the source is

    + on JavaMail. + The source is:

    @@ -1547,7 +1644,7 @@ public class BuildMonitor implements BuildListener {
    -

    With a monitor.properties like this

    +

    With a monitor.properties like this:

    @@ -1585,7 +1682,7 @@ build.succeeded.email.subject=Nightly build succeeded!

    monitor.properties should be placed right next to your compiled BuildMonitor.class. To use it, - invoke Ant like

    + invoke Ant like:

    @@ -1610,7 +1707,7 @@ ant -listener BuildMonitor -logfile build.log

    Make sure that mail.jar from JavaMail and activation.jar from the Java - Beans Activation Framework in your CLASSPATH.

    + Beans Activation Framework are in your CLASSPATH.

    @@ -1657,8 +1754,7 @@ public void buildFinished(BuildEvent e) {

    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 are specified on the command line - when running Ant.

    + results for properties that were specified on the Ant command line.

    @@ -1668,7 +1764,7 @@ public void buildFinished(BuildEvent e) { - <chmod> or <exec> don't work in Ant + <chmod> or <exec> doesn't work in Ant 1.3 on Unix @@ -1676,9 +1772,10 @@ public void buildFinished(BuildEvent e) {

    The antRun script in ANT_HOME/bin - 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 <fixcrlf> task or something like:

    + 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 <fixcrlf> task + or something like:

    @@ -1717,8 +1814,8 @@ mv /tmp/foo $ANT_HOME/bin/antRun diff --git a/xdocs/faq.xml b/xdocs/faq.xml index e92956c4f..6f233bcea 100644 --- a/xdocs/faq.xml +++ b/xdocs/faq.xml @@ -11,7 +11,7 @@ Where do I find the latest version of this document? -

    The latest version can always be found at Ant's homepage +

    The latest version can always be found at Ant's homepage http://jakarta.apache.org/ant/faq.html.

     @@ -22,10 +22,10 @@

    The page you are looking it is generated from this document. If you want to add a new question, please submit - a patch against this document to one of Ant's mailing lists, - the structure is hoped to be self-explaining.

    + a patch against this document to one of Ant's mailing lists; + hopefully, the structure is self-explanatory.

    -

    If you don't know how to create a patch, see the patches +

    If you don't know how to create a patch, see the patches section of this page.

    @@ -42,12 +42,12 @@

    The Velocity stylesheets used to process the XML files can be found in the xdocs/stylesheets subdirectory of - Ant's CVS repository - the build file docs.xml is + Ant's CVS repository - the build file docs.xml is used to drive Anakia. This file assumes that you have the jakarta-site2 module checked out from CVS as - well, but if you follow the instruction from Anakia's + 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.

    + sure all required jars are in the task's classpath.

    @@ -57,8 +57,8 @@ What is Apache Ant? -

    Ant is a Java based build tool. In theory it is kind of - like "make" without makes wrinkles and with the full +

    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.

         @@ -67,14 +67,14 @@ Why do you call it Ant? -

    According to Ant's original author James Duncan +

    According to Ant's original author, James Duncan Davidson, the name is an acronym for "Another Neat Tool".

    -

    Later explanations go along the lines of "Ants are - doing an extremely good job at building things" or - "Ants are very small and can carry a weight a dozen times - of their own" - describing what Ant is intended to +

    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.

     @@ -83,29 +83,29 @@ Tell us a little bit about Ant's history. -

    Initially Ant was part of the Tomcat code base when it was - donated to the Apache Software Foundation - it has been - created by James Duncan Davidson, who also is the original +

    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.

    -

    Soon thereafter several open source Java projects realized - that Ant could solve the problems they had with makefiles. +

    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 now is the build + Apache project, Ant spread like a virus and is now the build tool of choice for a lot of projects.

    -

    In January 2000 Ant was moved to a separate CVS module and +

    In January 2000, Ant was moved to a separate CVS module and was promoted to a project of its own, independent of - Tomcat. Ant became Apache Ant.

    + Tomcat, and became Apache Ant.

    -

    The first version of Ant that was exposed a lager audience +

    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 referenced to as Ant + 2000. This version has later been referred to as Ant 0.3.1.

    -

    The first official release of Ant as a stand alone product was - Ant 1.1 released on 19 July 2000. The complete release +

    The first official release of Ant as a stand-alone product was + Ant 1.1, released on 19 July 2000. The complete release history:

    There is a bug in the Solaris reference implementation of - the JDK, see http://developer.java.sun.com/developer/bugParade/bugs/4230399.html. - This also appears to be true under Linux, moving the JDK to + the JDK (see http://developer.java.sun.com/developer/bugParade/bugs/4230399.html). + This also appears to be true under Linux. Moving the JDK to the front of the PATH fixes the problem.

    @@ -162,7 +162,7 @@ you cannot use it to extract the archive.

    The solution is to either install GNU tar, which can be - found here + found here, or use the zip archive instead (you can extract it using jar xf).

    @@ -178,20 +178,29 @@ compares the timestamps of the source files to those of the resulting .class files. Opening all source files to find out which package they belong to would be very - inefficient - instead of this, Ant expects you to place your + 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 srcdir attribute.

    Say you have <javac srcdir="src" - destdir="dest" />. If Ant finds a file - src/a/b/C.java it expects it to be in package + destdir="dest"/>. If Ant finds a file + src/a/b/C.java, it expects it to be in package a.b so that the resulting .class file is going to be dest/a/b/C.class.

    -

    If your setup is different, 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.

    +

    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.

    + +

    If you have Java source files that aren't declared to + be part of any package, you can still use the <javac> + task to compile these files correctly - just set the + srcdir and destdir attributes to + the actual directory the source + files live in and the directory the class files should go into, + respectively.

    @@ -201,22 +210,23 @@ build file? -

    Use properties: ant - -D<name>=<value> lets you define values for - properties. These can then be used within your build file as - any normal property: ${<name>} will put in - <value>.

    +

    Use properties. Using ant + -Dname=value 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: ${name} will put in + value.

     - How can I use Jikes specific command line + How can I use Jikes-specific command-line switches? -

    A couple of switches are supported via magic +

    A couple of switches are supported via "magic" properties:

    @@ -245,8 +255,10 @@ - + @@ -257,13 +269,13 @@ - How do I include a < character in my command line arguments? + How do I include a < character in my command-line arguments? -

    The short answer is "Use &lt;".

    +

    The short answer is "Use: &lt;".

    -

    The long answer is, that this probably won't do what you - want anyway, see the next - section.

    +

    The long answer is that this probably won't do what you + want anyway (see the next + section).

         @@ -273,7 +285,7 @@

    Say you want to redirect the standard input stream of the cat command to read from a file, something - like

    + like:

    cat < foo @@ -288,7 +300,7 @@ shell-prompt> cat < foo ]]> -

    This will not do what you expect. The input-redirection is +

    This will not do what you expect. The input redirection is performed by your shell, not the command itself, so this should read:

    @@ -299,25 +311,54 @@ shell-prompt> cat < foo ]]> -

    Note, that you must use the value attribute of - <arg> in the last element.

    +

    Note that you must use the value attribute of + <arg> in the last element, in order to have + the command passed as a single, quoted argument. Alternatively, + you can use:

    + + + +]]> + +

    Note the double-quotes nested inside the single-quotes.

    + +     + + + + How do I execute a batch file or shell script from Ant? + + +

    Execute the command shell instead, then pass the batch file or + shell script as a single command, using the /c or + -c switch, respectively. See + the above section + for example <exec> tasks + executing sh. On Windows, use something like:

    + + + +]]>     - I've made a <delete> task to delete unwanted - sourcesafe control files (CVS files, editor backup files), but - it doesn't seem to work. The files never get deleted. What's + I've used a <delete> 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? -

    This is probably happening because by default, Ant excludes - SourceSafe control files (vssver.scc) and other +

    This is probably happening because, by default, Ant excludes + SourceSafe control files (vssver.scc) and certain other files from FileSets.

    -

    Here's what you probably did:

    +

    Here's what you probably did:

    cat < foo ]]> -

    You need to switch off the default exclusions and it will work:

    +

    You need to switch off the default exclusions, + and it will work:

    cat < foo ]]>

    For a complete listing of the patterns that are excluded - by default, see the user + by default, see the user manual.

     @@ -349,18 +391,18 @@ shell-prompt> cat < foo

    There are actually several answers to this question.

    If you have only one set and one unset property to test, - you can put both an if and an unless - attribute into the target. The target will act as if they + you can specify both an if and an unless + attribute for the target, and they will act as if they are "anded" together.

    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 wish to test for.

    + to determine the specific state you want to test for.

    -

    To see how this works, assume you have three properties, +

    To see how this works, assume you have three properties: prop1, prop2, and prop3. You want to test that prop1 and prop2 - are set, but that prop3 is not. If the condition + are set, and that prop3 is not. If the condition holds true you want to echo "yes".

    Here is the implementation in Ant 1.3 and earlier:

    @@ -381,9 +423,13 @@ shell-prompt> cat < foo ]]> -

    Note that <antcall> tasks do not pass +

    Note: <antcall> tasks do not pass property changes back up to the environment they were called - from.

    + from, so you would'nt be able to, for example, set a + result property in the cond-if-3 target, + then do + <echo message="result is ${result}"/> + in the cond target.

    Starting with Ant 1.4, you can use the <condition> task.

    @@ -422,10 +468,11 @@ shell-prompt> cat < foo
  • To get a literal $ in Ant, you have to escape it with another $ - this will also break - the special treatment of the sequence ${.
    • + the special treatment of the ${ sequence. -

    This is neither readable, nor easy to understand, therefore +

    Because testing for a literal ${property} string + isn't all that readable or easy to understand, post-1.4.1 Ant introduces the <isset> element to the <condition> task.

    @@ -448,35 +495,39 @@ shell-prompt> cat < foo

    The last option is to use a scripting language to set the properties. This can be particularly handy when you need much - better control than the simple conditions shown here, but of - course comes with the overhead of adding JAR files to support + 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.

    + two languages to implement a single system. See the + + <script> task documentation for more + details.

     - I have a target I want to skip if a variable is set, - so I have unless="variable" as an attribute - of the target. The trouble is that all of the targets that this target + I have a target I want to skip if a property is set, + so I have unless="property" as an attribute + of the target, but all the targets this target depends on are still executed. Why?

    The list of dependencies is generated by Ant before any of the - targets are run. This allows dependent targets such as an - init target to set properties that can control the - execution of the targets higher in the dependency graph. This - is a good thing.

    - -

    When your dependencies actually break down the higher level task - into several simpler steps, though, this behaviour becomes - counterintuitive. There are a couple of solutions available: + targets are run. This allows dependent targets, such as an + init target, to set properties that can control the + execution of the targets higher in the dependency graph. This + is a good thing.

    + +

    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:

    1. Put the same condition on each of the dependent targets.
      2. -
    2. Execute the steps using <antcall> +
    3. Execute the steps using <antcall>, instead of specifying them inside the depends attribute.
    @@ -485,16 +536,16 @@ shell-prompt> cat < foo     - In my fileset, I've put in an + In my <fileset>, I've put in an <exclude> of all files followed by an <include> of just the files I want, but it - isn't giving me anything at all. What's wrong? + isn't giving me any files at all. What's wrong?

    The order of the <include> and - <exclude> tags within a fileset is ignored - when the fileset is created. Instead, all of the + <exclude> tags within a <fileset> + is ignored when the FileSet is created. Instead, all of the <include> elements are processed together, followed by all of the <exclude> elements. This means that the <exclude> @@ -503,8 +554,9 @@ shell-prompt> cat < foo

    To get the files you want, focus on just the <include> patterns that would be necessary - to get them. If you need to trim the list that the includes - would produce, use excludes.

    + to get them. If you find you need to trim the list that the + <include> elements + produce, then use <exclude> elements.

         @@ -515,22 +567,22 @@ shell-prompt> cat < foo Is Ant supported by my IDE/Editor?

    See the section - on IDE integration on our external tools page.

    + on IDE integration on our External Tools and Tasks page.

     - Why doesn't (X)Emacs/vi/MacOS X's project builder - parse the error messages generated by Ant correctly? + Why doesn't (X)Emacs/vi/MacOS X's project builder + correctly parse the error messages generated by Ant?

    Ant adds a "banner" with the name of the current - task in front of all messages - and there are no built-in - regular expressions in your Editor that would account for + task in front of all logging messages - and there are no built-in + regular expressions in your editor that would account for this.

    You can disable this banner by invoking Ant with the - -emacs switch. Alternatively you can add the + -emacs switch. Alternatively, you can add the following snippet to your .emacs to make Emacs understand Ant's output.

    @@ -545,8 +597,8 @@ shell-prompt> cat < foo compilation-error-regexp-alist)) ]]> -

    Yet another alternative that preserves most of Ant's - formatting is to pipe Ant's output through the following Perl +

    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:

    ) {     - + Is there a DTD that I can use to validate my build files? @@ -602,9 +654,9 @@ while() { happen quite frequently - if your version of Ant contains the optional <test> and <junit> tasks, there are two XML - elements named test (the task and the nested child element - of <junit>) with different attribute - lists. This problem cannot be solved, DTDs don't give a + elements named test (the task and the nested child + element of <junit>) with different attribute + lists. This problem cannot be solved; DTDs don't give a syntax rich enough to support this. @@ -655,23 +707,23 @@ while() { -

    If you are using a nightly-build of Ant 1.5 after - 2001-12-14, you can use the built-in MailLogger.

    +

    If you are using a nightly build of Ant 1.5 after + 2001-12-14, you can use the built-in MailLogger:

    -

    See the Listener - & Logger documentation for details on the properties +

    See the Listeners + & Loggers documentation for details on the properties required.

    -

    For older versions of Ant you can use a custom - BuildListener, that sends out an email +

    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 JavaMail, - the source is

    + on JavaMail. + The source is:

    -

    With a monitor.properties like this

    +

    With a monitor.properties like this:

    monitor.properties should be placed right next to your compiled BuildMonitor.class. To use it, - invoke Ant like

    + invoke Ant like:

    Make sure that mail.jar from JavaMail and activation.jar from the Java - Beans Activation Framework in your CLASSPATH.

    + Beans Activation Framework are in your CLASSPATH.

         @@ -840,23 +892,23 @@ public void buildFinished(BuildEvent e) {

    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 are specified on the command line - when running Ant.

    + results for properties that were specified on the Ant command line.

     - + - <chmod> or <exec> don't work in Ant + <chmod> or <exec> doesn't work in Ant 1.3 on Unix

    The antRun script in ANT_HOME/bin - 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 <fixcrlf> task or something like:

    + 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 <fixcrlf> task + or something like:

    /tmp/foo @@ -869,8 +921,8 @@ mv /tmp/foo $ANT_HOME/bin/antRun JavaDoc failed: java.io.IOException: javadoc: cannot execute

    There is a bug in the Solaris reference implementation of - the JDK, see http://developer.java.sun.com/developer/bugParade/bugs/4230399.html. - This also appears to be true under Linux, moving the JDK to + the JDK (see http://developer.java.sun.com/developer/bugParade/bugs/4230399.html). + This also appears to be true under Linux. Moving the JDK to the front of the PATH fixes the problem.
    only for Ant < 1.4, replaced by the nowarn - attribute of javac after that -nowarn(Only for Ant < 1.4; replaced by the + nowarn + attribute of the <javac> + task after that.)

    -nowarn    		 build.compiler.warnings true == not set