Author: bodewig
Date: Tue Dec 22 05:31:20 2009
New Revision: 893073
URL: http://svn.apache.org/viewvc?rev=893073&view=rev
Log:
add a manual page for targets and target-groups
Added:
ant/core/trunk/docs/manual/targets.html (with props)
Modified:
ant/core/trunk/docs/manual/conceptstypeslist.html
ant/core/trunk/docs/manual/using.html
ant/core/trunk/docs/manual/usinglist.html
Modified: ant/core/trunk/docs/manual/conceptstypeslist.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/conceptstypeslist.html?rev=893073&r1=893072&r2=893073&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/conceptstypeslist.html (original)
+++ ant/core/trunk/docs/manual/conceptstypeslist.html Tue Dec 22 05:31:20 2009
@@ -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>
Added: ant/core/trunk/docs/manual/targets.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/targets.html?rev=893073&view=auto
==============================================================================
--- ant/core/trunk/docs/manual/targets.html (added)
+++ ant/core/trunk/docs/manual/targets.html Tue Dec 22 05:31:20 2009
@@ -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><target name="A"/>
+<target name="B" depends="A"/>
+<target name="C" depends="B"/>
+<target name="D" depends="C,B,A"/></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><target name="build-module-A"
if="module-A-present"/></pre>
+ <pre><target name="build-own-fake-module-A"
unless="module-A-present"/></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>
+<target name="myTarget" depends="myTarget.check" if="myTarget.run">
+ <echo>Files foo.txt and bar.txt are present.</echo>
+</target>
+
+<target name="myTarget.check">
+ <condition property="myTarget.run">
+ <and>
+ <available file="foo.txt"/>
+ <available file="bar.txt"/>
+ </and>
+ </condition>
+</target>
+</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>"init"</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 "" is in this
+ set, as is comma "," and space " ". 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>"-restart"</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>
+<target name="create-directory-layout">
+ ...
+</target>
+<target-group name="ready-to-compile"
+ depends="create-directory-layout"/>
+<target name="compile" depends="ready-to-compile">
+ ...
+</target>
+</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>
+<target name="generate-sources"
+ group="ready-to-compile">
+ ...
+</target>
+</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>
Propchange: ant/core/trunk/docs/manual/targets.html
------------------------------------------------------------------------------
svn:eol-style = native
Modified: ant/core/trunk/docs/manual/using.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/using.html?rev=893073&r1=893072&r2=893073&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/using.html (original)
+++ ant/core/trunk/docs/manual/using.html Tue Dec 22 05:31:20 2009
@@ -85,135 +85,9 @@
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><target name="A"/>
-<target name="B" depends="A"/>
-<target name="C" depends="B"/>
-<target name="D" depends="C,B,A"/></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><target name="build-module-A"
if="module-A-present"/></pre>
- <pre><target name="build-own-fake-module-A"
unless="module-A-present"/></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>
-<target name="myTarget" depends="myTarget.check" if="myTarget.run">
- <echo>Files foo.txt and bar.txt are present.</echo>
-</target>
-
-<target name="myTarget.check">
- <condition property="myTarget.run">
- <and>
- <available file="foo.txt"/>
- <available file="bar.txt"/>
- </and>
- </condition>
-</target>
-</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>"init"</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 "" is in this set, as is
-comma "," and space " ".
-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>"-restart"</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>
Modified: ant/core/trunk/docs/manual/usinglist.html
URL:
http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/usinglist.html?rev=893073&r1=893072&r2=893073&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/usinglist.html (original)
+++ ant/core/trunk/docs/manual/usinglist.html Tue Dec 22 05:31:20 2009
@@ -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>
