1 | <!--
|
---|
2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
---|
3 | contributor license agreements. See the NOTICE file distributed with
|
---|
4 | this work for additional information regarding copyright ownership.
|
---|
5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
---|
6 | (the "License"); you may not use this file except in compliance with
|
---|
7 | the License. You may obtain a copy of the License at
|
---|
8 |
|
---|
9 | http://www.apache.org/licenses/LICENSE-2.0
|
---|
10 |
|
---|
11 | Unless required by applicable law or agreed to in writing, software
|
---|
12 | distributed under the License is distributed on an "AS IS" BASIS,
|
---|
13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
14 | See the License for the specific language governing permissions and
|
---|
15 | limitations under the License.
|
---|
16 | -->
|
---|
17 |
|
---|
18 | <html>
|
---|
19 | <head>
|
---|
20 | <meta http-equiv="Content-Language" content="en-us">
|
---|
21 | <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
---|
22 | <title>Subant Task</title>
|
---|
23 | </head>
|
---|
24 |
|
---|
25 | <body>
|
---|
26 |
|
---|
27 | <h2><a name="subant">Subant Task</a></h2>
|
---|
28 | Calls a given target for all defined sub-builds.
|
---|
29 |
|
---|
30 | <h3>Description</h3>
|
---|
31 | <p>
|
---|
32 | Calls a given target for all defined sub-builds.
|
---|
33 | This is an extension
|
---|
34 | of ant for bulk project execution.
|
---|
35 |
|
---|
36 | <strong>This task must not be used outside of a
|
---|
37 | <code>target</code> if it invokes the same build file it is
|
---|
38 | part of.</strong>
|
---|
39 | </p>
|
---|
40 | <p><em>Since Ant 1.6</em></p>
|
---|
41 | <a name="Use with directories">
|
---|
42 | <strong>Use with directories</strong></a>
|
---|
43 | <p>
|
---|
44 | subant can be used with directory sets to execute a build from different directories.
|
---|
45 | 2 different options are offered :
|
---|
46 | </p>
|
---|
47 | <ul>
|
---|
48 | <li>
|
---|
49 | to run the same build file <code>/somepath/otherpath/mybuild.xml</code>
|
---|
50 | with different base directories, use the genericantfile attribute
|
---|
51 | </li>
|
---|
52 | <li>if you want to run <code>directory1/mybuild.xml</code>, <code>directory2/mybuild.xml</code>, <code>....</code>,
|
---|
53 | use the antfile attribute. The subant task does not set the base directory for you in this case, because you can specify it in each build file.
|
---|
54 | </li>
|
---|
55 | </ul>
|
---|
56 |
|
---|
57 |
|
---|
58 | <!-- Ignore -->
|
---|
59 |
|
---|
60 |
|
---|
61 |
|
---|
62 |
|
---|
63 | <h3><a name="attributes">Parameters</a></h3>
|
---|
64 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
65 | <tr>
|
---|
66 | <td>
|
---|
67 | <b>Attribute</b>
|
---|
68 | </td>
|
---|
69 | <td>
|
---|
70 | <b>Description</b>
|
---|
71 | </td>
|
---|
72 | <td>
|
---|
73 | <b>Type</b>
|
---|
74 | </td>
|
---|
75 | <td>
|
---|
76 | <b>Requirement</b>
|
---|
77 | </td>
|
---|
78 | </tr>
|
---|
79 | <!-- Attribute Group -->
|
---|
80 |
|
---|
81 | <!-- Attribute Group -->
|
---|
82 | <!-- Attribute -->
|
---|
83 | <tr>
|
---|
84 | <td>
|
---|
85 | antfile
|
---|
86 | </td>
|
---|
87 | <td>
|
---|
88 | Build file name, to use in conjunction with directories.<br> Defaults to "build.xml".<br> If <code>genericantfile</code> is set, this attribute is ignored.
|
---|
89 | </td>
|
---|
90 | <td>
|
---|
91 | String
|
---|
92 | </td>
|
---|
93 | <td>
|
---|
94 | Optional
|
---|
95 | </td>
|
---|
96 | </tr>
|
---|
97 | <!-- Attribute -->
|
---|
98 | <tr>
|
---|
99 | <td>
|
---|
100 | buildpath
|
---|
101 | </td>
|
---|
102 | <td>
|
---|
103 | Set the buildpath to be used to find sub-projects.
|
---|
104 | </td>
|
---|
105 | <td>
|
---|
106 | Path
|
---|
107 | </td>
|
---|
108 | </tr>
|
---|
109 | <!-- Attribute -->
|
---|
110 | <tr>
|
---|
111 | <td>
|
---|
112 | buildpathref
|
---|
113 | </td>
|
---|
114 | <td>
|
---|
115 | Buildpath to use, by reference.
|
---|
116 | </td>
|
---|
117 | <td>
|
---|
118 | Reference
|
---|
119 | </td>
|
---|
120 | </tr>
|
---|
121 | <!-- Attribute -->
|
---|
122 | <tr>
|
---|
123 | <td>
|
---|
124 | failonerror
|
---|
125 | </td>
|
---|
126 | <td>
|
---|
127 | Sets whether to fail with a build exception on error, or go on.
|
---|
128 | </td>
|
---|
129 | <td>
|
---|
130 | boolean
|
---|
131 | </td>
|
---|
132 | </tr>
|
---|
133 | <!-- Attribute -->
|
---|
134 | <tr>
|
---|
135 | <td>
|
---|
136 | genericantfile
|
---|
137 | </td>
|
---|
138 | <td>
|
---|
139 | Build file path, to use in conjunction with directories.<br> Use <code>genericantfile</code>, in order to run the same build file with different basedirs.<br> If this attribute is set, <code>antfile</code> is ignored.
|
---|
140 | </td>
|
---|
141 | <td>
|
---|
142 | File
|
---|
143 | </td>
|
---|
144 | </tr>
|
---|
145 | <!-- Attribute -->
|
---|
146 | <tr>
|
---|
147 | <td>
|
---|
148 | inheritall
|
---|
149 | </td>
|
---|
150 | <td>
|
---|
151 | Corresponds to
|
---|
152 | <code><ant></code>'s
|
---|
153 | <code>inheritall</code> attribute but defaults
|
---|
154 | to false in this task..
|
---|
155 | </td>
|
---|
156 | <td>
|
---|
157 | boolean
|
---|
158 | </td>
|
---|
159 | </tr>
|
---|
160 | <!-- Attribute -->
|
---|
161 | <tr>
|
---|
162 | <td>
|
---|
163 | inheritrefs
|
---|
164 | </td>
|
---|
165 | <td>
|
---|
166 | Corresponds to <code><ant></code>'s <code>inheritrefs</code> attribute.
|
---|
167 | </td>
|
---|
168 | <td>
|
---|
169 | boolean
|
---|
170 | </td>
|
---|
171 | </tr>
|
---|
172 | <!-- Attribute -->
|
---|
173 | <tr>
|
---|
174 | <td>
|
---|
175 | output
|
---|
176 | </td>
|
---|
177 | <td>
|
---|
178 | Corresponds to <code><ant></code>'s <code>output</code> attribute.
|
---|
179 | </td>
|
---|
180 | <td>
|
---|
181 | String
|
---|
182 | </td>
|
---|
183 | </tr>
|
---|
184 | <!-- Attribute -->
|
---|
185 | <tr>
|
---|
186 | <td>
|
---|
187 | target
|
---|
188 | </td>
|
---|
189 | <td>
|
---|
190 |
|
---|
191 | </td>
|
---|
192 | <td>
|
---|
193 | String
|
---|
194 | </td>
|
---|
195 | </tr>
|
---|
196 |
|
---|
197 | <!-- Attribute -->
|
---|
198 | <tr>
|
---|
199 | <td>
|
---|
200 | verbose
|
---|
201 | </td>
|
---|
202 | <td>
|
---|
203 |
|
---|
204 | Enable/ disable log messages showing when each sub-build path is entered/ exited.
|
---|
205 | The default value is false.
|
---|
206 | </td>
|
---|
207 | <td>
|
---|
208 | boolean
|
---|
209 | </td>
|
---|
210 | </tr>
|
---|
211 |
|
---|
212 |
|
---|
213 | </table>
|
---|
214 | <!-- End Attributes -->
|
---|
215 |
|
---|
216 | <!-- Start Elements -->
|
---|
217 |
|
---|
218 | <h3><a name="elements">Parameters as nested elements</a></h3>
|
---|
219 |
|
---|
220 | <!-- Start Element -->
|
---|
221 | <h4>any filesystem based <a href="../CoreTypes/resources.html#collection">resource collection</a></h4>
|
---|
222 | <p>This includes <code><fileset></code>,
|
---|
223 | <code><dirset></code> and <code><filelist></code>
|
---|
224 | which are the nested resource collections supported prior
|
---|
225 | to Ant 1.7.</p>
|
---|
226 |
|
---|
227 | <h4>dirset</h4> (org.apache.tools.ant.types.DirSet)
|
---|
228 |
|
---|
229 | <p>Adds a directory set to the implicit build path. <p> <em>Note that the directories will be added to the build path in no particular order, so if order is significant, one should use a file list instead!</em></p>
|
---|
230 |
|
---|
231 | <h4>filelist</h4> (org.apache.tools.ant.types.FileList)
|
---|
232 | <p>
|
---|
233 | Adds an ordered file list to the implicit build path. <p> <em>Note that contrary to file and directory sets, file lists can reference non-existent files or directories!</em></p>
|
---|
234 |
|
---|
235 |
|
---|
236 | <h4>fileset</h4> (org.apache.tools.ant.types.FileSet)
|
---|
237 | <p>
|
---|
238 | Adds a file set to the implicit build path. <p> <em>Note that the directories will be added to the build path in no particular order, so if order is significant, one should use a file list instead!</em>
|
---|
239 | </p>
|
---|
240 |
|
---|
241 |
|
---|
242 | <h4>property</h4> (org.apache.tools.ant.taskdefs.Property)
|
---|
243 | <p>
|
---|
244 | Corresponds to <code><ant></code>'s nested <code><property></code> element.
|
---|
245 | </p>
|
---|
246 |
|
---|
247 |
|
---|
248 | <h4>propertyset</h4> (org.apache.tools.ant.types.PropertySet)
|
---|
249 | <p>
|
---|
250 | Corresponds to <code><ant></code>'s nested <code><propertyset></code> element.
|
---|
251 | </p>
|
---|
252 |
|
---|
253 |
|
---|
254 | <h4>buildpath</h4> (org.apache.tools.ant.types.Path)
|
---|
255 | <p>
|
---|
256 | Creates a nested build path, and add it to the implicit build path.
|
---|
257 | </p>
|
---|
258 |
|
---|
259 |
|
---|
260 | <h4>buildpathelement</h4> (org.apache.tools.ant.types.Path.PathElement)
|
---|
261 | <p>
|
---|
262 | Creates a nested <code><buildpathelement></code>, and add it to the implicit build path.
|
---|
263 | </p>
|
---|
264 |
|
---|
265 |
|
---|
266 | <h4>target</h4> (org.apache.tools.ant.taskdefs.Ant.TargetElement)
|
---|
267 | <p>
|
---|
268 | You can specify multiple targets using nested <code><target></code> elements
|
---|
269 | instead of using the target attribute. These will be executed as if
|
---|
270 | Ant had been invoked with a single target whose dependencies are the
|
---|
271 | targets so specified, in the order specified.
|
---|
272 | <!-- Ignore -->
|
---|
273 | <!-- Ignore -->
|
---|
274 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
275 | <tr>
|
---|
276 | <td valign="top"><b>Attribute</b></td>
|
---|
277 | <td valign="top"><b>Description</b></td>
|
---|
278 | <td align="center" valign="top"><b>Required</b></td>
|
---|
279 | </tr>
|
---|
280 | <tr>
|
---|
281 | <td valign="top">name</td>
|
---|
282 | <td valign="top">The name of the called target.</td>
|
---|
283 | <td valign="top" align="center">Yes</td>
|
---|
284 | </tr>
|
---|
285 | </table>
|
---|
286 | <p><em>since Ant 1.7</em>.</p>
|
---|
287 | </blockquote></td></tr>
|
---|
288 | </table>
|
---|
289 | <!-- End Element -->
|
---|
290 | <!-- manually written end -->
|
---|
291 |
|
---|
292 | <h3><a name="examples">Examples</a></h3>
|
---|
293 | <p>
|
---|
294 | <pre>
|
---|
295 | <project name="subant" default="subant1">
|
---|
296 | <property name="build.dir" value="subant.build"/>
|
---|
297 | <target name="subant1">
|
---|
298 | <subant target="">
|
---|
299 | <property name="build.dir" value="subant1.build"/>
|
---|
300 | <property name="not.overloaded" value="not.overloaded"/>
|
---|
301 | <fileset dir="." includes="*/build.xml"/>
|
---|
302 | </subant>
|
---|
303 | </target>
|
---|
304 | </project>
|
---|
305 | </pre>
|
---|
306 | <p>
|
---|
307 | this snippet build file will run ant in each subdirectory of the project directory,
|
---|
308 | where a file called build.xml can be found.
|
---|
309 | The property build.dir will have the value subant1.build in the ant projects called by subant.
|
---|
310 | </p>
|
---|
311 | <pre>
|
---|
312 | <subant target="">
|
---|
313 | <propertyset>
|
---|
314 | <propertyref prefix="toplevel"/>
|
---|
315 | <mapper type="glob" from="foo*" to="bar*"/>
|
---|
316 | </propertyset>
|
---|
317 | <fileset dir="." includes="*/build.xml"/>
|
---|
318 | </subant>
|
---|
319 | </pre>
|
---|
320 | <p>
|
---|
321 | this snippet build file will run ant in each subdirectory of the project directory,
|
---|
322 | where a file called build.xml can be found.
|
---|
323 | All properties whose name starts with "foo" are passed, their names are changed to start with "bar" instead
|
---|
324 | </p>
|
---|
325 | <pre>
|
---|
326 | <subant target="compile" genericantfile="/opt/project/build1.xml">
|
---|
327 | <dirset dir="." includes="projects*"/>
|
---|
328 | </subant>
|
---|
329 | </pre>
|
---|
330 | <p>
|
---|
331 | assuming the subdirs of the project dir are called projects1, projects2, projects3
|
---|
332 | this snippet will execute the compile target of /opt/project/build1.xml,
|
---|
333 | setting the basedir to projects1, projects2, projects3
|
---|
334 | </p>
|
---|
335 |
|
---|
336 | <!-- manually written -->
|
---|
337 | <p>Now a little more complex - but useful - scenario. Assume that we have
|
---|
338 | a directory structure like this:</p>
|
---|
339 | <pre>
|
---|
340 | root
|
---|
341 | | common.xml
|
---|
342 | | build.xml
|
---|
343 | |
|
---|
344 | +-- modules
|
---|
345 | +-- modA
|
---|
346 | | +-- src
|
---|
347 | +-- modB
|
---|
348 | +-- src
|
---|
349 |
|
---|
350 | <u><b>common.xml:</b></u><br>
|
---|
351 | <project>
|
---|
352 | <property name="src.dir" value="src"/>
|
---|
353 | <property name="build.dir" value="build"/>
|
---|
354 | <property name="classes.dir" value="${build.dir}/classes"/>
|
---|
355 |
|
---|
356 | <target name="compile">
|
---|
357 | <mkdir dir="${classes.dir}"/>
|
---|
358 | <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
|
---|
359 | </target>
|
---|
360 |
|
---|
361 | <!-- more targets -->
|
---|
362 | </project>
|
---|
363 |
|
---|
364 | <u><b>build.xml:</b></u><br>
|
---|
365 | <project>
|
---|
366 |
|
---|
367 | <macrodef name="iterate">
|
---|
368 | <attribute name="target"/>
|
---|
369 | <sequential>
|
---|
370 | <subant target="@{target}">
|
---|
371 | <fileset dir="modules" includes="*/build.xml"/>
|
---|
372 | </subant>
|
---|
373 | </sequential>
|
---|
374 | </macrodef>
|
---|
375 |
|
---|
376 |
|
---|
377 | <target name="compile">
|
---|
378 | <iterate target="compile"/>
|
---|
379 | </target>
|
---|
380 |
|
---|
381 | <!-- more targets -->
|
---|
382 | </project>
|
---|
383 |
|
---|
384 | <u><b>modules/modA/build.xml:</b></u><br>
|
---|
385 | <project name="modA">
|
---|
386 | <import file="../../common.xml"/>
|
---|
387 | </project>
|
---|
388 | </pre>
|
---|
389 |
|
---|
390 | <p>This results in very small buildfiles in the modules, maintainable
|
---|
391 | buildfile (common.xml) and a clear project structure. Additionally
|
---|
392 | the root buildfile is capable to run the whole build over all
|
---|
393 | modules.
|
---|
394 | </p>
|
---|
395 |
|
---|
396 | <pre>
|
---|
397 | <subant failonerror="false">
|
---|
398 | <fileset dir="." includes="**/build.xml" excludes="build.xml"/>
|
---|
399 | <target name="clean"/>
|
---|
400 | <target name="build"/>
|
---|
401 | </subant>
|
---|
402 | </pre>
|
---|
403 |
|
---|
404 | <p>Does a "clean build" for each subproject.</p>
|
---|
405 | <p><b>Hint:</b> because buildfiles are plain xml, you could generate the
|
---|
406 | masterbuildfile from the common buildfile by using a XSLT transformation:
|
---|
407 | </p>
|
---|
408 |
|
---|
409 | <pre>
|
---|
410 | <xslt in="common.xml"
|
---|
411 | out="master.xml"
|
---|
412 | style="${ant.home}/etc/common2master.xsl"
|
---|
413 | />
|
---|
414 | </pre>
|
---|
415 |
|
---|
416 |
|
---|
417 |
|
---|
418 | </body>
|
---|
419 | </html>
|
---|