source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual/manual/CoreTasks/ant.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 10.3 KB
Line 
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<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22<title>Ant Task</title>
23</head>
24
25<body>
26
27<h2><a name="ant">Ant</a></h2>
28<h3>Description</h3>
29
30<p>Runs Ant on a supplied buildfile. This can be used to build
31subprojects. <strong>This task must not be used outside of a
32<code>target</code> if it invokes the same build file it is part
33of.</strong></p>
34
35<p>When the <i>antfile</i> attribute is omitted, the file &quot;build.xml&quot;
36in the supplied directory (<i>dir</i> attribute) is used.</p>
37<p>If no target attribute is supplied, the default target of the new project is
38used.</p>
39<p>By default, all of the properties of the current project will be
40available in the new project. Alternatively, you can set the
41<i>inheritAll</i> attribute to <code>false</code> and only
42&quot;user&quot; properties (i.e., those passed on the command-line)
43will be passed to the new project. In either case, the set of
44properties passed to the new project will override the properties that
45are set in the new project (See also the <a
46href="property.html">property task</a>).</p>
47
48<p>You can also set properties in the new project from the old project
49by using nested property tags. These properties are always passed
50to the new project and any project created in that project
51regardless of the setting of <i>inheritAll</i>. This allows you to
52parameterize your subprojects. Properties defined on the command line
53cannot be overridden by nested <code>&lt;property&gt;</code> elements.</p>
54
55<p>References to data types can also be passed to the new project, but
56by default they are not. If you set the inheritrefs attribute to
57true, all references will be copied, but they will not override
58references defined in the new project.</p>
59
60<p>Nested <a href="#reference"><i><code>&lt;reference&gt;</code></i></a> elements
61can also be used to copy references from the calling project to the
62new project, optionally under a different id. References taken from
63nested elements will override existing references that have been
64defined outside of targets in the new project - but not those defined
65inside of targets.</p>
66
67<h3>Parameters</h3>
68<table border="1" cellpadding="2" cellspacing="0">
69 <tr>
70 <td valign="top"><b>Attribute</b></td>
71 <td valign="top"><b>Description</b></td>
72 <td align="center" valign="top"><b>Required</b></td>
73 </tr>
74 <tr>
75 <td valign="top">antfile</td>
76 <td valign="top">the buildfile to use. Defaults to
77 &quot;build.xml&quot;. This file is expected to be a filename
78 relative to the dir attribute given.</td>
79 <td valign="top" align="center">No</td>
80 </tr>
81 <tr>
82 <td valign="top">dir</td>
83 <td valign="top">the directory to use as a basedir for the new Ant project.
84 Defaults to the current project's basedir, unless
85 inheritall has been set to false, in which case it doesn't
86 have a default value. This will override the basedir
87 setting of the called project.</td>
88 <td valign="top" align="center">No</td>
89 </tr>
90 <tr>
91 <td valign="top">target</td>
92 <td valign="top">the target of the new Ant project that should be executed.
93 Defaults to the new project's default target.</td>
94 <td valign="top" align="center">No</td>
95 </tr>
96 <tr>
97 <td valign="top">output</td>
98 <td valign="top">Filename to write the ant output to. This is
99 relative to the value of the dir attribute if it has been set or
100 to the base directory of the current project otherwise.
101 </td>
102 <td align="center" valign="top">No</td>
103 </tr>
104 <tr>
105 <td valign="top">inheritAll</td>
106 <td valign="top">If <code>true</code>, pass all properties to the
107 new Ant project. Defaults to <code>true</code>.</td>
108 <td align="center" valign="top">No</td>
109 </tr>
110 <tr>
111 <td valign="top">inheritRefs</td>
112 <td valign="top">If <code>true</code>, pass all references to the
113 new Ant project. Defaults to <code>false</code>.</td>
114 <td align="center" valign="top">No</td>
115 </tr>
116</table>
117
118<h3>Parameters specified as nested elements</h3>
119
120<h4>property</h4>
121<p>See the description of the <a href="property.html">property
122task</a>. <br>
123These properties become equivalent to properties you define on
124the command line. These are special properties and they will always get passed
125down, even through additional <code>&lt;*ant*&gt;</code> tasks with inheritall set to
126false (see above). <br>
127Note that the <code>refid</code> attribute points to a
128reference in the calling project, not in the new one.</p>
129
130<h4><a name="reference">reference</a></h4>
131<p>Used to choose references that shall be copied into the new project,
132optionally changing their id.</p>
133
134<table border="1" cellpadding="2" cellspacing="0">
135 <tr>
136 <td valign="top"><b>Attribute</b></td>
137 <td valign="top"><b>Description</b></td>
138 <td align="center" valign="top"><b>Required</b></td>
139 </tr>
140 <tr>
141 <td valign="top">refid</td>
142 <td valign="top">The id of the reference in the calling project.</td>
143 <td valign="top" align="center">Yes</td>
144 </tr>
145 <tr>
146 <td valign="top">torefid</td>
147 <td valign="top">The id of the reference in the new project.</td>
148 <td valign="top" align="center">No, defaults to the value of refid.</td>
149 </tr>
150</table>
151
152<h4>propertyset</h4>
153
154<p>You can specify a set of properties to be copied into the new
155project with <a
156href="../CoreTypes/propertyset.html">propertyset</a>s.</p>
157
158<p><em>since Ant 1.6</em>.</p>
159
160<h4>target</h4>
161
162<p>You can specify multiple targets using nested <code>&lt;target&gt;</code> elements
163instead of using the target attribute. These will be executed as if
164Ant had been invoked with a single target whose dependencies are the
165targets so specified, in the order specified.</p>
166<table border="1" cellpadding="2" cellspacing="0">
167 <tr>
168 <td valign="top"><b>Attribute</b></td>
169 <td valign="top"><b>Description</b></td>
170 <td align="center" valign="top"><b>Required</b></td>
171 </tr>
172 <tr>
173 <td valign="top">name</td>
174 <td valign="top">The name of the called target.</td>
175 <td valign="top" align="center">Yes</td>
176 </tr>
177</table>
178<p><em>since Ant 1.6.3</em>.</p>
179
180<h3>Basedir of the new project</h3>
181
182<p>The basedir value of the new project is affected by the two
183attributes dir and inheritall, see the following table for
184details:</p>
185
186<table border="1" cellpadding="2" cellspacing="0">
187 <tr>
188 <td valign="top"><b>dir attribute</b></td>
189 <td valign="top"><b>inheritAll attribute</b></td>
190 <td valign="top"><b>new project's basedir</b></td>
191 </tr>
192 <tr>
193 <td valign="top">value provided</td>
194 <td valign="top">true</td>
195 <td valign="top">value of dir attribute</td>
196 </tr>
197 <tr>
198 <td valign="top">value provided</td>
199 <td valign="top">false</td>
200 <td valign="top">value of dir attribute</td>
201 </tr>
202 <tr>
203 <td valign="top">omitted</td>
204 <td valign="top">true</td>
205 <td valign="top">basedir of calling project (the one whose build
206 file contains the <code>&lt;ant&gt;</code> task).</td>
207 </tr>
208 <tr>
209 <td valign="top">omitted</td>
210 <td valign="top">false</td>
211 <td valign="top">basedir attribute of the <code>&lt;project&gt;</code> element
212 of the new project</td>
213 </tr>
214</table>
215
216<h3>Examples</h3>
217<blockquote><pre>
218&lt;ant antfile=&quot;subproject/subbuild.xml&quot; target=&quot;compile&quot;/&gt;
219
220&lt;ant dir=&quot;subproject&quot;/&gt;
221
222&lt;ant antfile=&quot;subproject/property_based_subbuild.xml&quot;&gt;
223 &lt;property name=&quot;param1&quot; value=&quot;version 1.x&quot;/&gt;
224 &lt;property file=&quot;config/subproject/default.properties&quot;/&gt;
225&lt;/ant&gt;
226
227&lt;ant inheritAll=&quot;false&quot; antfile=&quot;subproject/subbuild.xml&quot;&gt;
228 &lt;property name=&quot;output.type&quot; value=&quot;html&quot;/&gt;
229&lt;/ant&gt;
230</pre></blockquote>
231
232<p>These lines invoke the same build file:</p>
233<blockquote><pre>
234&lt;ant antfile=&quot;sub1/sub2/build.xml&quot; /&gt;
235&lt;ant antfile=&quot;sub2/build.xml&quot; dir=&quot;sub1&quot; /&gt;
236&lt;ant antfile=&quot;build.xml&quot; dir=&quot;sub1/sub2&quot; /&gt;
237</pre></blockquote>
238
239<p>The build file of the calling project defines some
240<code>&lt;path&gt;</code> elements like this:</p>
241
242<blockquote><pre>
243&lt;path id="path1"&gt;
244 ...
245&lt;/path&gt;
246&lt;path id="path2"&gt;
247 ...
248&lt;/path&gt;
249</pre></blockquote>
250
251<p>and the called build file (<code>subbuild.xml</code>) also defines
252a <code>&lt;path&gt;</code> with the id <code>path1</code>, but
253<code>path2</code> is not defined:</p>
254
255<blockquote><pre>
256&lt;ant antfile=&quot;subbuild.xml&quot; inheritrefs=&quot;true&quot;/&gt;
257</pre></blockquote>
258
259<p>will not override <code>subbuild</code>'s definition of
260<code>path1</code>, but make the parent's definition of
261<code>path2</code> available in the subbuild.</p>
262
263<blockquote><pre>
264&lt;ant antfile=&quot;subbuild.xml&quot;/&gt;
265</pre></blockquote>
266
267<p>as well as</p>
268
269<blockquote><pre>
270&lt;ant antfile=&quot;subbuild.xml&quot; inheritrefs=&quot;false&quot;/&gt;
271</pre></blockquote>
272
273<p>will neither override <code>path1</code> nor copy
274<code>path2</code>.</p>
275
276<blockquote><pre>
277&lt;ant antfile=&quot;subbuild.xml&quot; inheritrefs=&quot;false&quot;&gt;
278 &lt;reference refid=&quot;path1&quot;/&gt;
279&lt;/ant&gt;
280</pre></blockquote>
281
282<p>will override <code>subbuild</code>'s definition of
283<code>path1</code>.</p>
284
285<blockquote><pre>
286&lt;ant antfile=&quot;subbuild.xml&quot; inheritrefs=&quot;false&quot;&gt;
287 &lt;reference refid=&quot;path1&quot; torefid=&quot;path2&quot;/&gt;
288&lt;/ant&gt;
289</pre></blockquote>
290
291<p>will copy the parent's definition of <code>path1</code> into the
292new project using the id <code>path2</code>.</p>
293
294
295
296</body>
297</html>
Note: See TracBrowser for help on using the repository browser.