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>Writing a Simple Buildfile</title>
|
---|
23 | </head>
|
---|
24 |
|
---|
25 | <body>
|
---|
26 | <h1>Using Ant</h1>
|
---|
27 | <h2><a name="buildfile">Writing a Simple Buildfile</a></h2>
|
---|
28 | <p>Ant's buildfiles are written in XML. Each buildfile contains one project
|
---|
29 | and at least one (default) target. Targets contain task elements.
|
---|
30 | Each task element of the buildfile can have an <code>id</code> attribute and
|
---|
31 | can later be referred to by the value supplied to this. The value has
|
---|
32 | to be unique. (For additional information, see the
|
---|
33 | <a href="#tasks"> Tasks</a> section below.)</p>
|
---|
34 | <h3><a name="projects">Projects</a></h3>
|
---|
35 | <p>A <i>project</i> has three attributes:</p>
|
---|
36 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
37 | <tr>
|
---|
38 | <td valign="top"><b>Attribute</b></td>
|
---|
39 | <td valign="top"><b>Description</b></td>
|
---|
40 | <td align="center" valign="top"><b>Required</b></td>
|
---|
41 | </tr>
|
---|
42 | <tr>
|
---|
43 | <td valign="top">name</td>
|
---|
44 | <td valign="top">the name of the project.</td>
|
---|
45 | <td align="center" valign="top">No</td>
|
---|
46 | </tr>
|
---|
47 | <tr>
|
---|
48 | <td valign="top">default</td>
|
---|
49 | <td valign="top">the default target to use when no target is supplied.</td>
|
---|
50 | <td align="center" valign="top">No; however, <b>since Ant 1.6.0</b>,
|
---|
51 | every project includes an implicit target that contains any and
|
---|
52 | all top-level tasks and/or types. This target will always be
|
---|
53 | executed as part of the project's initialization, even when Ant is
|
---|
54 | run with the <a href="running.html#options">-projecthelp</a> option.
|
---|
55 | </td>
|
---|
56 | </tr>
|
---|
57 | <tr>
|
---|
58 | <td valign="top">basedir</td>
|
---|
59 | <td valign="top">the base directory from which all path calculations are
|
---|
60 | done. This attribute might be overridden by setting
|
---|
61 | the "basedir"
|
---|
62 | property beforehand. When this is done, it must be omitted in the
|
---|
63 | project tag. If neither the attribute nor the property have
|
---|
64 | been set, the parent directory of the buildfile will be used.</td>
|
---|
65 | <td align="center" valign="top">No</td>
|
---|
66 | </tr>
|
---|
67 | </table>
|
---|
68 | <p>Optionally, a description for the project can be provided as a
|
---|
69 | top-level <code><description></code> element (see the <a
|
---|
70 | href="CoreTypes/description.html">description</a> type).</p>
|
---|
71 |
|
---|
72 | <p>Each project defines one or more <i>targets</i>.
|
---|
73 | A target is a set of <i>tasks</i> you want
|
---|
74 | to be executed. When starting Ant, you can select which target(s) you
|
---|
75 | want to have executed. When no target is given,
|
---|
76 | the project's default is used.</p>
|
---|
77 |
|
---|
78 | <h3><a name="targets">Targets</a></h3>
|
---|
79 | <p>A target can depend on other targets. You might have a target for compiling,
|
---|
80 | for example, and a target for creating a distributable. You can only build a
|
---|
81 | distributable when you have compiled first, so the distribute target
|
---|
82 | <i>depends on</i> the compile target. Ant resolves these dependencies.</p>
|
---|
83 | <p>It should be noted, however, that Ant's <code>depends</code> attribute
|
---|
84 | only specifies the <i>order</i> in which targets should be executed - it
|
---|
85 | does not affect whether the target that specifies the dependency(s) gets
|
---|
86 | executed if the dependent target(s) did not (need to) run.
|
---|
87 | </p>
|
---|
88 | <p>Ant tries to execute the targets in the <code>depends</code>
|
---|
89 | attribute in the order
|
---|
90 | they appear (from left to right). Keep in mind that it is possible that a target
|
---|
91 | can get executed earlier when an earlier target depends on it:</p>
|
---|
92 | <blockquote>
|
---|
93 | <pre><target name="A"/>
|
---|
94 | <target name="B" depends="A"/>
|
---|
95 | <target name="C" depends="B"/>
|
---|
96 | <target name="D" depends="C,B,A"/></pre>
|
---|
97 | </blockquote>
|
---|
98 | <p>Suppose we want to execute target D. From its
|
---|
99 | <code>depends</code> attribute, you
|
---|
100 | might think that first target C, then B and then A is executed.
|
---|
101 | Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.</p>
|
---|
102 | <p>In a chain of dependencies stretching back from a given target such
|
---|
103 | as D above, each target gets executed only once, even when more than
|
---|
104 | one target depends on it. Thus, executing the D target will first
|
---|
105 | result in C being called, which in turn will first call B, which in
|
---|
106 | turn will first call A. After A, then B, then C have executed,
|
---|
107 | execution returns to the dependency list of D, which will <u>not</u>
|
---|
108 | call B and A, since they were already called in process of dependency
|
---|
109 | resolution for C and B respectively as dependencies of D. Had no such
|
---|
110 | dependencies been discovered in processing C and B, B and A would
|
---|
111 | have been executed after C in processing D's dependency list.</p>
|
---|
112 | <p>A target also has the ability to perform its execution if (or
|
---|
113 | unless) a property has been set. This allows, for example, better
|
---|
114 | control on the building process depending on the state of the system
|
---|
115 | (java version, OS, command-line property defines, etc.). To make a target
|
---|
116 | <i>sense</i> this property, you should add the <code>if</code> (or
|
---|
117 | <code>unless</code>) attribute with the name of the property that the target
|
---|
118 | should react to. <strong>Note:</strong> Ant will only check whether
|
---|
119 | the property has been set, the value doesn't matter. A property set
|
---|
120 | to the empty string is still an existing property. For example:</p>
|
---|
121 | <blockquote>
|
---|
122 | <pre><target name="build-module-A" if="module-A-present"/></pre>
|
---|
123 | <pre><target name="build-own-fake-module-A" unless="module-A-present"/></pre>
|
---|
124 | </blockquote>
|
---|
125 | <p>In the first example, if the <code>module-A-present</code>
|
---|
126 | property is set (to any value, e.g. <i>false</i>), the target will be run. In the second
|
---|
127 | example, if the <code>module-A-present</code> property is set
|
---|
128 | (again, to any value), the target will not be run.
|
---|
129 | </p>
|
---|
130 | <p>Only one propertyname can be specified in the if/unless clause. If you want to check
|
---|
131 | multiple conditions, you can use a dependend target for computing the result for the check:</p>
|
---|
132 | <blockquote><pre>
|
---|
133 | <target name="myTarget" depends="myTarget.check" if="myTarget.run">
|
---|
134 | <echo>Files foo.txt and bar.txt are present.</echo>
|
---|
135 | </target>
|
---|
136 |
|
---|
137 | <target name="myTarget.check">
|
---|
138 | <condition property="myTarget.run">
|
---|
139 | <and>
|
---|
140 | <available file="foo.txt"/>
|
---|
141 | <available file="bar.txt"/>
|
---|
142 | </and>
|
---|
143 | </condition>
|
---|
144 | </target>
|
---|
145 | </pre></blockquote>
|
---|
146 | <p>If no <code>if</code> and no <code>unless</code> attribute is present,
|
---|
147 | the target will always be executed.</p>
|
---|
148 |
|
---|
149 | <p>
|
---|
150 | <b>Important:</b> the <code>if</code> and <code>unless</code> attributes only
|
---|
151 | enable or disable the target to which they are attached. They do not control
|
---|
152 | whether or not targets that a conditional target depends upon get executed.
|
---|
153 | In fact, they do not even get evaluated until the target is about to be executed,
|
---|
154 | and all its predecessors have already run.
|
---|
155 |
|
---|
156 | <p>The optional <code>description</code> attribute can be used to provide a one-line description of this target, which is printed by the
|
---|
157 | <nobr><code>-projecthelp</code></nobr> command-line option. Targets
|
---|
158 | without such a description are deemed internal and will not be listed,
|
---|
159 | unless either the <nobr><code>-verbose</code></nobr> or
|
---|
160 | <nobr><code>-debug</code></nobr> option is used.
|
---|
161 | </p>
|
---|
162 | <p>It is a good practice to place your <a
|
---|
163 | href="CoreTasks/tstamp.html">tstamp</a> tasks in a so-called
|
---|
164 | <i>initialization</i> target, on which
|
---|
165 | all other targets depend. Make sure that target is always the first one in
|
---|
166 | the depends list of the other targets. In this manual, most initialization targets
|
---|
167 | have the name <code>"init"</code>.</p>
|
---|
168 | <p>If the depends attribute and the if/unless attribute are set, the depends attribute is
|
---|
169 | executed first.</p>
|
---|
170 | <p>A target has the following attributes:</p>
|
---|
171 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
172 | <tr>
|
---|
173 | <td valign="top"><b>Attribute</b></td>
|
---|
174 | <td valign="top"><b>Description</b></td>
|
---|
175 | <td align="center" valign="top"><b>Required</b></td>
|
---|
176 | </tr>
|
---|
177 | <tr>
|
---|
178 | <td valign="top">name</td>
|
---|
179 | <td valign="top">the name of the target.</td>
|
---|
180 | <td align="center" valign="top">Yes</td>
|
---|
181 | </tr>
|
---|
182 | <tr>
|
---|
183 | <td valign="top">depends</td>
|
---|
184 | <td valign="top">a comma-separated list of names of targets on which this
|
---|
185 | target depends.</td>
|
---|
186 | <td align="center" valign="top">No</td>
|
---|
187 | </tr>
|
---|
188 | <tr>
|
---|
189 | <td valign="top">if</td>
|
---|
190 | <td valign="top">the name of the property that must be set in order for this
|
---|
191 | target to execute.</td>
|
---|
192 | <td align="center" valign="top">No</td>
|
---|
193 | </tr>
|
---|
194 | <tr>
|
---|
195 | <td valign="top">unless</td>
|
---|
196 | <td valign="top">the name of the property that must not be set in order
|
---|
197 | for this target to execute.</td>
|
---|
198 | <td align="center" valign="top">No</td>
|
---|
199 | </tr>
|
---|
200 | <tr>
|
---|
201 | <td valign="top">description</td>
|
---|
202 | <td valign="top">a short description of this target's function.</td>
|
---|
203 | <td align="center" valign="top">No</td>
|
---|
204 | </tr>
|
---|
205 | </table>
|
---|
206 | </p>
|
---|
207 |
|
---|
208 | <p>A target name can be any alphanumeric string valid in the encoding of the XML
|
---|
209 | file. The empty string "" is in this set, as is
|
---|
210 | comma "," and space " ".
|
---|
211 | Please avoid using these, as they will not be supported in future Ant versions
|
---|
212 | because of all the confusion they cause. IDE support of unusual target names,
|
---|
213 | or any target name containing spaces, varies with the IDE.</p>
|
---|
214 |
|
---|
215 | <p>Targets beginning with a hyphen such as <code>"-restart"</code>
|
---|
216 | are valid, and can be used
|
---|
217 | to name targets that should not be called directly from the command line.</p>
|
---|
218 |
|
---|
219 | <h3><a name="tasks">Tasks</a></h3>
|
---|
220 | <p>A task is a piece of code that can be executed.</p>
|
---|
221 | <p>A task can have multiple attributes (or arguments, if you prefer). The value
|
---|
222 | of an attribute might contain references to a property. These references will be
|
---|
223 | resolved before the task is executed.</p>
|
---|
224 | <p>Tasks have a common structure:</p>
|
---|
225 | <blockquote>
|
---|
226 | <pre><<i>name</i> <i>attribute1</i>="<i>value1</i>" <i>attribute2</i>="<i>value2</i>" ... /></pre>
|
---|
227 | </blockquote>
|
---|
228 | <p>where <i>name</i> is the name of the task,
|
---|
229 | <i>attributeN</i> is the attribute name, and
|
---|
230 | <i>valueN</i> is the value for this attribute.</p>
|
---|
231 | <p>There is a set of <a href="coretasklist.html" target="navFrame">built-in tasks</a>, along with a
|
---|
232 | number of
|
---|
233 | <a href="optionaltasklist.html" target="navFrame"> optional tasks</a>, but it is also very
|
---|
234 | easy to <a href="develop.html#writingowntask">write your own</a>.</p>
|
---|
235 | <p>All tasks share a task name attribute. The value of
|
---|
236 | this attribute will be used in the logging messages generated by
|
---|
237 | Ant.</p>
|
---|
238 | Tasks can be assigned an <code>id</code> attribute:
|
---|
239 | <blockquote>
|
---|
240 | <pre><<i>taskname</i> id="<i>taskID</i>" ... /></pre>
|
---|
241 | </blockquote>
|
---|
242 | where <i>taskname</i> is the name of the task, and <i>taskID</i> is
|
---|
243 | a unique identifier for this task.
|
---|
244 | You can refer to the
|
---|
245 | corresponding task object in scripts or other tasks via this name.
|
---|
246 | For example, in scripts you could do:
|
---|
247 | <blockquote>
|
---|
248 | <pre>
|
---|
249 | <script ... >
|
---|
250 | task1.setFoo("bar");
|
---|
251 | </script>
|
---|
252 | </pre>
|
---|
253 | </blockquote>
|
---|
254 | to set the <code>foo</code> attribute of this particular task instance.
|
---|
255 | In another task (written in Java), you can access the instance via
|
---|
256 | <code>project.getReference("task1")</code>.
|
---|
257 | <p>
|
---|
258 | Note<sup>1</sup>: If "task1" has not been run yet, then
|
---|
259 | it has not been configured (ie., no attributes have been set), and if it is
|
---|
260 | going to be configured later, anything you've done to the instance may
|
---|
261 | be overwritten.
|
---|
262 | </p>
|
---|
263 | <p>
|
---|
264 | Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i>
|
---|
265 | be backward-compatible with this behaviour, since there will likely be no
|
---|
266 | task instances at all, only proxies.
|
---|
267 | </p>
|
---|
268 |
|
---|
269 | <h3><a name="properties">Properties</a></h3>
|
---|
270 | <p>A project can have a set of properties. These might be set in the buildfile
|
---|
271 | by the <a href="CoreTasks/property.html">property</a> task, or might be set outside Ant. A
|
---|
272 | property has a name and a value; the name is case-sensitive. Properties may be used in the value of
|
---|
273 | task attributes. This is done by placing the property name between
|
---|
274 | "<code>${</code>" and "<code>}</code>" in the
|
---|
275 | attribute value. For example,
|
---|
276 | if there is a "builddir" property with the value
|
---|
277 | "build", then this could be used in an attribute like this:
|
---|
278 | <code>${builddir}/classes</code>.
|
---|
279 | This is resolved at run-time as <code>build/classes</code>.</p>
|
---|
280 | <p>In the event you should need to include this construct literally
|
---|
281 | (i.e. without property substitutions), simply "escape" the '$' character
|
---|
282 | by doubling it. To continue the previous example:
|
---|
283 | <pre> <echo>$${builddir}=${builddir}</echo></pre>
|
---|
284 | will echo this message:
|
---|
285 | <pre> ${builddir}=build/classes</pre></p>
|
---|
286 | <p>In order to maintain backward compatibility with older Ant releases,
|
---|
287 | a single '$' character encountered apart from a property-like construct
|
---|
288 | (including a matched pair of french braces) will be interpreted literally;
|
---|
289 | that is, as '$'. The "correct" way to specify this literal character,
|
---|
290 | however, is by using the escaping mechanism unconditionally, so that "$$"
|
---|
291 | is obtained by specifying "$$$$". Mixing the two approaches yields
|
---|
292 | unpredictable results, as "$$$" results in "$$".</p>
|
---|
293 |
|
---|
294 | <h3><a name="built-in-props">Built-in Properties</a></h3>
|
---|
295 | <p>Ant provides access to all system properties as if they had been
|
---|
296 | defined using a <code><property></code> task.
|
---|
297 | For example, <code>${os.name}</code> expands to the
|
---|
298 | name of the operating system.</p>
|
---|
299 | <p>For a list of system properties see
|
---|
300 | <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
|
---|
301 | </p>
|
---|
302 | <p>In addition, Ant has some built-in properties:</p>
|
---|
303 | <pre>
|
---|
304 | basedir the absolute path of the project's basedir (as set
|
---|
305 | with the basedir attribute of <a href="#projects"><project>)</a>.
|
---|
306 | ant.file the absolute path of the buildfile.
|
---|
307 | ant.version the version of Ant
|
---|
308 | ant.project.name the name of the project that is currently executing;
|
---|
309 | it is set in the name attribute of <project>.
|
---|
310 | ant.java.version the JVM version Ant detected; currently it can hold
|
---|
311 | the values "1.2", "1.3", "1.4" and "1.5".
|
---|
312 | </pre>
|
---|
313 | <p>There is also another property, but this is set by the launcher script and therefore
|
---|
314 | maybe not set inside IDEs:</p>
|
---|
315 | <pre>
|
---|
316 | ant.home home directory of Ant
|
---|
317 | </pre>
|
---|
318 |
|
---|
319 | <a name="example"><h3>Example Buildfile</h3></a>
|
---|
320 | <pre>
|
---|
321 | <project name="MyProject" default="dist" basedir=".">
|
---|
322 | <description>
|
---|
323 | simple example build file
|
---|
324 | </description>
|
---|
325 | <!-- set global properties for this build -->
|
---|
326 | <property name="src" location="src"/>
|
---|
327 | <property name="build" location="build"/>
|
---|
328 | <property name="dist" location="dist"/>
|
---|
329 |
|
---|
330 | <target name="init">
|
---|
331 | <!-- Create the time stamp -->
|
---|
332 | <tstamp/>
|
---|
333 | <!-- Create the build directory structure used by compile -->
|
---|
334 | <mkdir dir="${build}"/>
|
---|
335 | </target>
|
---|
336 |
|
---|
337 | <target name="compile" depends="init"
|
---|
338 | description="compile the source " >
|
---|
339 | <!-- Compile the java code from ${src} into ${build} -->
|
---|
340 | <javac srcdir="${src}" destdir="${build}"/>
|
---|
341 | </target>
|
---|
342 |
|
---|
343 | <target name="dist" depends="compile"
|
---|
344 | description="generate the distribution" >
|
---|
345 | <!-- Create the distribution directory -->
|
---|
346 | <mkdir dir="${dist}/lib"/>
|
---|
347 |
|
---|
348 | <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
|
---|
349 | <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
|
---|
350 | </target>
|
---|
351 |
|
---|
352 | <target name="clean"
|
---|
353 | description="clean up" >
|
---|
354 | <!-- Delete the ${build} and ${dist} directory trees -->
|
---|
355 | <delete dir="${build}"/>
|
---|
356 | <delete dir="${dist}"/>
|
---|
357 | </target>
|
---|
358 | </project>
|
---|
359 | </pre>
|
---|
360 |
|
---|
361 | <p>Notice that we are declaring properties outside any target. As of
|
---|
362 | Ant 1.6 all tasks can be declared outside targets (earlier version
|
---|
363 | only allowed <tt><property></tt>,<tt><typedef></tt> and
|
---|
364 | <tt><taskdef></tt>). When you do this they are evaluated before
|
---|
365 | any targets are executed. Some tasks will generate build failures if
|
---|
366 | they are used outside of targets as they may cause infinite loops
|
---|
367 | otherwise (<code><antcall></code> for example).</p>
|
---|
368 |
|
---|
369 | <p>
|
---|
370 | We have given some targets descriptions; this causes the <tt>projecthelp</tt>
|
---|
371 | invocation option to list them as public targets with the descriptions; the
|
---|
372 | other target is internal and not listed.
|
---|
373 | <p>
|
---|
374 | Finally, for this target to work the source in the <tt>src</tt> subdirectory
|
---|
375 | should be stored in a directory tree which matches the package names. Check the
|
---|
376 | <tt><javac></tt> task for details.
|
---|
377 |
|
---|
378 | <a name="filters"><h3>Token Filters</h3></a>
|
---|
379 | <p>A project can have a set of tokens that might be automatically expanded if
|
---|
380 | found when a file is copied, when the filtering-copy behavior is selected in the
|
---|
381 | tasks that support this. These might be set in the buildfile
|
---|
382 | by the <a href="CoreTasks/filter.html">filter</a> task.</p>
|
---|
383 | <p>Since this can potentially be a very harmful behavior,
|
---|
384 | the tokens in the files <b>must</b>
|
---|
385 | be of the form <code>@</code><i>token</i><code>@</code>, where
|
---|
386 | <i>token</i> is the token name that is set
|
---|
387 | in the <code><filter></code> task. This token syntax matches the syntax of other build systems
|
---|
388 | that perform such filtering and remains sufficiently orthogonal to most
|
---|
389 | programming and scripting languages, as well as with documentation systems.</p>
|
---|
390 | <p>Note: If a token with the format <code>@</code><i>token</i><code>@</code>
|
---|
391 | is found in a file, but no
|
---|
392 | filter is associated with that token, no changes take place;
|
---|
393 | therefore, no escaping
|
---|
394 | method is available - but as long as you choose appropriate names for your
|
---|
395 | tokens, this should not cause problems.</p>
|
---|
396 | <p><b>Warning:</b> If you copy binary files with filtering turned on, you can corrupt the
|
---|
397 | files. This feature should be used with text files <em>only</em>.</p>
|
---|
398 |
|
---|
399 | <h3><a name="path">Path-like Structures</a></h3>
|
---|
400 | <p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type
|
---|
401 | references using both
|
---|
402 | "<code>:</code>" and "<code>;</code>" as separator
|
---|
403 | characters. Ant will
|
---|
404 | convert the separator to the correct character of the current operating
|
---|
405 | system.</p>
|
---|
406 | <p>Wherever path-like values need to be specified, a nested element can
|
---|
407 | be used. This takes the general form of:</p>
|
---|
408 | <pre>
|
---|
409 | <classpath>
|
---|
410 | <pathelement path="${classpath}"/>
|
---|
411 | <pathelement location="lib/helper.jar"/>
|
---|
412 | </classpath>
|
---|
413 | </pre>
|
---|
414 | <p>The <code>location</code> attribute specifies a single file or
|
---|
415 | directory relative to the project's base directory (or an absolute
|
---|
416 | filename), while the <code>path</code> attribute accepts colon-
|
---|
417 | or semicolon-separated lists of locations. The <code>path</code>
|
---|
418 | attribute is intended to be used with predefined paths - in any other
|
---|
419 | case, multiple elements with <code>location</code> attributes should be
|
---|
420 | preferred.</p>
|
---|
421 | <p>As a shortcut, the <code><classpath></code> tag
|
---|
422 | supports <code>path</code> and
|
---|
423 | <code>location</code> attributes of its own, so:</p>
|
---|
424 | <pre>
|
---|
425 | <classpath>
|
---|
426 | <pathelement path="${classpath}"/>
|
---|
427 | </classpath>
|
---|
428 | </pre>
|
---|
429 | <p>can be abbreviated to:</p>
|
---|
430 | <pre>
|
---|
431 | <classpath path="${classpath}"/>
|
---|
432 | </pre>
|
---|
433 | <p>In addition, one or more
|
---|
434 | <a href="CoreTypes/resources.html#collection">Resource Collection</a>s
|
---|
435 | can be specified as nested elements (these must consist of
|
---|
436 | <a href="CoreTypes/resources.html#file">file</a>-type resources only).
|
---|
437 | Additionally, it should be noted that although resource collections are
|
---|
438 | processed in the order encountered, certain resource collection types
|
---|
439 | such as <a href="CoreTypes/fileset.html">fileset</a>,
|
---|
440 | <a href="CoreTypes/dirset.html">dirset</a> and
|
---|
441 | <a href="CoreTypes/resources.html#files">files</a>
|
---|
442 | are undefined in terms of order.</p>
|
---|
443 | <pre>
|
---|
444 | <classpath>
|
---|
445 | <pathelement path="${classpath}"/>
|
---|
446 | <fileset dir="lib">
|
---|
447 | <include name="**/*.jar"/>
|
---|
448 | </fileset>
|
---|
449 | <pathelement location="classes"/>
|
---|
450 | <dirset dir="${build.dir}">
|
---|
451 | <include name="apps/**/classes"/>
|
---|
452 | <exclude name="apps/**/*Test*"/>
|
---|
453 | </dirset>
|
---|
454 | <filelist refid="third-party_jars"/>
|
---|
455 | </classpath>
|
---|
456 | </pre>
|
---|
457 | <p>This builds a path that holds the value of <code>${classpath}</code>,
|
---|
458 | followed by all jar files in the <code>lib</code> directory,
|
---|
459 | the <code>classes</code> directory, all directories named
|
---|
460 | <code>classes</code> under the <code>apps</code> subdirectory of
|
---|
461 | <code>${build.dir}</code>, except those
|
---|
462 | that have the text <code>Test</code> in their name, and
|
---|
463 | the files specified in the referenced FileList.</p>
|
---|
464 | <p>If you want to use the same path-like structure for several tasks,
|
---|
465 | you can define them with a <code><path></code> element at the
|
---|
466 | same level as <i>target</i>s, and reference them via their
|
---|
467 | <i>id</i> attribute--see <a href="#references">References</a> for an
|
---|
468 | example.</p>
|
---|
469 | <p>A path-like structure can include a reference to another path-like
|
---|
470 | structure (a path being itself a resource collection)
|
---|
471 | via nested <code><path></code> elements:</p>
|
---|
472 | <pre>
|
---|
473 | <path id="base.path">
|
---|
474 | <pathelement path="${classpath}"/>
|
---|
475 | <fileset dir="lib">
|
---|
476 | <include name="**/*.jar"/>
|
---|
477 | </fileset>
|
---|
478 | <pathelement location="classes"/>
|
---|
479 | </path>
|
---|
480 |
|
---|
481 | <path id="tests.path">
|
---|
482 | <path refid="base.path"/>
|
---|
483 | <pathelement location="testclasses"/>
|
---|
484 | </path>
|
---|
485 | </pre>
|
---|
486 | The shortcuts previously mentioned for <code><classpath></code> are also valid for <code><path></code>.For example:
|
---|
487 | <pre>
|
---|
488 | <path id="base.path">
|
---|
489 | <pathelement path="${classpath}"/>
|
---|
490 | </path>
|
---|
491 | </pre>
|
---|
492 | can be written as:
|
---|
493 | <pre>
|
---|
494 | <path id="base.path" path="${classpath}"/>
|
---|
495 | </pre>
|
---|
496 |
|
---|
497 | <h3><a name="arg">Command-line Arguments</a></h3>
|
---|
498 | <p>Several tasks take arguments that will be passed to another
|
---|
499 | process on the command line. To make it easier to specify arguments
|
---|
500 | that contain space characters, nested <code>arg</code> elements can be used.</p>
|
---|
501 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
502 | <tr>
|
---|
503 | <td width="12%" valign="top"><b>Attribute</b></td>
|
---|
504 | <td width="78%" valign="top"><b>Description</b></td>
|
---|
505 | <td width="10%" valign="top"><b>Required</b></td>
|
---|
506 | </tr>
|
---|
507 | <tr>
|
---|
508 | <td valign="top">value</td>
|
---|
509 | <td valign="top">a single command-line argument; can contain space
|
---|
510 | characters.</td>
|
---|
511 | <td align="center" rowspan="5">Exactly one of these.</td>
|
---|
512 | </tr>
|
---|
513 | <tr>
|
---|
514 | <td valign="top">file</td>
|
---|
515 | <td valign="top">The name of a file as a single command-line
|
---|
516 | argument; will be replaced with the absolute filename of the file.</td>
|
---|
517 | </tr>
|
---|
518 | <tr>
|
---|
519 | <td valign="top">path</td>
|
---|
520 | <td valign="top">A string that will be treated as a path-like
|
---|
521 | string as a single command-line argument; you can use <code>;</code>
|
---|
522 | or <code>:</code> as
|
---|
523 | path separators and Ant will convert it to the platform's local
|
---|
524 | conventions.</td>
|
---|
525 | </tr>
|
---|
526 | <tr>
|
---|
527 | <td valign="top">pathref</td>
|
---|
528 | <td valign="top"><a href="#references">Reference</a> to a path
|
---|
529 | defined elsewhere. Ant will convert it to the platform's local
|
---|
530 | conventions.</td>
|
---|
531 | </tr>
|
---|
532 | <tr>
|
---|
533 | <td valign="top">line</td>
|
---|
534 | <td valign="top">a space-delimited list of command-line arguments.</td>
|
---|
535 | </tr>
|
---|
536 | </table>
|
---|
537 |
|
---|
538 | <p>It is highly recommended to avoid the <code>line</code> version
|
---|
539 | when possible. Ant will try to split the command line in a way
|
---|
540 | similar to what a (Unix) shell would do, but may create something that
|
---|
541 | is very different from what you expect under some circumstances.</p>
|
---|
542 |
|
---|
543 | <h4>Examples</h4>
|
---|
544 | <blockquote><pre>
|
---|
545 | <arg value="-l -a"/>
|
---|
546 | </pre></blockquote>
|
---|
547 | <p>is a single command-line argument containing a space character,
|
---|
548 | <i>not</i> separate commands "-l" and "-a".</p>
|
---|
549 | <blockquote><pre>
|
---|
550 | <arg line="-l -a"/>
|
---|
551 | </pre></blockquote>
|
---|
552 | <p>This is a command line with two separate arguments, "-l" and "-a".</p>
|
---|
553 | <blockquote><pre>
|
---|
554 | <arg path="/dir;/dir2:\dir3"/>
|
---|
555 | </pre></blockquote>
|
---|
556 | <p>is a single command-line argument with the value
|
---|
557 | <code>\dir;\dir2;\dir3</code> on DOS-based systems and
|
---|
558 | <code>/dir:/dir2:/dir3</code> on Unix-like systems.</p>
|
---|
559 |
|
---|
560 | <h3><a name="references">References</a></h3>
|
---|
561 |
|
---|
562 | <p>Any project element can be assigned an identifier using its
|
---|
563 | <code>id</code> attribute. In most cases the element can subsequently
|
---|
564 | be referenced by specifying the <code>refid</code> attribute on an
|
---|
565 | element of the same type. This can be useful if you are going to
|
---|
566 | replicate the same snippet of XML over and over again--using a
|
---|
567 | <code><classpath></code> structure more than once, for example.</p>
|
---|
568 | <p>The following example:</p>
|
---|
569 | <blockquote><pre>
|
---|
570 | <project ... >
|
---|
571 | <target ... >
|
---|
572 | <rmic ...>
|
---|
573 | <classpath>
|
---|
574 | <pathelement location="lib/"/>
|
---|
575 | <pathelement path="${java.class.path}/"/>
|
---|
576 | <pathelement path="${additional.path}"/>
|
---|
577 | </classpath>
|
---|
578 | </rmic>
|
---|
579 | </target>
|
---|
580 |
|
---|
581 | <target ... >
|
---|
582 | <javac ...>
|
---|
583 | <classpath>
|
---|
584 | <pathelement location="lib/"/>
|
---|
585 | <pathelement path="${java.class.path}/"/>
|
---|
586 | <pathelement path="${additional.path}"/>
|
---|
587 | </classpath>
|
---|
588 | </javac>
|
---|
589 | </target>
|
---|
590 | </project>
|
---|
591 | </pre></blockquote>
|
---|
592 | <p>could be rewritten as:</p>
|
---|
593 | <blockquote><pre>
|
---|
594 | <project ... >
|
---|
595 | <path id="project.class.path">
|
---|
596 | <pathelement location="lib/"/>
|
---|
597 | <pathelement path="${java.class.path}/"/>
|
---|
598 | <pathelement path="${additional.path}"/>
|
---|
599 | </path>
|
---|
600 |
|
---|
601 | <target ... >
|
---|
602 | <rmic ...>
|
---|
603 | <classpath refid="project.class.path"/>
|
---|
604 | </rmic>
|
---|
605 | </target>
|
---|
606 |
|
---|
607 | <target ... >
|
---|
608 | <javac ...>
|
---|
609 | <classpath refid="project.class.path"/>
|
---|
610 | </javac>
|
---|
611 | </target>
|
---|
612 | </project>
|
---|
613 | </pre></blockquote>
|
---|
614 | <p>All tasks that use nested elements for
|
---|
615 | <a href="CoreTypes/patternset.html">PatternSet</a>s,
|
---|
616 | <a href="CoreTypes/fileset.html">FileSet</a>s,
|
---|
617 | <a href="CoreTypes/zipfileset.html">ZipFileSet</a>s or
|
---|
618 | <a href="#path">path-like structures</a> accept references to these structures
|
---|
619 | as shown in the examples. Using <code>refid</code> on a task will ordinarily
|
---|
620 | have the same effect (referencing a task already declared), but the user
|
---|
621 | should be aware that the interpretation of this attribute is dependent on the
|
---|
622 | implementation of the element upon which it is specified. Some tasks (the
|
---|
623 | <a href="CoreTasks/property.html">property</a> task is a handy example)
|
---|
624 | deliberately assign a different meaning to <code>refid</code>.</p>
|
---|
625 |
|
---|
626 |
|
---|
627 | <h3><a name="external-tasks">Use of external tasks</a></h3>
|
---|
628 | Ant supports a plugin mechanism for using third party tasks. For using them you
|
---|
629 | have to do two steps:
|
---|
630 | <ol>
|
---|
631 | <li>place their implementation somewhere where Ant can find them</li>
|
---|
632 | <li>declare them.</li>
|
---|
633 | </ol>
|
---|
634 | Don't add anything to the CLASSPATH environment variable - this is often the
|
---|
635 | reason for very obscure errors. Use Ant's own <a href="install.html#optionalTasks">mechanisms</a>
|
---|
636 | for adding libraries:
|
---|
637 | <ul>
|
---|
638 | <li>via command line argument <code>-lib</code></li>
|
---|
639 | <li>adding to <code>${user.home}/.ant/lib</code></li>
|
---|
640 | <li>adding to <code>${ant.home}/lib</code></li>
|
---|
641 | </ul>
|
---|
642 | For the declaration there are several ways:
|
---|
643 | <ul>
|
---|
644 | <li>declare a single task per using instruction using
|
---|
645 | <code><<a href="CoreTasks/taskdef.html">taskdef</a> name="taskname"
|
---|
646 | classname="ImplementationClass"/></code>
|
---|
647 | <br>
|
---|
648 | <code><taskdef name="for" classname="net.sf.antcontrib.logic.For" />
|
---|
649 | <for ... /></code>
|
---|
650 | </li>
|
---|
651 | <li>declare a bundle of tasks using a properties-file holding these
|
---|
652 | taskname-ImplementationClass-pairs and <code><taskdef></code>
|
---|
653 | <br>
|
---|
654 | <code><taskdef resource="net/sf/antcontrib/antcontrib.properties" />
|
---|
655 | <for ... /></code>
|
---|
656 | </li>
|
---|
657 | <li>declare a bundle of tasks using a <a href="CoreTypes/antlib.html">xml-file</a> holding these
|
---|
658 | taskname-ImplementationClass-pairs and <code><taskdef></code>
|
---|
659 | <br>
|
---|
660 | <code><taskdef resource="net/sf/antcontrib/antlib.xml" />
|
---|
661 | <for ... /></code>
|
---|
662 | </li>
|
---|
663 | <li>declare a bundle of tasks using a xml-file named antlib.xml, XML-namespace and
|
---|
664 | <a href="CoreTypes/antlib.html#antlibnamespace"><code>antlib:</code> protocoll handler</a>
|
---|
665 | <br>
|
---|
666 | <code><project xmlns:ac="antlib:net.sf.antconrib"/>
|
---|
667 | <ac:for ... /></code>
|
---|
668 | </li>
|
---|
669 | </ul>
|
---|
670 |
|
---|
671 | If you need a special function, you should
|
---|
672 | <ol>
|
---|
673 | <li>have a look at this manual, because Ant provides lot of tasks</li>
|
---|
674 | <li>have a look at the external task page in the <a href="../external.html">manual</a>
|
---|
675 | (or better <a href="http://ant.apache.org/external.html">online</a>)</li>
|
---|
676 | <li>have a look at the external task <a href="http://wiki.apache.org/ant/AntExternalTaskdefs">wiki
|
---|
677 | page</a></li>
|
---|
678 | <li>ask on the <a href="http://ant.apache.org/mail.html#User%20List">Ant user</a> list</li>
|
---|
679 | <li><a href="tutorial-writing-tasks.html">implement </a>(and share) your own</li>
|
---|
680 | </ol>
|
---|
681 |
|
---|
682 | </body>
|
---|
683 | </html>
|
---|