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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
|
<!--
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>Ant Task</title>
</head>
<body>
<h2><a name="ant">Ant</a></h2>
<h3>Description</h3>
<p>Runs Apache Ant on a supplied buildfile. This can be used to build
subprojects. <strong>This task must not be used outside of a
<code>target</code> if it invokes the same build file it is part
of.</strong></p>
<p>When the <i>antfile</i> attribute is omitted, the file "build.xml"
in the supplied directory (<i>dir</i> attribute) is used.</p>
<p>If no target attribute is supplied, the default target of the new project is
used.</p>
<p>By default, all of the properties of the current project will be
available in the new project. Alternatively, you can set the
<i>inheritAll</i> attribute to <code>false</code> and only
"user" properties (i.e., those passed on the command-line)
will be passed to the new project. In either case, the set of
properties passed to the new project will override the properties that
are set in the new project (See also the <a
href="property.html">property task</a>).</p>
<p>You can also set properties in the new project from the old project
by using nested property tags. These properties are always passed
to the new project and any project created in that project
regardless of the setting of <i>inheritAll</i>. This allows you to
parameterize your subprojects.</p>
<p>When more than one nested <code><property></code> element
would set a property of the same name, the one declared last will
win. This is for backwards compatibility reasons even so it is
different from the way <code><property></code> tasks in build
files behave.</p>
<p>Properties defined on the command line cannot be overridden by
nested <code><property></code> elements. <em>Since Ant
1.8.0.</em> the same is true for nested structures
of <code><ant></code> tasks: if a build file <em>A</em>
invokes <em>B</em> via an <code><ant></code> task setting a
property with a nested <code><property></code> element
and <em>B</em> contains an <code><ant></code> tasks
invoking <em>C</em>, <em>C</em> will see the value set
in <em>A</em>, even if <em>B</em> used a
nested <code><property></code> element as well.</p>
<p>References to data types can also be passed to the new project, but
by default they are not. If you set the inheritrefs attribute to
true, all references will be copied, but they will not override
references defined in the new project.</p>
<p>Nested <a href="#reference"><i><code><reference></code></i></a> elements
can also be used to copy references from the calling project to the
new project, optionally under a different id. References taken from
nested elements will override existing references that have been
defined outside of targets in the new project - but not those defined
inside of targets.</p>
<h3>Parameters</h3>
<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">antfile</td>
<td valign="top">the buildfile to use. Defaults to
"build.xml". This file is expected to be a filename
relative to the dir attribute given.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">dir</td>
<td valign="top">the directory to use as a basedir for the new Ant
project (unless useNativeBasedir is set to true).
Defaults to the current project's basedir, unless
inheritall has been set to false, in which case it doesn't
have a default value. This will override the basedir
setting of the called project.<br/>
Also serves as the directory to resolve the antfile and output
attribute's values (if any).
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">target</td>
<td valign="top">the target of the new Ant project that should be executed.
Defaults to the new project's default target.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">output</td>
<td valign="top">Filename to write the ant output to. This is
relative to the value of the dir attribute if it has been set or
to the base directory of the current project otherwise.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">inheritAll</td>
<td valign="top">If <code>true</code>, pass all properties to the
new Ant project. Defaults to <code>true</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">inheritRefs</td>
<td valign="top">If <code>true</code>, pass all references to the
new Ant project. Defaults to <code>false</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">useNativeBasedir</td>
<td valign="top">If set to true, the child build will use the same
basedir as it would have used when run from the command line
(i.e. the basedir one would expect when looking at the child
build's buildfile). Defaults to <code>false</code>. <em>since
Ant 1.8.0</em></td>
<td valign="top" align="center">No</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>property</h4>
<p>See the description of the <a href="property.html">property
task</a>. <br>
These properties become equivalent to properties you define on
the command line. These are special properties and they will always get passed
down, even through additional <code><*ant*></code> tasks with inheritall set to
false (see above). <br>
Note that the <code>refid</code> attribute points to a
reference in the calling project, not in the new one.</p>
<h4><a name="reference">reference</a></h4>
<p>Used to choose references that shall be copied into the new project,
optionally changing their id.</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">refid</td>
<td valign="top">The id of the reference in the calling project.</td>
<td valign="top" align="center">Yes</td>
</tr>
<tr>
<td valign="top">torefid</td>
<td valign="top">The id of the reference in the new project.</td>
<td valign="top" align="center">No, defaults to the value of refid.</td>
</tr>
</table>
<h4>propertyset</h4>
<p>You can specify a set of properties to be copied into the new
project with <a
href="../Types/propertyset.html">propertyset</a>s.</p>
<p><em>since Ant 1.6</em>.</p>
<h4>target</h4>
<p>You can specify multiple targets using nested <code><target></code> elements
instead of using the target attribute. These will be executed as if
Ant had been invoked with a single target whose dependencies are the
targets so specified, in the order specified.</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 called target.</td>
<td valign="top" align="center">Yes</td>
</tr>
</table>
<p><em>since Ant 1.6.3</em>.</p>
<h3>Basedir of the new project</h3>
<p>If you set <code>useNativeBasedir</code> to true, the basedir of
the new project will be whatever the basedir attribute of
the <code><project></code> element of the new project says (or
the new project's directory if the there is no basedir attribute) -
no matter what any other attribute of this task says and no matter
how deeply nested into levels of
<code><ant></code> invocations this task lives.</p>
<p>If you haven't set <code>useNativeBasedir</code> or set it to
false, the following rules apply:</p>
<p>The basedir value of the new project is affected by the two
attributes dir and inheritall as well as
the <code><ant></code> task's history. The current behaviour
is known to be confusing but cannot be changed without breaking
backwards compatibility in subtle ways.</p>
<p>If the <code><ant></code> task is in a "top level" build
file, i.e. the project containing the <code><ant></code> task
has not itself been invoked as part of a
different <code><ant></code> (or <code><antcall></code>)
task "higher up", the following table shows the details:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>dir attribute</b></td>
<td valign="top"><b>inheritAll attribute</b></td>
<td valign="top"><b>new project's basedir</b></td>
</tr>
<tr>
<td valign="top">value provided</td>
<td valign="top">true</td>
<td valign="top">value of dir attribute</td>
</tr>
<tr>
<td valign="top">value provided</td>
<td valign="top">false</td>
<td valign="top">value of dir attribute</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">true</td>
<td valign="top">basedir of calling project (the one whose build
file contains the <code><ant></code> task).</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">false</td>
<td valign="top">basedir attribute of the <code><project></code> element
of the new project</td>
</tr>
</table>
<p>If on the other hand the <code><ant></code> task is already
nested into another invocation, the parent invocation's settings
affect the outcome of the basedir value. The current task's dir
attribute will always win, but if the dir attribute has been omitted
an even more complex situation arises:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>parent dir attribute</b></td>
<td valign="top"><b>parent inheritAll attribute</b></td>
<td valign="top"><b>current inheritAll attribute</b></td>
<td valign="top"><b>new project's basedir</b></td>
</tr>
<tr>
<td valign="top">value provided</td>
<td valign="top">any</td>
<td valign="top">any</td>
<td valign="top">value of parent's dir attribute</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">true</td>
<td valign="top">true</td>
<td valign="top">basedir of parent project (the one whose build
file called the build file that contains
the current <code><ant></code> task).</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">true</td>
<td valign="top">false</td>
<td valign="top">basedir of parent project (the one whose build
file called the build file that contains
the current <code><ant></code> task).</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">false</td>
<td valign="top">true</td>
<td valign="top">basedir of calling project (the one whose build
file contains the current <code><ant></code> task).</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">false</td>
<td valign="top">false</td>
<td valign="top">basedir attribute of the <code><project></code> element
of the new project</td>
</tr>
</table>
<p>If you add even deeper levels of nesting, things get even more
complicated and you need to apply the above table recursively.</p>
<p>If the basedir of the outer most build has been specified as a
property on the command line (i.e. <code>-Dbasedir=some-value</code>
or a <code>-propertyfile</code> argument) the value provided will
get an even higher priority. For any <code><ant></code> task
that doesn't specify a dir attribute, the new project's basedir will
be the value specified on the command line - no matter how deeply
nested into layers of build files the task may be.</p>
<p>The same happens if the basedir is specified as a
nested <code><property></code> of an <code><ant></code>
task. The basedir of build files started at deeper levels will be
set to the specified value of the property element unless the
corresponding Ant tasks set the dir attribute explicitly.</p>
<h3>Examples</h3>
<blockquote><pre>
<ant antfile="subproject/subbuild.xml" target="compile"/>
<ant dir="subproject"/>
<ant antfile="subproject/property_based_subbuild.xml">
<property name="param1" value="version 1.x"/>
<property file="config/subproject/default.properties"/>
</ant>
<ant inheritAll="false" antfile="subproject/subbuild.xml">
<property name="output.type" value="html"/>
</ant>
</pre></blockquote>
<p>These lines invoke the same build file:</p>
<blockquote><pre>
<ant antfile="sub1/sub2/build.xml" />
<ant antfile="sub2/build.xml" dir="sub1" />
<ant antfile="build.xml" dir="sub1/sub2" />
</pre></blockquote>
<p>The build file of the calling project defines some
<code><path></code> elements like this:</p>
<blockquote><pre>
<path id="path1">
...
</path>
<path id="path2">
...
</path>
</pre></blockquote>
<p>and the called build file (<code>subbuild.xml</code>) also defines
a <code><path></code> with the id <code>path1</code>, but
<code>path2</code> is not defined:</p>
<blockquote><pre>
<ant antfile="subbuild.xml" inheritrefs="true"/>
</pre></blockquote>
<p>will not override <code>subbuild</code>'s definition of
<code>path1</code>, but make the parent's definition of
<code>path2</code> available in the subbuild.</p>
<blockquote><pre>
<ant antfile="subbuild.xml"/>
</pre></blockquote>
<p>as well as</p>
<blockquote><pre>
<ant antfile="subbuild.xml" inheritrefs="false"/>
</pre></blockquote>
<p>will neither override <code>path1</code> nor copy
<code>path2</code>.</p>
<blockquote><pre>
<ant antfile="subbuild.xml" inheritrefs="false">
<reference refid="path1"/>
</ant>
</pre></blockquote>
<p>will override <code>subbuild</code>'s definition of
<code>path1</code>.</p>
<blockquote><pre>
<ant antfile="subbuild.xml" inheritrefs="false">
<reference refid="path1" torefid="path2"/>
</ant>
</pre></blockquote>
<p>will copy the parent's definition of <code>path1</code> into the
new project using the id <code>path2</code>.</p>
</body>
</html>
|
