1 | <html>
|
---|
2 |
|
---|
3 | <head>
|
---|
4 | <meta http-equiv="Content-Language" content="en-us">
|
---|
5 | <title>Writing a Simple Buildfile</title>
|
---|
6 | <link rel="stylesheet" type="text/css" href="stylesheets/antmanual.css">
|
---|
7 | </head>
|
---|
8 |
|
---|
9 | <body>
|
---|
10 | <h1>Using Ant</h1>
|
---|
11 | <h2><a name="buildfile">Writing a Simple Buildfile</a></h2>
|
---|
12 | <p>Ant's buildfiles are written in XML. Each buildfile contains one project
|
---|
13 | and at least one (default) target. Targets contain task elements.
|
---|
14 | Each task element of the buildfile can have an <code>id</code> attribute and
|
---|
15 | can later be referred to by the value supplied to this. The value has
|
---|
16 | to be unique. (For additional information, see the
|
---|
17 | <a href="#tasks"> Tasks</a> section below.)</p>
|
---|
18 | <h3><a name="projects">Projects</a></h3>
|
---|
19 | <p>A <i>project</i> has three attributes:</p>
|
---|
20 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
21 | <tr>
|
---|
22 | <td valign="top"><b>Attribute</b></td>
|
---|
23 | <td valign="top"><b>Description</b></td>
|
---|
24 | <td align="center" valign="top"><b>Required</b></td>
|
---|
25 | </tr>
|
---|
26 | <tr>
|
---|
27 | <td valign="top">name</td>
|
---|
28 | <td valign="top">the name of the project.</td>
|
---|
29 | <td align="center" valign="top">No</td>
|
---|
30 | </tr>
|
---|
31 | <tr>
|
---|
32 | <td valign="top">default</td>
|
---|
33 | <td valign="top">the default target to use when no target is supplied.</td>
|
---|
34 | <td align="center" valign="top"><!-- No. No target will be run if omitted.--> Yes.</td>
|
---|
35 | </tr>
|
---|
36 | <tr>
|
---|
37 | <td valign="top">basedir</td>
|
---|
38 | <td valign="top">the base directory from which all path calculations are
|
---|
39 | done. This attribute might be overridden by setting
|
---|
40 | the "basedir"
|
---|
41 | property beforehand. When this is done, it must be omitted in the
|
---|
42 | project tag. If neither the attribute nor the property have
|
---|
43 | been set, the parent directory of the buildfile will be used.</td>
|
---|
44 | <td align="center" valign="top">No</td>
|
---|
45 | </tr>
|
---|
46 | </table>
|
---|
47 | <p>Optionally, a description for the project can be provided as a
|
---|
48 | top-level <code><description></code> element (see the <a
|
---|
49 | href="CoreTypes/description.html">description</a> type).</p>
|
---|
50 |
|
---|
51 | <p>Each project defines one or more <i>targets</i>.
|
---|
52 | A target is a set of <i>tasks</i> you want
|
---|
53 | to be executed. When starting Ant, you can select which target(s) you
|
---|
54 | want to have executed. When no target is given,
|
---|
55 | the project's default is used.</p>
|
---|
56 |
|
---|
57 | <h3><a name="targets">Targets</a></h3>
|
---|
58 | <p>A target can depend on other targets. You might have a target for compiling,
|
---|
59 | for example, and a target for creating a distributable. You can only build a
|
---|
60 | distributable when you have compiled first, so the distribute target
|
---|
61 | <i>depends on</i> the compile target. Ant resolves these dependencies.</p>
|
---|
62 | <p>It should be noted, however, that Ant's <code>depends</code> attribute
|
---|
63 | only specifies the <i>order</i> in which targets should be executed - it
|
---|
64 | does not affect whether the target that specifies the dependency(s) gets
|
---|
65 | executed if the dependent target(s) did not (need to) run.
|
---|
66 | </p>
|
---|
67 | <p>Ant tries to execute the targets in the <code>depends</code>
|
---|
68 | attribute in the order
|
---|
69 | they appear (from left to right). Keep in mind that it is possible that a target
|
---|
70 | can get executed earlier when an earlier target depends on it:</p>
|
---|
71 | <blockquote>
|
---|
72 | <pre><target name="A"/>
|
---|
73 | <target name="B" depends="A"/>
|
---|
74 | <target name="C" depends="B"/>
|
---|
75 | <target name="D" depends="C,B,A"/></pre>
|
---|
76 | </blockquote>
|
---|
77 | <p>Suppose we want to execute target D. From its
|
---|
78 | <code>depends</code> attribute, you
|
---|
79 | might think that first target C, then B and then A is executed.
|
---|
80 | Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.</p>
|
---|
81 | <p>In a chain of dependencies stretching back from a given target such
|
---|
82 | as D above, each target gets executed only once, even when more than
|
---|
83 | one target depends on it. Thus, executing the D target will first
|
---|
84 | result in C being called, which in turn will first call B, which in
|
---|
85 | turn will first call A. After A, then B, then C have executed,
|
---|
86 | execution returns to the dependency list of D, which will <u>not</u>
|
---|
87 | call B and A, since they were already called in process of dependency
|
---|
88 | resolution for C and B respectively as dependencies of D. Had no such
|
---|
89 | dependencies been discovered in processing C and B, B and A would
|
---|
90 | have been executed after C in processing D's dependency list.</p>
|
---|
91 | <p>A target also has the ability to perform its execution if (or
|
---|
92 | unless) a property has been set. This allows, for example, better
|
---|
93 | control on the building process depending on the state of the system
|
---|
94 | (java version, OS, command-line property defines, etc.). To make a target
|
---|
95 | <i>sense</i> this property, you should add the <code>if</code> (or
|
---|
96 | <code>unless</code>) attribute with the name of the property that the target
|
---|
97 | should react to. <strong>Note:</strong> Ant will only check whether
|
---|
98 | the property has been set, the value doesn't matter. A property set
|
---|
99 | to the empty string is still an existing property. For example:</p>
|
---|
100 | <blockquote>
|
---|
101 | <pre><target name="build-module-A" if="module-A-present"/></pre>
|
---|
102 | <pre><target name="build-own-fake-module-A" unless="module-A-present"/></pre>
|
---|
103 | </blockquote>
|
---|
104 | <p>In the first example, if the <code>module-A-present</code>
|
---|
105 | property is set (to any value), the target will be run. In the second
|
---|
106 | example, if the <code>module-A-present</code> property is set
|
---|
107 | (again, to any value), the target will not be run.
|
---|
108 | </p>
|
---|
109 | <p>If no <code>if</code> and no <code>unless</code> attribute is present,
|
---|
110 | the target will always be executed.</p>
|
---|
111 | <p>The optional <code>description</code> attribute can be used to provide a one-line description of this target, which is printed by the
|
---|
112 | <nobr><code>-projecthelp</code></nobr> command-line option. Targets
|
---|
113 | without such a description are deemed internal and will not be listed,
|
---|
114 | unless either the <nobr><code>-verbose</code></nobr> or
|
---|
115 | <nobr><code>-debug</code></nobr> option is used.
|
---|
116 | </p>
|
---|
117 | <p>It is a good practice to place your <a
|
---|
118 | href="CoreTasks/tstamp.html">tstamp</a> tasks in a so-called
|
---|
119 | <i>initialization</i> target, on which
|
---|
120 | all other targets depend. Make sure that target is always the first one in
|
---|
121 | the depends list of the other targets. In this manual, most initialization targets
|
---|
122 | have the name <code>"init"</code>.</p>
|
---|
123 | <p>If the depends attribute and the if/unless attribute are set, the depends attribute is
|
---|
124 | executed first.</p>
|
---|
125 | <p>A target has the following attributes:</p>
|
---|
126 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
127 | <tr>
|
---|
128 | <td valign="top"><b>Attribute</b></td>
|
---|
129 | <td valign="top"><b>Description</b></td>
|
---|
130 | <td align="center" valign="top"><b>Required</b></td>
|
---|
131 | </tr>
|
---|
132 | <tr>
|
---|
133 | <td valign="top">name</td>
|
---|
134 | <td valign="top">the name of the target.</td>
|
---|
135 | <td align="center" valign="top">Yes</td>
|
---|
136 | </tr>
|
---|
137 | <tr>
|
---|
138 | <td valign="top">depends</td>
|
---|
139 | <td valign="top">a comma-separated list of names of targets on which this
|
---|
140 | target depends.</td>
|
---|
141 | <td align="center" valign="top">No</td>
|
---|
142 | </tr>
|
---|
143 | <tr>
|
---|
144 | <td valign="top">if</td>
|
---|
145 | <td valign="top">the name of the property that must be set in order for this
|
---|
146 | target to execute.</td>
|
---|
147 | <td align="center" valign="top">No</td>
|
---|
148 | </tr>
|
---|
149 | <tr>
|
---|
150 | <td valign="top">unless</td>
|
---|
151 | <td valign="top">the name of the property that must not be set in order
|
---|
152 | for this target to execute.</td>
|
---|
153 | <td align="center" valign="top">No</td>
|
---|
154 | </tr>
|
---|
155 | <tr>
|
---|
156 | <td valign="top">description</td>
|
---|
157 | <td valign="top">a short description of this target's function.</td>
|
---|
158 | <td align="center" valign="top">No</td>
|
---|
159 | </tr>
|
---|
160 | </table>
|
---|
161 | </p>
|
---|
162 |
|
---|
163 | <p>A target name can be any alphanumeric string valid in the encoding of the XML
|
---|
164 | file. The empty string "" is in this set, as is
|
---|
165 | comma "," and space " ".
|
---|
166 | Please avoid using these, as they will not be supported in future Ant versions
|
---|
167 | because of all the confusion they cause. IDE support of unusual target names,
|
---|
168 | or any target name containing spaces, varies with the IDE.</p>
|
---|
169 |
|
---|
170 | <p>Targets beginning with a hyphen such as <code>"-restart"</code>
|
---|
171 | are valid, and can be used
|
---|
172 | to name targets that should not be called directly from the command line.</p>
|
---|
173 |
|
---|
174 | <h3><a name="tasks">Tasks</a></h3>
|
---|
175 | <p>A task is a piece of code that can be executed.</p>
|
---|
176 | <p>A task can have multiple attributes (or arguments, if you prefer). The value
|
---|
177 | of an attribute might contain references to a property. These references will be
|
---|
178 | resolved before the task is executed.</p>
|
---|
179 | <p>Tasks have a common structure:</p>
|
---|
180 | <blockquote>
|
---|
181 | <pre><<i>name</i> <i>attribute1</i>="<i>value1</i>" <i>attribute2</i>="<i>value2</i>" ... /></pre>
|
---|
182 | </blockquote>
|
---|
183 | <p>where <i>name</i> is the name of the task,
|
---|
184 | <i>attributeN</i> is the attribute name, and
|
---|
185 | <i>valueN</i> is the value for this attribute.</p>
|
---|
186 | <p>There is a set of <a href="coretasklist.html" target="navFrame">built-in tasks</a>, along with a
|
---|
187 | number of
|
---|
188 | <a href="optionaltasklist.html" target="navFrame"> optional tasks</a>, but it is also very
|
---|
189 | easy to <a href="develop.html#writingowntask">write your own</a>.</p>
|
---|
190 | <p>All tasks share a task name attribute. The value of
|
---|
191 | this attribute will be used in the logging messages generated by
|
---|
192 | Ant.</p>
|
---|
193 | Tasks can be assigned an <code>id</code> attribute:
|
---|
194 | <blockquote>
|
---|
195 | <pre><<i>taskname</i> id="<i>taskID</i>" ... /></pre>
|
---|
196 | </blockquote>
|
---|
197 | where <i>taskname</i> is the name of the task, and <i>taskID</i> is
|
---|
198 | a unique identifier for this task.
|
---|
199 | You can refer to the
|
---|
200 | corresponding task object in scripts or other tasks via this name.
|
---|
201 | For example, in scripts you could do:
|
---|
202 | <blockquote>
|
---|
203 | <pre>
|
---|
204 | <script ... >
|
---|
205 | task1.setFoo("bar");
|
---|
206 | </script>
|
---|
207 | </pre>
|
---|
208 | </blockquote>
|
---|
209 | to set the <code>foo</code> attribute of this particular task instance.
|
---|
210 | In another task (written in Java), you can access the instance via
|
---|
211 | <code>project.getReference("task1")</code>.
|
---|
212 | <p>
|
---|
213 | Note<sup>1</sup>: If "task1" has not been run yet, then
|
---|
214 | it has not been configured (ie., no attributes have been set), and if it is
|
---|
215 | going to be configured later, anything you've done to the instance may
|
---|
216 | be overwritten.
|
---|
217 | </p>
|
---|
218 | <p>
|
---|
219 | Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i>
|
---|
220 | be backward-compatible with this behaviour, since there will likely be no
|
---|
221 | task instances at all, only proxies.
|
---|
222 | </p>
|
---|
223 |
|
---|
224 | <h3><a name="properties">Properties</a></h3>
|
---|
225 | <p>A project can have a set of properties. These might be set in the buildfile
|
---|
226 | by the <a href="CoreTasks/property.html">property</a> task, or might be set outside Ant. A
|
---|
227 | property has a name and a value; the name is case-sensitive. Properties may be used in the value of
|
---|
228 | task attributes. This is done by placing the property name between
|
---|
229 | "<code>${</code>" and "<code>}</code>" in the
|
---|
230 | attribute value. For example,
|
---|
231 | if there is a "builddir" property with the value
|
---|
232 | "build", then this could be used in an attribute like this:
|
---|
233 | <code>${builddir}/classes</code>.
|
---|
234 | This is resolved at run-time as <code>build/classes</code>.</p>
|
---|
235 |
|
---|
236 | <h3><a name="built-in-props">Built-in Properties</a></h3>
|
---|
237 | <p>Ant provides access to all system properties as if they had been
|
---|
238 | defined using a <code><property></code> task.
|
---|
239 | For example, <code>${os.name}</code> expands to the
|
---|
240 | name of the operating system.</p>
|
---|
241 | <p>For a list of system properties see
|
---|
242 | <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
|
---|
243 | </p>
|
---|
244 | <p>In addition, Ant has some built-in properties:</p>
|
---|
245 | <pre>
|
---|
246 | basedir the absolute path of the project's basedir (as set
|
---|
247 | with the basedir attribute of <project>).
|
---|
248 | ant.file the absolute path of the buildfile.
|
---|
249 | ant.version the version of Ant
|
---|
250 | ant.project.name the name of the project that is currently executing;
|
---|
251 | it is set in the name attribute of <project>.
|
---|
252 | ant.java.version the JVM version Ant detected; currently it can hold
|
---|
253 | the values "1.1", "1.2", "1.3" and "1.4".
|
---|
254 | </pre>
|
---|
255 |
|
---|
256 | <a name="example"></a><h3>Example Buildfile</h3>
|
---|
257 | <pre>
|
---|
258 | <project name="MyProject" default="dist" basedir=".">
|
---|
259 | <description>
|
---|
260 | simple example build file
|
---|
261 | </description>
|
---|
262 | <!-- set global properties for this build -->
|
---|
263 | <property name="src" location="src"/>
|
---|
264 | <property name="build" location="build"/>
|
---|
265 | <property name="dist" location="dist"/>
|
---|
266 |
|
---|
267 | <target name="init">
|
---|
268 | <!-- Create the time stamp -->
|
---|
269 | <tstamp/>
|
---|
270 | <!-- Create the build directory structure used by compile -->
|
---|
271 | <mkdir dir="${build}"/>
|
---|
272 | </target>
|
---|
273 |
|
---|
274 | <target name="compile" depends="init"
|
---|
275 | description="compile the source " >
|
---|
276 | <!-- Compile the java code from ${src} into ${build} -->
|
---|
277 | <javac srcdir="${src}" destdir="${build}"/>
|
---|
278 | </target>
|
---|
279 |
|
---|
280 | <target name="dist" depends="compile"
|
---|
281 | description="generate the distribution" >
|
---|
282 | <!-- Create the distribution directory -->
|
---|
283 | <mkdir dir="${dist}/lib"/>
|
---|
284 |
|
---|
285 | <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
|
---|
286 | <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
|
---|
287 | </target>
|
---|
288 |
|
---|
289 | <target name="clean"
|
---|
290 | description="clean up" >
|
---|
291 | <!-- Delete the ${build} and ${dist} directory trees -->
|
---|
292 | <delete dir="${build}"/>
|
---|
293 | <delete dir="${dist}"/>
|
---|
294 | </target>
|
---|
295 | </project>
|
---|
296 | </pre>
|
---|
297 |
|
---|
298 | <p>Notice that we are declaring properties outside any target. As of
|
---|
299 | Ant 1.6 all tasks can be declared outside targets (earlier version
|
---|
300 | only allowed <tt><property></tt>,<tt><typedef></tt> and
|
---|
301 | <tt><taskdef></tt>). When you do this they are evaluated before
|
---|
302 | any targets are executed. Some tasks will generate build failures if
|
---|
303 | they are used outside of targets as they may cause infinite loops
|
---|
304 | otherwise (<code><antcall></code> for example).</p>
|
---|
305 |
|
---|
306 | <p>
|
---|
307 | We have given some targets descriptions; this causes the <tt>projecthelp</tt>
|
---|
308 | invocation option to list them as public targets with the descriptions; the
|
---|
309 | other target is internal and not listed.
|
---|
310 | <p>
|
---|
311 | Finally, for this target to work the source in the <tt>src</tt> subdirectory
|
---|
312 | should be stored in a directory tree which matches the package names. Check the
|
---|
313 | <tt><javac></tt> task for details.
|
---|
314 |
|
---|
315 | <a name="filters"></a><h3>Token Filters</h3>
|
---|
316 | <p>A project can have a set of tokens that might be automatically expanded if
|
---|
317 | found when a file is copied, when the filtering-copy behavior is selected in the
|
---|
318 | tasks that support this. These might be set in the buildfile
|
---|
319 | by the <a href="CoreTasks/filter.html">filter</a> task.</p>
|
---|
320 | <p>Since this can potentially be a very harmful behavior,
|
---|
321 | the tokens in the files <b>must</b>
|
---|
322 | be of the form <code>@</code><i>token</i><code>@</code>, where
|
---|
323 | <i>token</i> is the token name that is set
|
---|
324 | in the <code><filter></code> task. This token syntax matches the syntax of other build systems
|
---|
325 | that perform such filtering and remains sufficiently orthogonal to most
|
---|
326 | programming and scripting languages, as well as with documentation systems.</p>
|
---|
327 | <p>Note: If a token with the format <code>@</code><i>token</i><code>@</code>
|
---|
328 | is found in a file, but no
|
---|
329 | filter is associated with that token, no changes take place;
|
---|
330 | therefore, no escaping
|
---|
331 | method is available - but as long as you choose appropriate names for your
|
---|
332 | tokens, this should not cause problems.</p>
|
---|
333 | <p><b>Warning:</b> If you copy binary files with filtering turned on, you can corrupt the
|
---|
334 | files. This feature should be used with text files <em>only</em>.</p>
|
---|
335 |
|
---|
336 | <a name="path"></a><h3>Path-like Structures</h3>
|
---|
337 | <p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type
|
---|
338 | references using both
|
---|
339 | "<code>:</code>" and "<code>;</code>" as separator
|
---|
340 | characters. Ant will
|
---|
341 | convert the separator to the correct character of the current operating
|
---|
342 | system.</p>
|
---|
343 | <p>Wherever path-like values need to be specified, a nested element can
|
---|
344 | be used. This takes the general form of:</p>
|
---|
345 | <pre>
|
---|
346 | <classpath>
|
---|
347 | <pathelement path="${classpath}"/>
|
---|
348 | <pathelement location="lib/helper.jar"/>
|
---|
349 | </classpath>
|
---|
350 | </pre>
|
---|
351 | <p>The <code>location</code> attribute specifies a single file or
|
---|
352 | directory relative to the project's base directory (or an absolute
|
---|
353 | filename), while the <code>path</code> attribute accepts colon-
|
---|
354 | or semicolon-separated lists of locations. The <code>path</code>
|
---|
355 | attribute is intended to be used with predefined paths - in any other
|
---|
356 | case, multiple elements with <code>location</code> attributes should be
|
---|
357 | preferred.</p>
|
---|
358 | <p>As a shortcut, the <code><classpath></code> tag
|
---|
359 | supports <code>path</code> and
|
---|
360 | <code>location</code> attributes of its own, so:</p>
|
---|
361 | <pre>
|
---|
362 | <classpath>
|
---|
363 | <pathelement path="${classpath}"/>
|
---|
364 | </classpath>
|
---|
365 | </pre>
|
---|
366 | <p>can be abbreviated to:</p>
|
---|
367 | <pre>
|
---|
368 | <classpath path="${classpath}"/>
|
---|
369 | </pre>
|
---|
370 | <p>In addition, <a href="CoreTypes/dirset.html">DirSet</a>s,
|
---|
371 | <a href="CoreTypes/fileset.html">FileSet</a>s, and
|
---|
372 | <a href="CoreTypes/filelist.html">FileList</a>s
|
---|
373 | can be specified via nested <code><dirset></code>,
|
---|
374 | <code><fileset></code>, and <code><filelist></code>
|
---|
375 | elements, respectively. <em>Note</em>: The order in which the files
|
---|
376 | building up a FileSet are added to the path-like structure is not
|
---|
377 | defined.</p>
|
---|
378 | <pre>
|
---|
379 | <classpath>
|
---|
380 | <pathelement path="${classpath}"/>
|
---|
381 | <fileset dir="lib">
|
---|
382 | <include name="**/*.jar"/>
|
---|
383 | </fileset>
|
---|
384 | <pathelement location="classes"/>
|
---|
385 | <dirset dir="${build.dir}">
|
---|
386 | <include name="apps/**/classes"/>
|
---|
387 | <exclude name="apps/**/*Test*"/>
|
---|
388 | </dirset>
|
---|
389 | <filelist refid="third-party_jars"/>
|
---|
390 | </classpath>
|
---|
391 | </pre>
|
---|
392 | <p>This builds a path that holds the value of <code>${classpath}</code>,
|
---|
393 | followed by all jar files in the <code>lib</code> directory,
|
---|
394 | the <code>classes</code> directory, all directories named
|
---|
395 | <code>classes</code> under the <code>apps</code> subdirectory of
|
---|
396 | <code>${build.dir}</code>, except those
|
---|
397 | that have the text <code>Test</code> in their name, and
|
---|
398 | the files specified in the referenced FileList.</p>
|
---|
399 | <p>If you want to use the same path-like structure for several tasks,
|
---|
400 | you can define them with a <code><path></code> element at the
|
---|
401 | same level as <i>target</i>s, and reference them via their
|
---|
402 | <i>id</i> attribute - see <a href="#references">References</a> for an
|
---|
403 | example.</p>
|
---|
404 | <p>A path-like structure can include a reference to another path-like
|
---|
405 | structure via nested <code><path></code> elements:</p>
|
---|
406 | <pre>
|
---|
407 | <path id="base.path">
|
---|
408 | <pathelement path="${classpath}"/>
|
---|
409 | <fileset dir="lib">
|
---|
410 | <include name="**/*.jar"/>
|
---|
411 | </fileset>
|
---|
412 | <pathelement location="classes"/>
|
---|
413 | </path>
|
---|
414 |
|
---|
415 | <path id="tests.path">
|
---|
416 | <path refid="base.path"/>
|
---|
417 | <pathelement location="testclasses"/>
|
---|
418 | </path>
|
---|
419 | </pre>
|
---|
420 | The shortcuts previously mentioned for <code><classpath></code> are also valid for <code><path></code>.For example:
|
---|
421 | <pre>
|
---|
422 | <path id="base.path">
|
---|
423 | <pathelement path="${classpath}"/>
|
---|
424 | </path>
|
---|
425 | </pre>
|
---|
426 | can be written as:
|
---|
427 | <pre>
|
---|
428 | <path id="base.path" path="${classpath}"/>
|
---|
429 | </pre>
|
---|
430 |
|
---|
431 | <h3><a name="arg">Command-line Arguments</a></h3>
|
---|
432 | <p>Several tasks take arguments that will be passed to another
|
---|
433 | process on the command line. To make it easier to specify arguments
|
---|
434 | that contain space characters, nested <code>arg</code> elements can be used.</p>
|
---|
435 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
436 | <tr>
|
---|
437 | <td width="12%" valign="top"><b>Attribute</b></td>
|
---|
438 | <td width="78%" valign="top"><b>Description</b></td>
|
---|
439 | <td width="10%" valign="top"><b>Required</b></td>
|
---|
440 | </tr>
|
---|
441 | <tr>
|
---|
442 | <td valign="top">value</td>
|
---|
443 | <td valign="top">a single command-line argument; can contain space
|
---|
444 | characters.</td>
|
---|
445 | <td align="center" rowspan="5">Exactly one of these.</td>
|
---|
446 | </tr>
|
---|
447 | <tr>
|
---|
448 | <td valign="top">file</td>
|
---|
449 | <td valign="top">The name of a file as a single command-line
|
---|
450 | argument; will be replaced with the absolute filename of the file.</td>
|
---|
451 | </tr>
|
---|
452 | <tr>
|
---|
453 | <td valign="top">path</td>
|
---|
454 | <td valign="top">A string that will be treated as a path-like
|
---|
455 | string as a single command-line argument; you can use <code>;</code>
|
---|
456 | or <code>:</code> as
|
---|
457 | path separators and Ant will convert it to the platform's local
|
---|
458 | conventions.</td>
|
---|
459 | </tr>
|
---|
460 | <tr>
|
---|
461 | <td valign="top">pathref</td>
|
---|
462 | <td valign="top"><a href="#references">Reference</a> to a path
|
---|
463 | defined elsewhere. Ant will convert it to the platform's local
|
---|
464 | conventions.</td>
|
---|
465 | </tr>
|
---|
466 | <tr>
|
---|
467 | <td valign="top">line</td>
|
---|
468 | <td valign="top">a space-delimited list of command-line arguments.</td>
|
---|
469 | </tr>
|
---|
470 | </table>
|
---|
471 |
|
---|
472 | <p>It is highly recommended to avoid the <code>line</code> version
|
---|
473 | when possible. Ant will try to split the command line in a way
|
---|
474 | similar to what a (Unix) shell would do, but may create something that
|
---|
475 | is very different from what you expect under some circumstances.</p>
|
---|
476 |
|
---|
477 | <h4>Examples</h4>
|
---|
478 | <blockquote><pre>
|
---|
479 | <arg value="-l -a"/>
|
---|
480 | </pre></blockquote>
|
---|
481 | <p>is a single command-line argument containing a space character.</p>
|
---|
482 | <blockquote><pre>
|
---|
483 | <arg line="-l -a"/>
|
---|
484 | </pre></blockquote>
|
---|
485 | <p>represents two separate command-line arguments.</p>
|
---|
486 | <blockquote><pre>
|
---|
487 | <arg path="/dir;/dir2:\dir3"/>
|
---|
488 | </pre></blockquote>
|
---|
489 | <p>is a single command-line argument with the value
|
---|
490 | <code>\dir;\dir2;\dir3</code> on DOS-based systems and
|
---|
491 | <code>/dir:/dir2:/dir3</code> on Unix-like systems.</p>
|
---|
492 |
|
---|
493 | <h3><a name="references">References</a></h3>
|
---|
494 | <p>The <code>id</code> attribute of the buildfile's elements can be
|
---|
495 | used to refer to them. This can be useful if you are going to replicate
|
---|
496 | the same snippet of XML over and over again - using a
|
---|
497 | <code><classpath></code> structure more than once, for
|
---|
498 | example.</p>
|
---|
499 | <p>The following example:</p>
|
---|
500 | <blockquote><pre>
|
---|
501 | <project ... >
|
---|
502 | <target ... >
|
---|
503 | <rmic ...>
|
---|
504 | <classpath>
|
---|
505 | <pathelement location="lib/"/>
|
---|
506 | <pathelement path="${java.class.path}/"/>
|
---|
507 | <pathelement path="${additional.path}"/>
|
---|
508 | </classpath>
|
---|
509 | </rmic>
|
---|
510 | </target>
|
---|
511 |
|
---|
512 | <target ... >
|
---|
513 | <javac ...>
|
---|
514 | <classpath>
|
---|
515 | <pathelement location="lib/"/>
|
---|
516 | <pathelement path="${java.class.path}/"/>
|
---|
517 | <pathelement path="${additional.path}"/>
|
---|
518 | </classpath>
|
---|
519 | </javac>
|
---|
520 | </target>
|
---|
521 | </project>
|
---|
522 | </pre></blockquote>
|
---|
523 | <p>could be rewritten as:</p>
|
---|
524 | <blockquote><pre>
|
---|
525 | <project ... >
|
---|
526 | <path id="project.class.path">
|
---|
527 | <pathelement location="lib/"/>
|
---|
528 | <pathelement path="${java.class.path}/"/>
|
---|
529 | <pathelement path="${additional.path}"/>
|
---|
530 | </path>
|
---|
531 |
|
---|
532 | <target ... >
|
---|
533 | <rmic ...>
|
---|
534 | <classpath refid="project.class.path"/>
|
---|
535 | </rmic>
|
---|
536 | </target>
|
---|
537 |
|
---|
538 | <target ... >
|
---|
539 | <javac ...>
|
---|
540 | <classpath refid="project.class.path"/>
|
---|
541 | </javac>
|
---|
542 | </target>
|
---|
543 | </project>
|
---|
544 | </pre></blockquote>
|
---|
545 | <p>All tasks that use nested elements for <a
|
---|
546 | href="CoreTypes/patternset.html">PatternSet</a>s, <a href="CoreTypes/fileset.html">FileSet</a>s,
|
---|
547 | <a href="CoreTypes/zipfileset.html">ZipFileSet</a>s or
|
---|
548 | <a href="#path">path-like structures</a> accept references to these
|
---|
549 | structures as well.</p>
|
---|
550 |
|
---|
551 | <hr>
|
---|
552 | <p align="center">Copyright © 2000-2004 The Apache Software Foundation. All rights
|
---|
553 | Reserved.</p>
|
---|
554 |
|
---|
555 | </body>
|
---|
556 | </html>
|
---|