Repository: ant Updated Branches: refs/heads/master f02565dbd -> 97d81a726
http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/tutorial-tasks-filesets-properties.html ---------------------------------------------------------------------- diff --git a/manual/tutorial-tasks-filesets-properties.html b/manual/tutorial-tasks-filesets-properties.html index ac9a80b..8df706f 100644 --- a/manual/tutorial-tasks-filesets-properties.html +++ b/manual/tutorial-tasks-filesets-properties.html @@ -322,8 +322,8 @@ the <code><path></code>. Filesets are easy if the files are all under a co the case, you have a problem. Another disadvantage is its speed: if you have only a few files in a huge directory structure, why not use a <code><filelist></code> instead? <code><path></code>s combines these datatypes in that way that a path contains other paths, filesets, dirsets and filelists. This is -why <a href="http://ant-contrib.sourceforge.net/";>Ant-Contrib [4]</a> <code><foreach></code> task is modified to -support paths instead of filesets. So we want that, too.</p> +why <a href="http://ant-contrib.sourceforge.net/"; target="_top">Ant-Contrib [4]</a> <code><foreach></code> task is +modified to support paths instead of filesets. So we want that, too.</p> <p>Changing from fileset to path support is very easy:</p> <em><strong>Change Java code from:</strong></em> @@ -659,8 +659,8 @@ After that it prints out the result (e.g. <samp>C:/ant-1.5.4/bin/ant.jar;C <li>create a patch file</li> <li>publishing that patch file</li> </ul> -<p>The <a href="https://ant.apache.org/ant_task_guidelines.html";>Ant Task Guidelines [6]</a> support additional -information on that.</p> +<p>The <a href="https://ant.apache.org/ant_task_guidelines.html"; target="_top">Ant Task Guidelines [6]</a> support +additional information on that.</p> <p>Now we will check the "Checklist before submitting a new task" described in that guideline.</p> <ul> @@ -762,7 +762,7 @@ after <code>git clone</code> (without our modifications).</p> <h3>Test on JDK 5</h3> <p>Ant 1.10 uses Java 8 for development, but Ant 1.9 is actively maintained, too. That means that Ant code must be able to run on a JDK 5. So we have to test that. You can download older JDKs -from <a href="https://www.oracle.com/technetwork/java/archive-139210.html";>Oracle [8]</a>.</p> +from <a href="https://www.oracle.com/technetwork/java/archive-139210.html"; target="_top">Oracle [8]</a>.</p> <p>Clean the <code>ANT_HOME</code> variable, delete the <samp>build</samp>, <samp>bootstrap</samp> and <samp>dist</samp> directories, and point <code>JAVA_HOME</code> to the JDK 5 home directory. Then create the patch with your commit, @@ -773,11 +773,11 @@ run <code>ant test</code> (like above).</p> <h3>Checkstyle</h3> <p>There are many things we have to ensure. Indentation with 4 spaces, blanks here and there, ... (all described in -the <a href="https://ant.apache.org/ant_task_guidelines.html";>Ant Task Guidelines [6]</a> which includes -the <a href="https://www.oracle.com/technetwork/java/codeconvtoc-136057.html";>Sun code style [9]</a>). Because there are -so many things we would be happy to have a tool for do the checks. There is one: checkstyle. Checkstyle is available -at <a href="http://checkstyle.sourceforge.net/";> Sourceforge [10]</a> and Ant provides with the <samp>check.xml</samp> a -buildfile which will do the job for us.</p> +the <a href="https://ant.apache.org/ant_task_guidelines.html"; target="_top">Ant Task Guidelines [6]</a> which includes +the <a href="https://www.oracle.com/technetwork/java/codeconvtoc-136057.html"; target="_top">Sun code style +[9]</a>). Because there are so many things we would be happy to have a tool for do the checks. There is one: +checkstyle. Checkstyle is available at <a href="http://checkstyle.sourceforge.net/"; target="_top">Sourceforge [10]</a> +and Ant provides with the <samp>check.xml</samp> a buildfile which will do the job for us.</p> <p>Download it and put the <samp>checkstyle-*-all.jar</samp> into your <samp>%USERPROFILE%\.ant\lib</samp> directory. All jar's stored there are available to Ant so you haven't to add it to you <samp>%ANT_HOME%\lib</samp> directory (this @@ -796,9 +796,9 @@ will find the next error place much more easier without redoing the checkstyle.< run. Now our task isn't listed. That's fine :-)</p> <h3>Publish the task</h3> -<p>Finally we publish that archive. As described in the <a href="https://ant.apache.org/ant_task_guidelines.html";>Ant -Task Guidelines [7]</a> we can announce it on the developer mailing list, create a BugZilla entry and open a GitHub pull -request. For both we need some information:</p> +<p>Finally we publish that archive. As described in the <a href="https://ant.apache.org/ant_task_guidelines.html"; +target="_top">Ant Task Guidelines [7]</a> we can announce it on the developer mailing list, create a BugZilla entry and +open a GitHub pull request. For both we need some information:</p> <table> <tr> @@ -826,13 +826,14 @@ request. For both we need some information:</p> more difficult. But the advantage is that entries will not be forgotten (a report is generated once every weekend). So I will describe the process.</p> -<p>First, you must have a BugZilla account. So open the <a href="https://issues.apache.org/bugzilla/";>BugZilla Main Page -[11]</a> and follow the link <a href="https://issues.apache.org/bugzilla/createaccount.cgi";>Open a new Bugzilla account -[12]</a> and the steps described there if you haven't one.</p> +<p>First, you must have a BugZilla account. So open the <a href="https://issues.apache.org/bugzilla/"; +target="_top">BugZilla Main Page [11]</a> and follow the +link <a href="https://issues.apache.org/bugzilla/createaccount.cgi"; target="_top">Open a new Bugzilla account [12]</a> +and the steps described there if you haven't one.</p> <ol> -<li>From the BugZilla main page choose <a href="https://issues.apache.org/bugzilla/enter_bug.cgi";>Enter a new bug report - [13]</a></li> +<li>From the BugZilla main page choose <a href="https://issues.apache.org/bugzilla/enter_bug.cgi"; target="_top">Enter a + new bug report [13]</a></li> <li>Choose "Ant" as product</li> <li>Version is the last "Alpha (nightly)" (at this time 1.10)</li> <li>Component is "Core tasks"</li> @@ -854,16 +855,21 @@ I will describe the process.</p> <li><a href="tutorial-writing-tasks.html">tutorial-writing-tasks.html</a></li> <li><a href="tutorial-tasks-filesets-properties.zip">tutorial-tasks-filesets-properties.zip</a></li> <li><a href="properties.html#built-in-props">properties.html#built-in-props</a></li> - <li><a href="http://ant-contrib.sourceforge.net/";>http://ant-contrib.sourceforge.net/</a></li> + <li><a href="http://ant-contrib.sourceforge.net/"; target="_top">http://ant-contrib.sourceforge.net/</a></li> <li><a href="Tasks/java.html">Tasks/java.html</a></li> - <li><a href="https://ant.apache.org/ant_task_guidelines.html";>https://ant.apache.org/ant_task_guidelines.html</a></li> - <li><a href="https://github.com/apache/ant";>https://github.com/apache/ant</a></li> - <li><a href="https://www.oracle.com/technetwork/java/archive-139210.html";>https://www.oracle.com/technetwork/java/archive-139210.html</a></li> - <li><a href="https://www.oracle.com/technetwork/java/codeconvtoc-136057.html";>https://www.oracle.com/technetwork/java/codeconvtoc-136057.html</a></li> - <li><a href="http://checkstyle.sourceforge.net/";>http://checkstyle.sourceforge.net/</a></li> - <li><a href="https://issues.apache.org/bugzilla/";>https://issues.apache.org/bugzilla/</a></li> - <li><a href="https://issues.apache.org/bugzilla/createaccount.cgi";>https://issues.apache.org/bugzilla/createaccount.cgi</a></li> - <li><a href="https://issues.apache.org/bugzilla/enter_bug.cgi";>https://issues.apache.org/bugzilla/enter_bug.cgi</a></li> + <li><a href="https://ant.apache.org/ant_task_guidelines.html"; + target="_top">https://ant.apache.org/ant_task_guidelines.html</a></li> + <li><a href="https://github.com/apache/ant"; target="_top">https://github.com/apache/ant</a></li> + <li><a href="https://www.oracle.com/technetwork/java/archive-139210.html"; + target="_top">https://www.oracle.com/technetwork/java/archive-139210.html</a></li> + <li><a href="https://www.oracle.com/technetwork/java/codeconvtoc-136057.html"; + target="_top">https://www.oracle.com/technetwork/java/codeconvtoc-136057.html</a></li> + <li><a href="http://checkstyle.sourceforge.net/"; target="_top">http://checkstyle.sourceforge.net/</a></li> + <li><a href="https://issues.apache.org/bugzilla/"; target="_top">https://issues.apache.org/bugzilla/</a></li> + <li><a href="https://issues.apache.org/bugzilla/createaccount.cgi"; + target="_top">https://issues.apache.org/bugzilla/createaccount.cgi</a></li> + <li><a href="https://issues.apache.org/bugzilla/enter_bug.cgi"; + target="_top">https://issues.apache.org/bugzilla/enter_bug.cgi</a></li> </ol> </body> http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/tutorial-writing-tasks.html ---------------------------------------------------------------------- diff --git a/manual/tutorial-writing-tasks.html b/manual/tutorial-writing-tasks.html index e14e32b..a1dee02 100644 --- a/manual/tutorial-writing-tasks.html +++ b/manual/tutorial-writing-tasks.html @@ -99,7 +99,7 @@ fail; <q>jar</q> requires the execution of some steps before. So the refactored </target> </project></pre> -<p><code>ant.project.name</code> is one of the <a href="properties.html#built-in-props" target="_blank">build-in +<p><code>ant.project.name</code> is one of the <a href="properties.html#built-in-props" target="_top">build-in properties [1]</a> of Ant.</p> <h2 id="write1">Write the Task</h2> @@ -117,7 +117,7 @@ attribute the <q>compile</q> is executed before).</p> <h2 id="use1">Use the Task</h2> <p>But after creating the jar we want to use our new Task. Therefore we need a new target <q>use</q>. Before we can use -our new task we have to declare it with <a href="Tasks/taskdef.html" target="_blank"><code><taskdef></code> +our new task we have to declare it with <a href="Tasks/taskdef.html" target="_top"><code><taskdef></code> [2]</a>. And for easier process we change the <var>default</var> attribute:</p> <pre class="code"> <?xml version="1.0" encoding="UTF-8"?> @@ -724,9 +724,8 @@ of your custom task. Then set breakpoints in other methods. This will ensure t JVM.</p> <h2 id="resources">Resources</h2> -<p>This tutorial and its resources are available -via <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=22570";>BugZilla [5]</a>. The ZIP provided there -contains</p> +<p>This tutorial and its resources are available via <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=22570"; +target="_top">BugZilla [5]</a>. The ZIP provided there contains</p> <ul> <li>this initial version of this tutorial</li> <li>the buildfile (last version)</li> @@ -746,7 +745,8 @@ the manual.</p> <li><a href="Tasks/taskdef.html">https://ant.apache.org/manual/Tasks/taskdef.html</a></li> <li><a href="develop.html#set-magic">https://ant.apache.org/manual/develop.html#set-magic</a></li> <li><a href="develop.html#nested-elements">https://ant.apache.org/manual/develop.html#nested-elements</a></li> -<li><a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=22570";>https://issues.apache.org/bugzilla/show_bug.cgi?id=22570</a></li> +<li><a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=22570"; + target="_top">https://issues.apache.org/bugzilla/show_bug.cgi?id=22570</a></li> <li><a href="tutorial-writing-tasks-src.zip">tutorial-writing-tasks-src.zip</a></li> </ol> http://git-wip-us.apache.org/repos/asf/ant/blob/97d81a72/manual/using.html ---------------------------------------------------------------------- diff --git a/manual/using.html b/manual/using.html index 7fde71f..e66ea2b 100644 --- a/manual/using.html +++ b/manual/using.html @@ -25,12 +25,10 @@ <body> <h1>Using Apache Ant</h1> <h2 id="buildfile">Writing a Simple Buildfile</h2> -<p>Apache Ant's buildfiles are written in XML. Each buildfile contains one project -and at least one (default) target. Targets contain task elements. -Each task element of the buildfile can have an <var>id</var> attribute and -can later be referred to by the value supplied to this. The value has -to be unique. (For additional information, see the -<a href="#tasks">Tasks</a> section below.)</p> +<p>Apache Ant's buildfiles are written in XML. Each buildfile contains one project and at least one (default) +target. Targets contain task elements. Each task element of the buildfile can have an <var>id</var> attribute and can +later be referred to by the value supplied to this. The value has to be unique. (For additional information, see +the <a href="#tasks">Tasks</a> section below.)</p> <h3 id="projects">Projects</h3> <p>A <em>project</em> has three attributes:</p> @@ -48,93 +46,69 @@ to be unique. (For additional information, see the <tr> <td>default</td> <td>the default target to use when no target is supplied.</td> - <td>No; however, <em>since Ant 1.6.0</em>, - every project includes an implicit target that contains any and - all top-level tasks and/or types. This target will always be - executed as part of the project's initialization, even when Ant is - run with the <a href="running.html#options"><code>-projecthelp</code></a> option. + <td>No; however, <em>since Ant 1.6.0</em>, every project includes an implicit target that contains any and all + top-level tasks and/or types. This target will always be executed as part of the project's initialization, even + when Ant is run with the <a href="running.html#options"><code>-projecthelp</code></a> option. </td> </tr> <tr> <td>basedir</td> - <td>the base directory from which all path calculations are - done. A relative path is resolved relative to the directory containing - the buildfile. + <td>the base directory from which all path calculations are done. A relative path is resolved relative to the + directory containing the buildfile. </td> - <td>No; defaults to the parent directory of the buildfile, - unless overridden by the project's <var>basedir</var> or the <code>basedir</code> - property</td> + <td>No; defaults to the parent directory of the buildfile, unless overridden by the project's <var>basedir</var> or + the <code>basedir</code> property</td> </tr> </table> -<p>Optionally, a description for the project can be provided as a -top-level <code><description></code> element (see the <a -href="Types/description.html">description</a> type).</p> +<p>Optionally, a description for the project can be provided as a top-level <code><description></code> element +(see the <a href="Types/description.html">description</a> type).</p> -<p>Each project defines one or more <em>targets</em>. -A target is a set of <em>tasks</em> you want -to be executed. When starting Ant, you can select which target(s) you -want to have executed. When no target is given, -the project's <var>default</var> is used.</p> +<p>Each project defines one or more <em>targets</em>. A target is a set of <em>tasks</em> you want to be executed. When +starting Ant, you can select which target(s) you want to have executed. When no target is given, the +project's <var>default</var> is used.</p> <h3 id="targets">Targets</h3> -<p>A target can depend on other targets. You might have a target for compiling, -for example, and a target for creating a distributable. You can only build a -distributable when you have compiled first, so the distribute target +<p>A target can depend on other targets. You might have a target for compiling, for example, and a target for creating a +distributable. You can only build a distributable when you have compiled first, so the distribute target <em>depends on</em> the compile target. Ant resolves these dependencies.</p> -<p>It should be noted, however, that Ant's <var>depends</var> attribute -only specifies the <em>order</em> in which targets should be executed—it -does not affect whether the target that specifies the dependency(s) gets -executed if the dependent target(s) did not (need to) run. -</p> +<p>It should be noted, however, that Ant's <var>depends</var> attribute only specifies the <em>order</em> in which +targets should be executed—it does not affect whether the target that specifies the dependency(s) gets executed if +the dependent target(s) did not (need to) run.</p> <p>More information can be found in the dedicated <a href="targets.html">manual page</a>.</p> <h3 id="tasks">Tasks</h3> <p>A task is a piece of code that can be executed.</p> -<p>A task can have multiple attributes (or arguments, if you prefer). The value -of an attribute might contain references to a property. These references will be -resolved before the task is executed.</p> +<p>A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references +to a property. These references will be resolved before the task is executed.</p> <p>Tasks have a common structure:</p> <pre><<i>name</i> <var>attribute1</var>="<i>value1</i>" <var>attribute2</var>="<i>value2</i>" ... /></pre> -<p>where <code><i>name</i></code> is the name of the task, -<var>attributeN</var> is the attribute name, and -<code><i>valueN</i></code> is the value for this attribute.</p> -<p>There is a set of <a href="tasklist.html" target="navFrame">built-in tasks</a>, but it is also very -easy to <a href="develop.html#writingowntask">write your own</a>.</p> -<p>All tasks can have a <var>name</var> attribute. The value of -this attribute will be used in the logging messages generated by -Ant.</p> -Tasks can be assigned an <var>id</var> attribute: +<p>where <code><i>name</i></code> is the name of the task, <var>attributeN</var> is the attribute name, +and <code><i>valueN</i></code> is the value for this attribute.</p> +<p>There is a set of <a href="tasklist.html" target="navFrame">built-in tasks</a>, but it is also very easy +to <a href="develop.html#writingowntask">write your own</a>.</p> +<p>All tasks can have a <var>name</var> attribute. The value of this attribute will be used in the logging messages +generated by Ant.</p> +<p>Tasks can be assigned an <var>id</var> attribute:</p> <pre><<i>taskname</i> <var>id</var>="<i>taskID</i>" ... /></pre> -where <code><i>taskname</i></code> is the name of the task, and <code><i>taskID</i></code> is -a unique identifier for this task. -You can refer to the -corresponding task object in scripts or other tasks via this name. -For example, in scripts you could do: +<p>where <code><i>taskname</i></code> is the name of the task, and <code><i>taskID</i></code> is a unique identifier for +this task. You can refer to the corresponding task object in scripts or other tasks via this name. For example, in +scripts you could do:</p> <pre> <script ... > task1.setFoo("bar"); </script></pre> - -to set the <code>foo</code> attribute of this particular task instance. -In another task (written in Java), you can access the instance via -<code>project.getReference("task1")</code>. -<p> -Note 1: If <q>task1</q> has not been run yet, then -it has not been configured (ie., no attributes have been set), and if it is -going to be configured later, anything you've done to the instance may -be overwritten. -</p> -<p> -Note 2: Future versions of Ant will most likely <em>not</em> -be backward-compatible with this behaviour, since there will likely be no -task instances at all, only proxies. -</p> +<p>to set the <code>foo</code> attribute of this particular task instance. In another task (written in Java), you can +access the instance via <code>project.getReference("task1")</code>.</p> +<p>Note 1: If <q>task1</q> has not been run yet, then it has not been configured (ie., no attributes have been set), and +if it is going to be configured later, anything you've done to the instance may be overwritten.</p> +<p>Note 2: Future versions of Ant will most likely <em>not</em> be backward-compatible with this behaviour, since there +will likely be no task instances at all, only proxies.</p> <h3 id="properties">Properties</h3> @@ -200,70 +174,49 @@ task instances at all, only proxies. </target> </project></pre> -<p>Notice that we are declaring properties outside any target. <em>Since - Ant 1.6</em>, all tasks can be declared outside targets (earlier version -only allowed <code><property></code>, <code><typedef></code> and -<code><taskdef></code>). When you do this they are evaluated before -any targets are executed. Some tasks will generate build failures if -they are used outside of targets as they may cause infinite loops -otherwise (<code><antcall></code> for example).</p> - -<p> -We have given some targets descriptions; this causes the <code>-projecthelp</code> -invocation option to list them as public targets with the descriptions; the -other target is internal and not listed. -<p> -Finally, for this target to work the source in the <samp>src</samp> subdirectory -should be stored in a directory tree which matches the package names. Check the -<code><javac></code> task for details. +<p>Notice that we are declaring properties outside any target. <em>Since Ant 1.6</em>, all tasks can be declared outside +targets (earlier version only allowed <code><property></code>, <code><typedef></code> +and <code><taskdef></code>). When you do this they are evaluated before any targets are executed. Some tasks +will generate build failures if they are used outside of targets as they may cause infinite loops otherwise +(<code><antcall></code> for example).</p> + +<p>We have given some targets descriptions; this causes the <code>-projecthelp</code> invocation option to list them as +public targets with the descriptions; the other target is internal and not listed.</p> +<p>Finally, for this target to work the source in the <samp>src</samp> subdirectory should be stored in a directory tree +which matches the package names. Check the <code><javac></code> task for details.</p> <h3 id="filters">Token Filters</h3> -<p>A project can have a set of tokens that might be automatically expanded if -found when a file is copied, when the filtering-copy behavior is selected in the -tasks that support this. These might be set in the buildfile -by the <a href="Tasks/filter.html">filter</a> task.</p> -<p>Since this can potentially be a very harmful behavior, -the tokens in the files <strong>must</strong> -be of the form <code>@<var>token</var>@</code>, where -<var>token</var> is the token name that is set -in the <code><filter></code> task. This token syntax matches the syntax of other build systems -that perform such filtering and remains sufficiently orthogonal to most -programming and scripting languages, as well as with documentation systems.</p> -<p><strong>Note</strong>: If a token with the format <code>@<var>token</var>@</code> -is found in a file, but no -filter is associated with that token, no changes take place; -therefore, no escaping -method is available—but as long as you choose appropriate names for your -tokens, this should not cause problems.</p> -<p><strong>Warning</strong>: If you copy binary files with filtering turned on, you can corrupt the -files. This feature should be used with text files <em>only</em>.</p> +<p>A project can have a set of tokens that might be automatically expanded if found when a file is copied, when the +filtering-copy behavior is selected in the tasks that support this. These might be set in the buildfile by +the <a href="Tasks/filter.html">filter</a> task.</p> +<p>Since this can potentially be a very harmful behavior, the tokens in the files <strong>must</strong> be of the +form <code>@<var>token</var>@</code>, where <var>token</var> is the token name that is set in +the <code><filter></code> task. This token syntax matches the syntax of other build systems that perform such +filtering and remains sufficiently orthogonal to most programming and scripting languages, as well as with documentation +systems.</p> +<p><strong>Note</strong>: If a token with the format <code>@<var>token</var>@</code> is found in a file, but no filter +is associated with that token, no changes take place; therefore, no escaping method is available—but as long as +you choose appropriate names for your tokens, this should not cause problems.</p> +<p><strong>Warning</strong>: If you copy binary files with filtering turned on, you can corrupt the files. This feature +should be used with text files <em>only</em>.</p> <h3 id="path">Path-like Structures</h3> -<p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type -references using both <q>:</q> and <q>;</q> as separator -characters. Ant will -convert the separator to the correct character of the current operating -system.</p> -<p>Wherever path-like values need to be specified, a nested element can -be used. This takes the general form of:</p> +<p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type references using both <q>:</q> and <q>;</q> as +separator characters. Ant will convert the separator to the correct character of the current operating system.</p> +<p>Wherever path-like values need to be specified, a nested element can be used. This takes the general form of:</p> <pre> <classpath> <pathelement path="${classpath}"/> <pathelement location="lib/helper.jar"/> </classpath></pre> -<p>The <var>location</var> attribute specifies a single file or -directory relative to the project's base directory (or an absolute -filename), while the <var>path</var> attribute accepts colon- -or semicolon-separated lists of locations. The <var>path</var> -attribute is intended to be used with predefined paths—in any other -case, multiple elements with <var>location</var> attributes should be -preferred.</p> -<p><em>Since Ant 1.8.2</em> the <var>location</var> attribute can also contain a - wildcard in its last path component (i.e. it can end in a - <q>*</q>) in order to support wildcard <code>CLASSPATH</code>s introduced - with Java 6. Ant will not expand or evaluate the wildcards and the - resulting path may not work as anything else but a <code>CLASSPATH</code>—or - even as a <code>CLASSPATH</code> for JVM prior to Java 6.</p> +<p>The <var>location</var> attribute specifies a single file or directory relative to the project's base directory (or +an absolute filename), while the <var>path</var> attribute accepts colon- or semicolon-separated lists of +locations. The <var>path</var> attribute is intended to be used with predefined paths—in any other case, multiple +elements with <var>location</var> attributes should be preferred.</p> +<p><em>Since Ant 1.8.2</em> the <var>location</var> attribute can also contain a wildcard in its last path component +(i.e. it can end in a <q>*</q>) in order to support wildcard <code>CLASSPATH</code>s introduced with Java 6. Ant will +not expand or evaluate the wildcards and the resulting path may not work as anything else but +a <code>CLASSPATH</code>—or even as a <code>CLASSPATH</code> for JVM prior to Java 6.</p> <p>As a shortcut, the <code><classpath></code> tag supports <var>path</var> and <var>location</var> attributes of its own, so:</p> @@ -274,16 +227,11 @@ supports <var>path</var> and </pre> <p>can be abbreviated to:</p> <pre><classpath path="${classpath}"/></pre> -<p>In addition, one or more -<a href="Types/resources.html#collection">resource collections</a> -can be specified as nested elements (these must consist of -<a href="Types/resources.html#file">file</a>-type resources only). -Additionally, it should be noted that although resource collections are -processed in the order encountered, certain resource collection types -such as <a href="Types/fileset.html">fileset</a>, -<a href="Types/dirset.html">dirset</a> and -<a href="Types/resources.html#files">files</a> -are undefined in terms of order.</p> +<p>In addition, one or more <a href="Types/resources.html#collection">resource collections</a> can be specified as +nested elements (these must consist of <a href="Types/resources.html#file">file</a>-type resources only). Additionally, +it should be noted that although resource collections are processed in the order encountered, certain resource +collection types such as <a href="Types/fileset.html">fileset</a>, <a href="Types/dirset.html">dirset</a> +and <a href="Types/resources.html#files">files</a> are undefined in terms of order.</p> <pre> <classpath> <pathelement path="${classpath}"/> @@ -297,33 +245,24 @@ are undefined in terms of order.</p> </dirset> <filelist refid="third-party_jars"/> </classpath></pre> -<p>This builds a path that holds the value of <samp>${classpath}</samp>, -followed by all jar files in the <samp>lib</samp> directory, -the <samp>classes</samp> directory, all directories named -<samp>classes</samp> under the <samp>apps</samp> subdirectory of -<samp>${build.dir}</samp>, except those -that have the text <code>Test</code> in their name, and -the files specified in the referenced FileList.</p> -<p>If you want to use the same path-like structure for several tasks, -you can define them with a <code><path></code> element at the -same level as <code><target></code>s, and reference them via their +<p>This builds a path that holds the value of <samp>${classpath}</samp>, followed by all jar files in +the <samp>lib</samp> directory, the <samp>classes</samp> directory, all directories named <samp>classes</samp> under +the <samp>apps</samp> subdirectory of <samp>${build.dir}</samp>, except those that have the text <code>Test</code> in +their name, and the files specified in the referenced FileList.</p> +<p>If you want to use the same path-like structure for several tasks, you can define them with +a <code><path></code> element at the same level as <code><target></code>s, and reference them via their <var>id</var> attribute—see <a href="#references">References</a> for an example.</p> -<p>By default a path-like structure will re-evaluate all nested - resource collections whenever it is used, which may lead to - unnecessary re-scanning of the filesystem. <em>Since Ant 1.8.0</em>, path has - an optional <var>cache</var> attribute, if it is set to <q>true</q>, the path - instance will only scan its nested resource collections once and - assume it doesn't change during the build anymore (the default - for <var>cache</var> still is <q>false</q>). Even if you are using the - path only in a single task it may improve overall performance to set - <var>cache</var> to <q>true</q> if you are using complex nested - constructs.</p> - -<p>A path-like structure can include a reference to another path-like -structure (a path being itself a resource collection) -via nested <code><path></code> elements:</p> +<p>By default a path-like structure will re-evaluate all nested resource collections whenever it is used, which may lead +to unnecessary re-scanning of the filesystem. <em>Since Ant 1.8.0</em>, path has an optional <var>cache</var> +attribute, if it is set to <q>true</q>, the path instance will only scan its nested resource collections once and assume +it doesn't change during the build anymore (the default for <var>cache</var> still is <q>false</q>). Even if you are +using the path only in a single task it may improve overall performance to set <var>cache</var> to <q>true</q> if you +are using complex nested constructs.</p> + +<p>A path-like structure can include a reference to another path-like structure (a path being itself a resource +collection) via nested <code><path></code> elements:</p> <pre> <path id="base.path"> <pathelement path="${classpath}"/> @@ -337,21 +276,18 @@ via nested <code><path></code> elements:</p> <path refid="base.path"/> <pathelement location="testclasses"/> </path></pre> - The shortcuts previously mentioned for <code><classpath></code> - are also valid for <code><path></code>. For example: +<p>The shortcuts previously mentioned for <code><classpath></code> are also valid +for <code><path></code>. For example:</p> <pre> <path id="base.path"> <pathelement path="${classpath}"/> </path></pre> -can be written as: +<p>can be written as:</p> <pre><path id="base.path" path="${classpath}"/></pre> <h4 id="pathshortcut">Path Shortcut</h4> -<p> - <em>Since Ant 1.6</em>, there is a shortcut for converting paths to OS specific - strings in properties. One can use the expression - <samp>${toString:<em>pathreference</em>}</samp> to convert a path element - reference to a string that can be used for a path argument. For example: -</p> +<p><em>Since Ant 1.6</em>, there is a shortcut for converting paths to OS specific strings in properties. One can use +the expression <samp>${toString:<em>pathreference</em>}</samp> to convert a path element reference to a string that can +be used for a path argument. For example:</p> <pre> <path id="lib.path.ref"> <fileset dir="lib" includes="*.jar"/> @@ -361,9 +297,8 @@ can be written as: </javac></pre> <h3 id="arg">Command-line Arguments</h3> -<p>Several tasks take arguments that will be passed to another -process on the command line. To make it easier to specify arguments -that contain space characters, nested <code>arg</code> elements can be used.</p> +<p>Several tasks take arguments that will be passed to another process on the command line. To make it easier to specify +arguments that contain space characters, nested <code>arg</code> elements can be used.</p> <table class="attr"> <tr> <th>Attribute</th> @@ -372,28 +307,23 @@ that contain space characters, nested <code>arg</code> elements can be used.</p> </tr> <tr> <td>value</td> - <td>a single command-line argument; can contain space - characters.</td> + <td>a single command-line argument; can contain space characters.</td> <td rowspan="5">Exactly one of these.</td> </tr> <tr> <td>file</td> - <td class="left">The name of a file as a single command-line - argument; will be replaced with the absolute filename of the file.</td> + <td class="left">The name of a file as a single command-line argument; will be replaced with the absolute filename + of the file.</td> </tr> <tr> <td>path</td> - <td class="left">A string that will be treated as a path-like - string as a single command-line argument; you can use <q>;</q> - or <q>:</q> as - path separators and Ant will convert it to the platform's local - conventions.</td> + <td class="left">A string that will be treated as a path-like string as a single command-line argument; you can + use <q>;</q> or <q>:</q> as path separators and Ant will convert it to the platform's local conventions.</td> </tr> <tr> <td>pathref</td> - <td class="left"><a href="#references">Reference</a> to a path - defined elsewhere. Ant will convert it to the platform's local - conventions.</td> + <td class="left"><a href="#references">Reference</a> to a path defined elsewhere. Ant will convert it to the + platform's local conventions.</td> </tr> <tr> <td>line</td> @@ -401,44 +331,38 @@ that contain space characters, nested <code>arg</code> elements can be used.</p> </tr> <tr> <td>prefix</td> - <td>A fixed string to be placed in front of the - argument. In the case of a line broken into parts, it will be - placed in front of every part. <em>Since Ant 1.8.</em></td> + <td>A fixed string to be placed in front of the argument. In the case of a line broken into parts, it will be placed + in front of every part. <em>Since Ant 1.8.</em></td> <td>No</td> </tr> <tr> <td>suffix</td> - <td>A fixed string to be placed immediately after the - argument. In the case of a line broken into parts, it will be + <td>A fixed string to be placed immediately after the argument. In the case of a line broken into parts, it will be placed after every part. <em>Since Ant 1.8.</em></td> <td>No</td> </tr> </table> -<p>It is highly recommended to avoid the <var>line</var> version -when possible. Ant will try to split the command line in a way -similar to what a (Unix) shell would do, but may create something that -is very different from what you expect under some circumstances.</p> +<p>It is highly recommended to avoid the <var>line</var> version when possible. Ant will try to split the command line +in a way similar to what a (Unix) shell would do, but may create something that is very different from what you expect +under some circumstances.</p> <h4>Examples</h4> <pre><arg value="-l -a"/></pre> -<p>is a single command-line argument containing a space character, -<em>not</em> separate options <q>-l</q> and <q>-a</q>.</p> +<p>is a single command-line argument containing a space character, <em>not</em> separate options <q>-l</q> +and <q>-a</q>.</p> <pre><arg line="-l -a"/></pre> <p>This is a command line with two separate options, <q>-l</q> and <q>-a</q>.</p> <pre><arg path="/dir;/dir2:\dir3"/></pre> -<p>is a single command-line argument with the value -<code>\dir;\dir2;\dir3</code> on DOS-based systems and -<code>/dir:/dir2:/dir3</code> on Unix(-like) systems.</p> +<p>is a single command-line argument with the value <code>\dir;\dir2;\dir3</code> on DOS-based systems +and <code>/dir:/dir2:/dir3</code> on Unix(-like) systems.</p> <h3 id="references">References</h3> -<p>Any project element can be assigned an identifier using its -<var>id</var> attribute. In most cases the element can subsequently -be referenced by specifying the <var>refid</var> attribute on an -element of the same type. This can be useful if you are going to -replicate the same snippet of XML over and over again—using a -<code><classpath></code> structure more than once, for example.</p> +<p>Any project element can be assigned an identifier using its <var>id</var> attribute. In most cases the element can +subsequently be referenced by specifying the <var>refid</var> attribute on an element of the same type. This can be +useful if you are going to replicate the same snippet of XML over and over again—using +a <code><classpath></code> structure more than once, for example.</p> <p>The following example:</p> <pre> <project ... > @@ -483,70 +407,56 @@ replicate the same snippet of XML over and over again—using a </javac> </target> </project></pre> -<p>All tasks that use nested elements for -<a href="Types/patternset.html">PatternSet</a>s, -<a href="Types/fileset.html">FileSet</a>s, -<a href="Types/zipfileset.html">ZipFileSet</a>s or -<a href="#path">path-like structures</a> accept references to these structures -as shown in the examples. Using <var>refid</var> on a task will ordinarily -have the same effect (referencing a task already declared), but the user -should be aware that the interpretation of this attribute is dependent on the -implementation of the element upon which it is specified. Some tasks (the -<a href="Tasks/property.html">property</a> task is a handy example) +<p>All tasks that use nested elements +for <a href="Types/patternset.html">PatternSet</a>s, <a href="Types/fileset.html">FileSet</a>s, <a href="Types/zipfileset.html">ZipFileSet</a>s +or <a href="#path">path-like structures</a> accept references to these structures as shown in the +examples. Using <var>refid</var> on a task will ordinarily have the same effect (referencing a task already declared), +but the user should be aware that the interpretation of this attribute is dependent on the implementation of the element +upon which it is specified. Some tasks (the <a href="Tasks/property.html">property</a> task is a handy example) deliberately assign a different meaning to <var>refid</var>.</p> <h3 id="external-tasks">Use of external tasks</h3> -Ant supports a plugin mechanism for using third party tasks. For using them you -have to do two steps: +<p>Ant supports a plugin mechanism for using third party tasks. For using them you have to do two steps:</p> <ol> <li>place their implementation somewhere where Ant can find them.</li> <li>declare them.</li> </ol> -Don't add anything to the <code>CLASSPATH</code> environment variable—this is often the -reason for very obscure errors. Use Ant's own <a href="install.html#optionalTasks">mechanisms</a> -for adding libraries: +<p>Don't add anything to the <code>CLASSPATH</code> environment variable—this is often the reason for very obscure +errors. Use Ant's own <a href="install.html#optionalTasks">mechanisms</a> for adding libraries:</p> <ul> <li>via command line argument <code>-lib</code></li> <li>adding to <code>${user.home}/.ant/lib</code></li> <li>adding to <code>${ant.home}/lib</code></li> </ul> -For the declaration there are several ways: +<p>For the declaration there are several ways:</p> <ul> <li>declare a single task per using instruction using - <code><<a href="Tasks/taskdef.html">taskdef</a> name="taskname" - classname="ImplementationClass"/></code> - <br/> - <code><taskdef name="for" classname="net.sf.antcontrib.logic.For"/> - <for ... /></code> + <code><<a href="Tasks/taskdef.html">taskdef</a> name="taskname" + classname="ImplementationClass"/></code><br/> + <code><taskdef name="for" classname="net.sf.antcontrib.logic.For"/> <for + ... /></code> </li> - <li>declare a bundle of tasks using a <samp>properties</samp> file holding these - taskname-ImplementationClass-pairs and <code><taskdef></code> - <br/> - <code><taskdef resource="net/sf/antcontrib/antcontrib.properties"/> - <for ... /></code> + <li>declare a bundle of tasks using a <samp>properties</samp> file holding these taskname–ImplementationClass + pairs and <code><taskdef></code><br/> + <code><taskdef resource="net/sf/antcontrib/antcontrib.properties"/> <for ... /></code> </li> - <li>declare a bundle of tasks using - an <a href="Types/antlib.html">xml file</a> holding these - taskname-ImplementationClass-pairs and <code><taskdef></code> - <br/> - <code><taskdef resource="net/sf/antcontrib/antlib.xml"/> - <for ... /></code> + <li>declare a bundle of tasks using an <a href="Types/antlib.html">xml file</a> holding these + taskname-ImplementationClass-pairs and <code><taskdef></code><br/> + <code><taskdef resource="net/sf/antcontrib/antlib.xml"/> <for ... /></code> </li> - <li>declare a bundle of tasks using an xml file named <samp>antlib.xml</samp>, XML namespace and - <a href="Types/antlib.html#antlibnamespace"><code>antlib:</code> protocol handler</a> - <br/> - <code><project xmlns:ac="antlib:net.sf.antcontrib"/> - <ac:for ... /></code> + <li>declare a bundle of tasks using an xml file named <samp>antlib.xml</samp>, XML namespace + and <a href="Types/antlib.html#antlibnamespace"><code>antlib:</code> protocol handler</a><br/> + <code><project xmlns:ac="antlib:net.sf.antcontrib"/> <ac:for ... /></code> </li> </ul> If you need a special function, you should <ol> <li>have a look at this manual, because Ant provides lot of tasks</li> - <li>have a look at the external task page <a href="https://ant.apache.org/external.html";>online</a></li> - <li>have a look at the external task <a href="https://wiki.apache.org/ant/AntExternalTaskdefs";>wiki - page</a></li> - <li>ask on the <a href="https://ant.apache.org/mail.html#User%20List";>Ant user</a> list</li> + <li>have a look at the external task page <a href="https://ant.apache.org/external.html"; target="_top">online</a></li> + <li>have a look at the external task <a href="https://wiki.apache.org/ant/AntExternalTaskdefs"; target="_top">wiki + page</a></li> + <li>ask on the <a href="https://ant.apache.org/mail.html#User%20List"; target="_top">Ant user</a> list</li> <li><a href="tutorial-writing-tasks.html">implement</a> (and share) your own</li> </ol>
