aboutsummaryrefslogtreecommitdiffstats
path: root/framework/src/ant/apache-ant-1.9.6/manual/targets.html
diff options
context:
space:
mode:
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.html300
1 files changed, 0 insertions, 300 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
deleted file mode 100644
index a778c950..00000000
--- a/framework/src/ant/apache-ant-1.9.6/manual/targets.html
+++ /dev/null
@@ -1,300 +0,0 @@
-<!--
- 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>&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>
-
- <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>&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
- dependent 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>
-
- <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>&quot;init&quot;</code>.</p>
- <blockquote><pre>
- &lt;project&gt;
- &lt;target name=&quot;init&quot;&gt;
- &lt;tstamp/&gt;
- &lt;/target&gt;
- &lt;target name=&quot;otherTarget&quot; depends=&quot;init&quot;&gt;
- ...
- &lt;/target&gt;
- &lt;/project&gt;
- </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>
- &lt;project&gt;
- &lt;tstamp/&gt;
- &lt;/project&gt;
- </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 &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 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>&quot;-restart&quot;</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>
-&lt;target name="create-directory-layout"&gt;
- ...
-&lt;/target&gt;
-&lt;extension-point name="ready-to-compile"
- depends="create-directory-layout"/&gt;
-&lt;target name="compile" depends="ready-to-compile"&gt;
- ...
-&lt;/target&gt;
-</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>
-&lt;target name="generate-sources"
- extensionOf="ready-to-compile"&gt;
- ...
-&lt;/target&gt;
-</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>