2009-12-22 05:31:20 +00:00
|
|
|
<!--
|
|
|
|
|
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"/>
|
2010-01-04 05:57:17 +00:00
|
|
|
<title>Targets and Extension-Points</title>
|
2009-12-22 05:31:20 +00:00
|
|
|
</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
|
2009-12-22 08:21:43 +00:00
|
|
|
other targets have been executed before the current target. For
|
|
|
|
|
example you might have a target for compiling and a
|
2009-12-22 05:31:20 +00:00
|
|
|
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>
|
2009-12-22 10:51:01 +00:00
|
|
|
|
|
|
|
|
<blockquote><pre><b>Call-Graph:</b> A --> B --> C --> D</pre></blockquote>
|
2009-12-22 05:31:20 +00:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2009-12-22 10:51:01 +00:00
|
|
|
<blockquote><pre><b>Call-Graph:</b> myTarget.check --> maybe(myTarget)</pre></blockquote>
|
|
|
|
|
|
2009-12-22 05:31:20 +00:00
|
|
|
<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
|
2009-12-22 10:51:01 +00:00
|
|
|
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
|
2009-12-22 15:51:49 +00:00
|
|
|
tasks directly under the project tag (since Ant 1.6.0):</p>
|
2009-12-22 10:51:01 +00:00
|
|
|
<blockquote><pre>
|
|
|
|
|
<project>
|
|
|
|
|
<tstamp/>
|
|
|
|
|
</project>
|
|
|
|
|
</pre></blockquote>
|
2009-12-22 05:31:20 +00:00
|
|
|
|
|
|
|
|
<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>
|
2010-01-04 05:57:17 +00:00
|
|
|
<td valign="top">extensionOf</td>
|
2009-12-22 05:31:20 +00:00
|
|
|
<td valign="top">Adds the current target to the depends list of
|
2010-01-04 05:57:17 +00:00
|
|
|
the named <a href="#extension-points">extension-point</a>.
|
2009-12-22 05:31:20 +00:00
|
|
|
<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
|
2009-12-22 08:21:43 +00:00
|
|
|
versions because of all the confusion they cause on command line and IDE. IDE support of
|
2009-12-22 05:31:20 +00:00
|
|
|
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
|
2009-12-22 08:21:43 +00:00
|
|
|
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>
|
2009-12-22 05:31:20 +00:00
|
|
|
|
2010-01-04 05:57:17 +00:00
|
|
|
<h1><a name="extension-points">Extension-Points</a></h1>
|
2009-12-22 05:31:20 +00:00
|
|
|
|
|
|
|
|
<p><em>since Ant 1.8.0.</em></p>
|
|
|
|
|
|
2010-01-04 05:57:17 +00:00
|
|
|
<p>Extension-Points are similar to targets in that they have a name and
|
2009-12-22 05:31:20 +00:00
|
|
|
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>
|
|
|
|
|
|
2010-01-04 05:57:17 +00:00
|
|
|
<p>Targets can add themselves to an extension-points's depends list via
|
|
|
|
|
their extensionOf attribute. The targets that add themselves will be
|
2009-12-22 05:31:20 +00:00
|
|
|
added after the targets of the explicit depends-attribute of the
|
2010-01-04 05:57:17 +00:00
|
|
|
extension-point, if multiple targets add themselves, their relative
|
2009-12-22 05:31:20 +00:00
|
|
|
order is not defined.</p>
|
|
|
|
|
|
2010-01-04 05:57:17 +00:00
|
|
|
<p>The main purpose of an extension-point is to act as an extension
|
2009-12-22 05:31:20 +00:00
|
|
|
point for build files designed to
|
|
|
|
|
be <a href="CoreTasks\import.html">imported</a>. In the imported
|
2010-01-04 05:57:17 +00:00
|
|
|
file an extension-point defines a state that must be reached and
|
2009-12-22 05:31:20 +00:00
|
|
|
targets from other build files can join the depends list of said
|
2010-01-04 05:57:17 +00:00
|
|
|
extension-point in order to contribute to that state.</p>
|
2009-12-22 05:31:20 +00:00
|
|
|
|
|
|
|
|
<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>
|
2010-01-04 05:57:17 +00:00
|
|
|
<extension-point name="ready-to-compile"
|
2009-12-22 05:31:20 +00:00
|
|
|
depends="create-directory-layout"/>
|
|
|
|
|
<target name="compile" depends="ready-to-compile">
|
|
|
|
|
...
|
|
|
|
|
</target>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
|
2009-12-22 10:51:01 +00:00
|
|
|
<blockquote><pre><b>Call-Graph:</b> create-directory-layout --> 'empty slot' --> compile</pre></blockquote>
|
|
|
|
|
|
|
|
|
|
|
2009-12-22 05:31:20 +00:00
|
|
|
<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"
|
2010-01-04 05:57:17 +00:00
|
|
|
extensionOf="ready-to-compile">
|
2009-12-22 05:31:20 +00:00
|
|
|
...
|
|
|
|
|
</target>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
|
2009-12-22 10:51:01 +00:00
|
|
|
<blockquote><pre><b>Call-Graph:</b> create-directory-layout --> generate-sources --> compile</pre></blockquote>
|
|
|
|
|
|
|
|
|
|
|
2009-12-22 05:31:20 +00:00
|
|
|
<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>
|
