1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
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>
|
