source: other-projects/trunk/gs3-release-maker/apache-ant-1.6.5/docs/manual/CoreTasks/ant.html@ 14627

Last change on this file since 14627 was 14627, checked in by oranfry, 17 years ago

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