From a19ffe6be853786986869909757a783ac182b520 Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Tue, 22 Dec 2009 05:31:20 +0000
Subject: [PATCH] add a manual page for targets and target-groups

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@893073 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/conceptstypeslist.html |   1 +
 docs/manual/targets.html           | 257 +++++++++++++++++++++++++++++
 docs/manual/using.html             | 130 +--------------
 docs/manual/usinglist.html         |   2 +-
 4 files changed, 261 insertions(+), 129 deletions(-)
 create mode 100644 docs/manual/targets.html
diff --git a/docs/manual/conceptstypeslist.html b/docs/manual/conceptstypeslist.html
index 738a42f10..54978e136 100644
--- a/docs/manual/conceptstypeslist.html
+++ b/docs/manual/conceptstypeslist.html
@@ -29,6 +29,7 @@
 
 <h3>Concepts</h3>
 <ul class="inlinelist">
+<li><a href="targets.html">Targets and Target-Groups</a></li>
 <li><a href="properties.html">Properties and PropertyHelpers</a></li>
 <li><a href="clonevm.html">ant.build.clonevm</a></li>
 <li><a href="sysclasspath.html">build.sysclasspath</a></li>
diff --git a/docs/manual/targets.html b/docs/manual/targets.html
new file mode 100644
index 000000000..fc109c651
--- /dev/null
+++ b/docs/manual/targets.html
@@ -0,0 +1,257 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<html>
+
+<head>
+  <meta http-equiv="Content-Language" content="en-us"/>
+  <link rel="stylesheet" type="text/css" href="stylesheets/style.css"/>
+  <title>Targets and Target-Groups</title>
+</head>
+
+<body>
+  <h1><a name="targets">Targets</a></h1>
+
+  <p>A target is a container of tasks that cooperate to reach a
+    desired state during the build process.</p>
+
+  <p>Targets can depend on other targets and Ant ensures that these
+    other targets have been executed before the current target.  For
+    example 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 <i>depends on</i> the compile target.</p>
+
+  <p>Ant tries to execute the targets in the <code>depends</code>
+    attribute in the order they appear (from left to right). Keep in
+    mind that it is possible that a target can get executed earlier
+    when an earlier target depends on it:</p>
+
+<blockquote>
+<pre>&lt;target name=&quot;A&quot;/&gt;
+&lt;target name=&quot;B&quot; depends=&quot;A&quot;/&gt;
+&lt;target name=&quot;C&quot; depends=&quot;B&quot;/&gt;
+&lt;target name=&quot;D&quot; depends=&quot;C,B,A&quot;/&gt;</pre>
+</blockquote>
+
+  <p>Suppose we want to execute target D. From its
+    <code>depends</code> attribute, you might think that first target
+    C, then B and then A is executed.  Wrong! C depends on B, and B
+    depends on A, so first A is executed, then B, then C, and finally
+    D.</p>
+
+  <p>In a chain of dependencies stretching back from a given target
+    such as D above, each target gets executed only once, even when
+    more than one target depends on it. Thus, executing the D target
+    will first result in C being called, which in turn will first call
+    B, which in turn will first call A. After A, then B, then C have
+    executed, execution returns to the dependency list of D, which
+    will <u>not</u> call B and A, since they were already called in
+    process of dependency resolution for C and B respectively as
+    dependencies of D. Had no such dependencies been discovered in
+    processing C and B, B and A would have been executed after C in
+    processing D's dependency list.</p>
+
+  <p>A target also has the ability to perform its execution if (or
+    unless) a property has been set. This allows, for example, better
+    control on the building process depending on the state of the
+    system (java version, OS, command-line property defines, etc.).
+    To make a target <i>sense</i> this property, you should add
+    the <code>if</code> (or <code>unless</code>) attribute with the
+    name of the property that the target should react
+    to. <strong>Note:</strong> In the most simple case Ant will only
+    check whether the property has been set, the value doesn't matter,
+    but using property expansions you can build more complex
+    conditions.  See
+    <a href="properties.html#if+unless">the properties page</a> for
+    more details.  For example:</p>
+
+<blockquote>
+  <pre>&lt;target name=&quot;build-module-A&quot; if=&quot;module-A-present&quot;/&gt;</pre>
+  <pre>&lt;target name=&quot;build-own-fake-module-A&quot; unless=&quot;module-A-present&quot;/&gt;</pre>
+</blockquote>
+
+  <p>In the first example, if the <code>module-A-present</code>
+    property is set (to any value, e.g. <i>false</i>), the target will
+    be run. In the second example, if
+    the <code>module-A-present</code> property is set (again, to any
+    value), the target will not be run.</p>
+
+  <p>Only one propertyname can be specified in the if/unless
+    clause. If you want to check multiple conditions, you can use a
+    dependend target for computing the result for the check:</p>
+
+<blockquote><pre>
+&lt;target name="myTarget" depends="myTarget.check" if="myTarget.run"&gt;
+    &lt;echo&gt;Files foo.txt and bar.txt are present.&lt;/echo&gt;
+&lt/target&gt;
+
+&lt;target name="myTarget.check"&gt;
+    &lt;condition property="myTarget.run"&gt;
+        &lt;and&gt;
+            &lt;available file="foo.txt"/&gt;
+            &lt;available file="bar.txt"/&gt;
+        &lt;/and&gt;
+    &lt;/condition&gt;
+&lt/target&gt;
+</pre></blockquote>
+
+  <p>If no <code>if</code> and no <code>unless</code> attribute is
+    present, the target will always be executed.</p>
+
+  <p><b>Important:</b> the <code>if</code> and <code>unless</code>
+    attributes only enable or disable the target to which they are
+    attached. They do not control whether or not targets that a
+    conditional target depends upon get executed.  In fact, they do
+    not even get evaluated until the target is about to be executed,
+    and all its predecessors have already run.
+
+  <p>The optional <code>description</code> attribute can be used to
+    provide a one-line description of this target, which is printed by
+    the <code>-projecthelp</code> command-line option. Targets without
+    such a description are deemed internal and will not be listed,
+    unless either the <code>-verbose</code> or <code>-debug</code>
+    option is used.</p>
+
+  <p>It is a good practice to place
+    your <a href="CoreTasks/tstamp.html">tstamp</a> tasks in a
+    so-called <i>initialization</i> target, on which all other targets
+    depend. Make sure that target is always the first one in the
+    depends list of the other targets. In this manual, most
+    initialization targets have the
+    name <code>&quot;init&quot;</code>.</p>
+
+  <p>If the depends attribute and the if/unless attribute are set, the
+    depends attribute is executed first.</p>
+
+  <p>A target has the following attributes:</p>
+
+  <table border="1" cellpadding="2" cellspacing="0">
+    <tr>
+      <td valign="top"><b>Attribute</b></td>
+      <td valign="top"><b>Description</b></td>
+      <td align="center" valign="top"><b>Required</b></td>
+    </tr>
+    <tr>
+      <td valign="top">name</td>
+      <td valign="top">the name of the target.</td>
+      <td align="center" valign="top">Yes</td>
+    </tr>
+    <tr>
+      <td valign="top">depends</td>
+      <td valign="top">a comma-separated list of names of targets on
+        which this target depends.</td>
+      <td align="center" valign="top">No</td>
+    </tr>
+    <tr>
+      <td valign="top">if</td>
+      <td valign="top">the name of the property that must be set in
+        order for this target to execute,
+        or <a href="properties.html#if+unless">something evaluating to
+          true</a>.</td>
+      <td align="center" valign="top">No</td>
+    </tr>
+    <tr>
+      <td valign="top">unless</td>
+      <td valign="top">the name of the property that must not be set
+        in order for this target to execute,
+        or <a href="properties.html#if+unless">something evaluating to
+        false</a>.</td>
+      <td align="center" valign="top">No</td>
+    </tr>
+    <tr>
+      <td valign="top">description</td>
+      <td valign="top">a short description of this target's function.</td>
+      <td align="center" valign="top">No</td>
+    </tr>
+    <tr>
+      <td valign="top">group</td>
+      <td valign="top">Adds the current target to the depends list of
+        the named <a href="#target-groups">target-group</a>.
+        <em>since Ant 1.8.0.</em></td>
+      <td align="center" valign="top">No</td>
+    </tr>
+  </table>
+
+  <p>A target name can be any alphanumeric string valid in the
+    encoding of the XML file. The empty string &quot;&quot; is in this
+    set, as is comma &quot;,&quot; and space &quot; &quot;.  Please
+    avoid using these, as they will not be supported in future Ant
+    versions because of all the confusion they cause. IDE support of
+    unusual target names, or any target name containing spaces, varies
+    with the IDE.</p>
+
+  <p>Targets beginning with a hyphen such
+    as <code>&quot;-restart&quot;</code> are valid, and can be used to
+    name targets that should not be called directly from the command
+    line.</p>
+
+  <h1><a name="target-groups">Target-Groups</a></h1>
+
+  <p><em>since Ant 1.8.0.</em></p>
+
+  <p>Target-Groups are similar to targets in that they have a name and
+    a depends list and can be executed from the command line.  Just
+    like targets they represent a state during the build process.</p>
+
+  <p>Unlike targets they don't contain any tasks, their main purpose
+    is to collect targets that contribute to the desired state in
+    their depends list.</p>
+
+  <p>Targets can add themselves to a target-group's depends list via
+    their group attribute.  The targets that add themselves will be
+    added after the targets of the explicit depends-attribute of the
+    target-group, if multiple targets add themselves, their relative
+    order is not defined.</p>
+
+  <p>The main purpose of a target-group is to act as an extension
+    point for build files designed to
+    be <a href="CoreTasks\import.html">imported</a>.  In the imported
+    file a target-groups defines a state that must be reached and
+    targets from other build files can join the depends list of said
+    target-group in order to contribute to that state.</p>
+
+  <p>For example your imported build file may need to compile code, it
+    might look like:</p>
+<blockquote><pre>
+&lt;target name="create-directory-layout"&gt;
+   ...
+&lt;/target&gt;
+&lt;target-group name="ready-to-compile"
+              depends="create-directory-layout"/&gt;
+&lt;target name="compile" depends="ready-to-compile"&gt;
+   ...
+&lt;/target&gt;
+</pre></blockquote>
+
+  <p>And you need to generate some source before compilation, then in
+    your main build file you may use something like</p>
+<blockquote><pre>
+&lt;target name="generate-sources"
+        group="ready-to-compile"&gt;
+   ...
+&lt;/target&gt;
+</pre></blockquote>
+
+  <p>This will ensure that the <em>generate-sources</em> target is
+    executed before the <em>compile</em> target.</p>
+
+  <p>Don't rely on the order of the depends list,
+    if <em>generate-sources</em> depends
+    on <em>create-directory-layout</em> then it must explicitly depend
+    on it via its own depends attribute.</p>
+</body>
+</html>
diff --git a/docs/manual/using.html b/docs/manual/using.html
index 4cb91feb4..5bd4983de 100644
--- a/docs/manual/using.html
+++ b/docs/manual/using.html
@@ -85,135 +85,9 @@ only specifies the <i>order</i> 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>Ant tries to execute the targets in the <code>depends</code>
-attribute in the order
-they appear (from left to right). Keep in mind that it is possible that a target
-can get executed earlier when an earlier target depends on it:</p>
-<blockquote>
-<pre>&lt;target name=&quot;A&quot;/&gt;
-&lt;target name=&quot;B&quot; depends=&quot;A&quot;/&gt;
-&lt;target name=&quot;C&quot; depends=&quot;B&quot;/&gt;
-&lt;target name=&quot;D&quot; depends=&quot;C,B,A&quot;/&gt;</pre>
-</blockquote>
-<p>Suppose we want to execute target D. From its
-<code>depends</code> attribute, you
-might think that first target C, then B and then A is executed.
-Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.</p>
-<p>In a chain of dependencies stretching back from a given target such
-as D above, each target gets executed only once, even when more than
-one target depends on it. Thus, executing the D target will first
-result in C being called, which in turn will first call B, which in
-turn will first call A. After A, then B, then C have executed,
-execution returns to the dependency list of D, which will <u>not</u>
-call B and A, since they were already called in process of dependency
-resolution for C and B respectively as dependencies of D. Had no such
-dependencies been discovered in processing C and B, B and A would
-have been executed after C in processing D's dependency list.</p>
-<p>A target also has the ability to perform its execution if (or
-unless) a property has been set. This allows, for example, better
-control on the building process depending on the state of the system
-(java version, OS, command-line property defines, etc.).  To make a target
-<i>sense</i> this property, you should add the <code>if</code> (or
-<code>unless</code>) attribute with the name of the property that the target
-should react to. <strong>Note:</strong> Ant will only check whether
-the property has been set, the value doesn't matter.  A property set
-to the empty string is still an existing property.  For example:</p>
-<blockquote>
-  <pre>&lt;target name=&quot;build-module-A&quot; if=&quot;module-A-present&quot;/&gt;</pre>
-  <pre>&lt;target name=&quot;build-own-fake-module-A&quot; unless=&quot;module-A-present&quot;/&gt;</pre>
-</blockquote>
-<p>In the first example, if the <code>module-A-present</code>
-property is set (to any value, e.g. <i>false</i>), the target will be run. In the second
-example, if the <code>module-A-present</code> property is set
-(again, to any value), the target will not be run.
-</p>
-<p>Only one propertyname can be specified in the if/unless clause. If you want to check
-multiple conditions, you can use a dependend target for computing the result for the check:</p>
-<blockquote><pre>
-&lt;target name="myTarget" depends="myTarget.check" if="myTarget.run"&gt;
-    &lt;echo&gt;Files foo.txt and bar.txt are present.&lt;/echo&gt;
-&lt/target&gt;
-
-&lt;target name="myTarget.check"&gt;
-    &lt;condition property="myTarget.run"&gt;
-        &lt;and&gt;
-            &lt;available file="foo.txt"/&gt;
-            &lt;available file="bar.txt"/&gt;
-        &lt;/and&gt;
-    &lt;/condition&gt;
-&lt/target&gt;
-</pre></blockquote>
-<p>If no <code>if</code> and no <code>unless</code> attribute is present,
-the target will always be executed.</p>
-
-<p>
-<b>Important:</b> the <code>if</code> and <code>unless</code> attributes only
-enable or disable the target to which they are attached. They do not control
-whether or not targets that a conditional target depends upon get executed.
-In fact, they do not even get evaluated until the target is about to be executed,
-and all its predecessors have already run.
-
-<p>The optional <code>description</code> attribute can be used to provide a one-line description of this target, which is printed by the
-<code>-projecthelp</code> command-line option. Targets
-without such a description are deemed internal and will not be listed,
-unless either the <code>-verbose</code> or
-<code>-debug</code> option is used.
-</p>
-<p>It is a good practice to place your <a
-href="CoreTasks/tstamp.html">tstamp</a> tasks in a so-called
-<i>initialization</i> target, on which
-all other targets depend. Make sure that target is always the first one in
-the depends list of the other targets. In this manual, most initialization targets
-have the name <code>&quot;init&quot;</code>.</p>
-<p>If the depends attribute and the if/unless attribute are set, the depends attribute is
-executed first.</p>
-<p>A target has the following attributes:</p>
-<table border="1" cellpadding="2" cellspacing="0">
-  <tr>
-    <td valign="top"><b>Attribute</b></td>
-    <td valign="top"><b>Description</b></td>
-    <td align="center" valign="top"><b>Required</b></td>
-  </tr>
-  <tr>
-    <td valign="top">name</td>
-    <td valign="top">the name of the target.</td>
-    <td align="center" valign="top">Yes</td>
-  </tr>
-  <tr>
-    <td valign="top">depends</td>
-    <td valign="top">a comma-separated list of names of targets on which this
-      target depends.</td>
-    <td align="center" valign="top">No</td>
-  </tr>
-  <tr>
-    <td valign="top">if</td>
-    <td valign="top">the name of the property that must be set in order for this
-      target to execute, or <a href="properties.html#if+unless">something evaluating to true</a>.</td>
-    <td align="center" valign="top">No</td>
-  </tr>
-  <tr>
-    <td valign="top">unless</td>
-    <td valign="top">the name of the property that must not be set in order
-      for this target to execute, or <a href="properties.html#if+unless">something evaluating to false</a>.</td>
-    <td align="center" valign="top">No</td>
-  </tr>
-  <tr>
-    <td valign="top">description</td>
-    <td valign="top">a short description of this target's function.</td>
-    <td align="center" valign="top">No</td>
-  </tr>
-</table>
-
-<p>A target name can be any alphanumeric string valid in the encoding of the XML
-file. The empty string &quot;&quot; is in this set, as is
-comma &quot;,&quot; and space &quot; &quot;.
-Please avoid using these, as they will not be supported in future Ant versions
-because of all the confusion they cause. IDE support of unusual target names,
-or any target name containing spaces, varies with the IDE.</p>
 
-<p>Targets beginning with a hyphen such as <code>&quot;-restart&quot;</code>
-are valid, and can be used
-to name targets that should not be called directly from the command line.</p>
+<p>More information can be found in the
+  dedicated <a href="targets.html">manual page</a>.</p>
 
 <h3><a name="tasks">Tasks</a></h3>
 <p>A task is a piece of code that can be executed.</p>
diff --git a/docs/manual/usinglist.html b/docs/manual/usinglist.html
index e2abae99b..a3f1cb81d 100644
--- a/docs/manual/usinglist.html
+++ b/docs/manual/usinglist.html
@@ -32,7 +32,7 @@
 <li><a href="using.html#buildfile">Writing a Simple Buildfile</a></li>
 <div style="padding-left:1em">
   <li><a href="using.html#projects">Projects</a></li>
-  <li><a href="using.html#targets">Targets</a></li>
+  <li><a href="targets.html#targets">Targets</a></li>
   <li><a href="using.html#tasks">Tasks</a></li>
   <li><a href="using.html#properties">Properties</a></li>
   <li><a href="properties.html#built-in-props">Built-in Properties</a></li>

Attribute	Description	Required
name	the name of the target.	Yes
depends	a comma-separated list of names of targets on + which this target depends.	No
if	the name of the property that must be set in + order for this target to execute, + or something evaluating to + true.	No
unless	the name of the property that must not be set + in order for this target to execute, + or something evaluating to + false.	No
description	a short description of this target's function.	No
group	Adds the current target to the depends list of + the named target-group. + since Ant 1.8.0.	No