diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/targets.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/targets.html | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/targets.html b/framework/src/ant/apache-ant-1.9.6/manual/targets.html new file mode 100644 index 00000000..a778c950 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/targets.html @@ -0,0 +1,300 @@ +<!-- + 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 Extension-Points</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 Apache Ant ensures that these + other targets have been executed before the current target. For + example you might have a target for compiling 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> + + <blockquote><pre><b>Call-Graph:</b> A --> B --> C --> D</pre></blockquote> + + <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 + dependent 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> + + <blockquote><pre><b>Call-Graph:</b> myTarget.check --> maybe(myTarget)</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="Tasks/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> + <blockquote><pre> + <project> + <target name="init"> + <tstamp/> + </target> + <target name="otherTarget" depends="init"> + ... + </target> + </project> + </pre></blockquote> + + <p>Especially if you only have a few tasks you also could place these + tasks directly under the project tag (since Ant 1.6.0):</p> + <blockquote><pre> + <project> + <tstamp/> + </project> + </pre></blockquote> + + <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">extensionOf</td> + <td valign="top">Adds the current target to the depends list of + the named <a href="#extension-points">extension-point</a>. + <em>since Ant 1.8.0.</em></td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">onMissingExtensionPoint</td> + <td valign="top">What to do if this target tries to extend a + missing + <a href="#extension-points">extension-point</a>. ("fail", + "warn", "ignore"). + <em>since Ant 1.8.2.</em></td> + <td align="center" valign="top">No. Not allowed unless + <code>extensionOf</code> is present. Defaults to <code>fail</code>. + </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 on command line and IDE. 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. <br> + For Ants main class every option starting with hyphen is an + option for Ant itself and not a target. For that reason calling these + target from command line is not possible. On the other hand IDEs usually + don't use Ants main class as entry point and calling them from the IDE + is usually possible.</p> + + <h1><a name="extension-points">Extension-Points</a></h1> + + <p><em>since Ant 1.8.0.</em></p> + + <p>Extension-Points 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 an extension-points's depends list via + their extensionOf attribute. The targets that add themselves will be + added after the targets of the explicit depends-attribute of the + extension-point, if multiple targets add themselves, their relative + order is not defined.</p> + + <p>The main purpose of an extension-point is to act as an extension + point for build files designed to + be <a href="Tasks/import.html">imported</a>. In the imported + file an extension-point defines a state that must be reached and + targets from other build files can join the depends list of said + extension-point 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> +<extension-point name="ready-to-compile" + depends="create-directory-layout"/> +<target name="compile" depends="ready-to-compile"> + ... +</target> +</pre></blockquote> + + <blockquote><pre><b>Call-Graph:</b> create-directory-layout --> 'empty slot' --> compile</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" + extensionOf="ready-to-compile"> + ... +</target> +</pre></blockquote> + + <blockquote><pre><b>Call-Graph:</b> create-directory-layout --> generate-sources --> compile</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> |