1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
<title>Writing a Simple Buildfile</title>
</head>
<body>
<h1>Using Apache Ant</h1>
<h2 id="buildfile">Writing a Simple Buildfile</h2>
<p>Apache Ant's buildfiles are written in XML. Each buildfile contains one project
and at least one (default) target. Targets contain task elements.
Each task element of the buildfile can have an <var>id</var> attribute and
can later be referred to by the value supplied to this. The value has
to be unique. (For additional information, see the
<a href="#tasks">Tasks</a> section below.)</p>
<h3 id="projects">Projects</h3>
<p>A <em>project</em> has three attributes:</p>
<table class="attr">
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>name</td>
<td>the name of the project.</td>
<td>No</td>
</tr>
<tr>
<td>default</td>
<td>the default target to use when no target is supplied.</td>
<td>No; however, <em>since Ant 1.6.0</em>,
every project includes an implicit target that contains any and
all top-level tasks and/or types. This target will always be
executed as part of the project's initialization, even when Ant is
run with the <a href="running.html#options"><code>-projecthelp</code></a> option.
</td>
</tr>
<tr>
<td>basedir</td>
<td>the base directory from which all path calculations are
done. A relative path is resolved relative to the directory containing
the buildfile.
</td>
<td>No; defaults to the parent directory of the buildfile,
unless overridden by the project's <var>basedir</var> or the <code>basedir</code>
property</td>
</tr>
</table>
<p>Optionally, a description for the project can be provided as a
top-level <code><description></code> element (see the <a
href="Types/description.html">description</a> type).</p>
<p>Each project defines one or more <em>targets</em>.
A target is a set of <em>tasks</em> you want
to be executed. When starting Ant, you can select which target(s) you
want to have executed. When no target is given,
the project's <var>default</var> is used.</p>
<h3 id="targets">Targets</h3>
<p>A target can depend on other targets. You might have a target for compiling,
for example, and a target for creating a distributable. You can only build a
distributable when you have compiled first, so the distribute target
<em>depends on</em> the compile target. Ant resolves these dependencies.</p>
<p>It should be noted, however, that Ant's <var>depends</var> attribute
only specifies the <em>order</em> in which targets should be executed—it
does not affect whether the target that specifies the dependency(s) gets
executed if the dependent target(s) did not (need to) run.
</p>
<p>More information can be found in the dedicated <a href="targets.html">manual page</a>.</p>
<h3 id="tasks">Tasks</h3>
<p>A task is a piece of code that can be executed.</p>
<p>A task can have multiple attributes (or arguments, if you prefer). The value
of an attribute might contain references to a property. These references will be
resolved before the task is executed.</p>
<p>Tasks have a common structure:</p>
<pre><<i>name</i> <var>attribute1</var>="<i>value1</i>" <var>attribute2</var>="<i>value2</i>" ... /></pre>
<p>where <code><i>name</i></code> is the name of the task,
<var>attributeN</var> is the attribute name, and
<code><i>valueN</i></code> is the value for this attribute.</p>
<p>There is a set of <a href="tasklist.html" target="navFrame">built-in tasks</a>, but it is also very
easy to <a href="develop.html#writingowntask">write your own</a>.</p>
<p>All tasks can have a <var>name</var> attribute. The value of
this attribute will be used in the logging messages generated by
Ant.</p>
Tasks can be assigned an <var>id</var> attribute:
<pre><<i>taskname</i> <var>id</var>="<i>taskID</i>" ... /></pre>
where <code><i>taskname</i></code> is the name of the task, and <code><i>taskID</i></code> is
a unique identifier for this task.
You can refer to the
corresponding task object in scripts or other tasks via this name.
For example, in scripts you could do:
<pre>
<script ... >
task1.setFoo("bar");
</script></pre>
to set the <code>foo</code> attribute of this particular task instance.
In another task (written in Java), you can access the instance via
<code>project.getReference("task1")</code>.
<p>
Note 1: If <q>task1</q> has not been run yet, then
it has not been configured (ie., no attributes have been set), and if it is
going to be configured later, anything you've done to the instance may
be overwritten.
</p>
<p>
Note 2: Future versions of Ant will most likely <em>not</em>
be backward-compatible with this behaviour, since there will likely be no
task instances at all, only proxies.
</p>
<h3 id="properties">Properties</h3>
<p>Properties are an important way to customize a build process or
to just provide shortcuts for strings that are used repeatedly
inside a buildfile.</p>
<p>In its most simple form properties are defined in the buildfile
(for example by the <a href="Tasks/property.html">property</a>
task) or might be set outside Ant. A property has a name and a
value; the name is case-sensitive. Properties may be used in the
value of task attributes or in the nested text of tasks that support
them. This is done by placing the property name between
<q>${</q> and <q>}</q> in the
attribute value. For example, if there is a <code>builddir</code>
property with the value <q>build</q>, then this could be used
in an attribute like this: <samp>${builddir}/classes</samp>. This
is resolved at run-time as <samp>build/classes</samp>.</p>
<p><em>Since Ant 1.8.0</em>, property expansion has become much more powerful
than simple key value pairs, more details can be
found <a href="properties.html">in the concepts section</a> of this
manual.</p>
<h3 id="example">Example Buildfile</h3>
<pre>
<project name="MyProject" default="dist" basedir=".">
<description>
simple example build file
</description>
<!-- set global properties for this build -->
<property name="src" location="src"/>
<property name="build" location="build"/>
<property name="dist" location="dist"/>
<target name="init">
<!-- Create the time stamp -->
<tstamp/>
<!-- Create the build directory structure used by compile -->
<mkdir dir="${build}"/>
</target>
<target name="compile" depends="init"
description="compile the source">
<!-- Compile the Java code from ${src} into ${build} -->
<javac srcdir="${src}" destdir="${build}"/>
</target>
<target name="dist" depends="compile"
description="generate the distribution">
<!-- Create the distribution directory -->
<mkdir dir="${dist}/lib"/>
<!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
<jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
</target>
<target name="clean"
description="clean up">
<!-- Delete the ${build} and ${dist} directory trees -->
<delete dir="${build}"/>
<delete dir="${dist}"/>
</target>
</project></pre>
<p>Notice that we are declaring properties outside any target. <em>Since
Ant 1.6</em>, all tasks can be declared outside targets (earlier version
only allowed <code><property></code>, <code><typedef></code> and
<code><taskdef></code>). When you do this they are evaluated before
any targets are executed. Some tasks will generate build failures if
they are used outside of targets as they may cause infinite loops
otherwise (<code><antcall></code> for example).</p>
<p>
We have given some targets descriptions; this causes the <code>-projecthelp</code>
invocation option to list them as public targets with the descriptions; the
other target is internal and not listed.
<p>
Finally, for this target to work the source in the <samp>src</samp> subdirectory
should be stored in a directory tree which matches the package names. Check the
<code><javac></code> task for details.
<h3 id="filters">Token Filters</h3>
<p>A project can have a set of tokens that might be automatically expanded if
found when a file is copied, when the filtering-copy behavior is selected in the
tasks that support this. These might be set in the buildfile
by the <a href="Tasks/filter.html">filter</a> task.</p>
<p>Since this can potentially be a very harmful behavior,
the tokens in the files <strong>must</strong>
be of the form <code>@<var>token</var>@</code>, where
<var>token</var> is the token name that is set
in the <code><filter></code> task. This token syntax matches the syntax of other build systems
that perform such filtering and remains sufficiently orthogonal to most
programming and scripting languages, as well as with documentation systems.</p>
<p><strong>Note</strong>: If a token with the format <code>@<var>token</var>@</code>
is found in a file, but no
filter is associated with that token, no changes take place;
therefore, no escaping
method is available—but as long as you choose appropriate names for your
tokens, this should not cause problems.</p>
<p><strong>Warning</strong>: If you copy binary files with filtering turned on, you can corrupt the
files. This feature should be used with text files <em>only</em>.</p>
<h3 id="path">Path-like Structures</h3>
<p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type
references using both <q>:</q> and <q>;</q> as separator
characters. Ant will
convert the separator to the correct character of the current operating
system.</p>
<p>Wherever path-like values need to be specified, a nested element can
be used. This takes the general form of:</p>
<pre>
<classpath>
<pathelement path="${classpath}"/>
<pathelement location="lib/helper.jar"/>
</classpath></pre>
<p>The <var>location</var> attribute specifies a single file or
directory relative to the project's base directory (or an absolute
filename), while the <var>path</var> attribute accepts colon-
or semicolon-separated lists of locations. The <var>path</var>
attribute is intended to be used with predefined paths—in any other
case, multiple elements with <var>location</var> attributes should be
preferred.</p>
<p><em>Since Ant 1.8.2</em> the <var>location</var> attribute can also contain a
wildcard in its last path component (i.e. it can end in a
<q>*</q>) in order to support wildcard <code>CLASSPATH</code>s introduced
with Java 6. Ant will not expand or evaluate the wildcards and the
resulting path may not work as anything else but a <code>CLASSPATH</code>—or
even as a <code>CLASSPATH</code> for JVM prior to Java 6.</p>
<p>As a shortcut, the <code><classpath></code> tag
supports <var>path</var> and
<var>location</var> attributes of its own, so:</p>
<pre>
<classpath>
<pathelement path="${classpath}"/>
</classpath>
</pre>
<p>can be abbreviated to:</p>
<pre><classpath path="${classpath}"/></pre>
<p>In addition, one or more
<a href="Types/resources.html#collection">resource collections</a>
can be specified as nested elements (these must consist of
<a href="Types/resources.html#file">file</a>-type resources only).
Additionally, it should be noted that although resource collections are
processed in the order encountered, certain resource collection types
such as <a href="Types/fileset.html">fileset</a>,
<a href="Types/dirset.html">dirset</a> and
<a href="Types/resources.html#files">files</a>
are undefined in terms of order.</p>
<pre>
<classpath>
<pathelement path="${classpath}"/>
<fileset dir="lib">
<include name="**/*.jar"/>
</fileset>
<pathelement location="classes"/>
<dirset dir="${build.dir}">
<include name="apps/**/classes"/>
<exclude name="apps/**/*Test*"/>
</dirset>
<filelist refid="third-party_jars"/>
</classpath></pre>
<p>This builds a path that holds the value of <samp>${classpath}</samp>,
followed by all jar files in the <samp>lib</samp> directory,
the <samp>classes</samp> directory, all directories named
<samp>classes</samp> under the <samp>apps</samp> subdirectory of
<samp>${build.dir}</samp>, except those
that have the text <code>Test</code> in their name, and
the files specified in the referenced FileList.</p>
<p>If you want to use the same path-like structure for several tasks,
you can define them with a <code><path></code> element at the
same level as <code><target></code>s, and reference them via their
<var>id</var> attribute—see <a href="#references">References</a> for an
example.</p>
<p>By default a path-like structure will re-evaluate all nested
resource collections whenever it is used, which may lead to
unnecessary re-scanning of the filesystem. <em>Since Ant 1.8.0</em>, path has
an optional <var>cache</var> attribute, if it is set to <q>true</q>, the path
instance will only scan its nested resource collections once and
assume it doesn't change during the build anymore (the default
for <var>cache</var> still is <q>false</q>). Even if you are using the
path only in a single task it may improve overall performance to set
<var>cache</var> to <q>true</q> if you are using complex nested
constructs.</p>
<p>A path-like structure can include a reference to another path-like
structure (a path being itself a resource collection)
via nested <code><path></code> elements:</p>
<pre>
<path id="base.path">
<pathelement path="${classpath}"/>
<fileset dir="lib">
<include name="**/*.jar"/>
</fileset>
<pathelement location="classes"/>
</path>
<path id="tests.path" cache="true">
<path refid="base.path"/>
<pathelement location="testclasses"/>
</path></pre>
The shortcuts previously mentioned for <code><classpath></code>
are also valid for <code><path></code>. For example:
<pre>
<path id="base.path">
<pathelement path="${classpath}"/>
</path></pre>
can be written as:
<pre><path id="base.path" path="${classpath}"/></pre>
<h4 id="pathshortcut">Path Shortcut</h4>
<p>
<em>Since Ant 1.6</em>, there is a shortcut for converting paths to OS specific
strings in properties. One can use the expression
<samp>${toString:<em>pathreference</em>}</samp> to convert a path element
reference to a string that can be used for a path argument. For example:
</p>
<pre>
<path id="lib.path.ref">
<fileset dir="lib" includes="*.jar"/>
</path>
<javac srcdir="src" destdir="classes">
<compilerarg arg="-Xbootclasspath/p:${toString:lib.path.ref}"/>
</javac></pre>
<h3 id="arg">Command-line Arguments</h3>
<p>Several tasks take arguments that will be passed to another
process on the command line. To make it easier to specify arguments
that contain space characters, nested <code>arg</code> elements can be used.</p>
<table class="attr">
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>value</td>
<td>a single command-line argument; can contain space
characters.</td>
<td rowspan="5">Exactly one of these.</td>
</tr>
<tr>
<td>file</td>
<td class="left">The name of a file as a single command-line
argument; will be replaced with the absolute filename of the file.</td>
</tr>
<tr>
<td>path</td>
<td class="left">A string that will be treated as a path-like
string as a single command-line argument; you can use <q>;</q>
or <q>:</q> as
path separators and Ant will convert it to the platform's local
conventions.</td>
</tr>
<tr>
<td>pathref</td>
<td class="left"><a href="#references">Reference</a> to a path
defined elsewhere. Ant will convert it to the platform's local
conventions.</td>
</tr>
<tr>
<td>line</td>
<td class="left">a space-delimited list of command-line arguments.</td>
</tr>
<tr>
<td>prefix</td>
<td>A fixed string to be placed in front of the
argument. In the case of a line broken into parts, it will be
placed in front of every part. <em>Since Ant 1.8.</em></td>
<td>No</td>
</tr>
<tr>
<td>suffix</td>
<td>A fixed string to be placed immediately after the
argument. In the case of a line broken into parts, it will be
placed after every part. <em>Since Ant 1.8.</em></td>
<td>No</td>
</tr>
</table>
<p>It is highly recommended to avoid the <var>line</var> version
when possible. Ant will try to split the command line in a way
similar to what a (Unix) shell would do, but may create something that
is very different from what you expect under some circumstances.</p>
<h4>Examples</h4>
<pre><arg value="-l -a"/></pre>
<p>is a single command-line argument containing a space character,
<em>not</em> separate options <q>-l</q> and <q>-a</q>.</p>
<pre><arg line="-l -a"/></pre>
<p>This is a command line with two separate options, <q>-l</q> and <q>-a</q>.</p>
<pre><arg path="/dir;/dir2:\dir3"/></pre>
<p>is a single command-line argument with the value
<code>\dir;\dir2;\dir3</code> on DOS-based systems and
<code>/dir:/dir2:/dir3</code> on Unix(-like) systems.</p>
<h3 id="references">References</h3>
<p>Any project element can be assigned an identifier using its
<var>id</var> attribute. In most cases the element can subsequently
be referenced by specifying the <var>refid</var> attribute on an
element of the same type. This can be useful if you are going to
replicate the same snippet of XML over and over again—using a
<code><classpath></code> structure more than once, for example.</p>
<p>The following example:</p>
<pre>
<project ... >
<target ... >
<rmic ...>
<classpath>
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</classpath>
</rmic>
</target>
<target ... >
<javac ...>
<classpath>
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</classpath>
</javac>
</target>
</project></pre>
<p>could be rewritten as:</p>
<pre>
<project ... >
<path id="project.class.path">
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</path>
<target ... >
<rmic ...>
<classpath refid="project.class.path"/>
</rmic>
</target>
<target ... >
<javac ...>
<classpath refid="project.class.path"/>
</javac>
</target>
</project></pre>
<p>All tasks that use nested elements for
<a href="Types/patternset.html">PatternSet</a>s,
<a href="Types/fileset.html">FileSet</a>s,
<a href="Types/zipfileset.html">ZipFileSet</a>s or
<a href="#path">path-like structures</a> accept references to these structures
as shown in the examples. Using <var>refid</var> on a task will ordinarily
have the same effect (referencing a task already declared), but the user
should be aware that the interpretation of this attribute is dependent on the
implementation of the element upon which it is specified. Some tasks (the
<a href="Tasks/property.html">property</a> task is a handy example)
deliberately assign a different meaning to <var>refid</var>.</p>
<h3 id="external-tasks">Use of external tasks</h3>
Ant supports a plugin mechanism for using third party tasks. For using them you
have to do two steps:
<ol>
<li>place their implementation somewhere where Ant can find them.</li>
<li>declare them.</li>
</ol>
Don't add anything to the <code>CLASSPATH</code> environment variable—this is often the
reason for very obscure errors. Use Ant's own <a href="install.html#optionalTasks">mechanisms</a>
for adding libraries:
<ul>
<li>via command line argument <code>-lib</code></li>
<li>adding to <code>${user.home}/.ant/lib</code></li>
<li>adding to <code>${ant.home}/lib</code></li>
</ul>
For the declaration there are several ways:
<ul>
<li>declare a single task per using instruction using
<code><<a href="Tasks/taskdef.html">taskdef</a> name="taskname"
classname="ImplementationClass"/></code>
<br/>
<code><taskdef name="for" classname="net.sf.antcontrib.logic.For"/>
<for ... /></code>
</li>
<li>declare a bundle of tasks using a <samp>properties</samp> file holding these
taskname-ImplementationClass-pairs and <code><taskdef></code>
<br/>
<code><taskdef resource="net/sf/antcontrib/antcontrib.properties"/>
<for ... /></code>
</li>
<li>declare a bundle of tasks using
an <a href="Types/antlib.html">xml file</a> holding these
taskname-ImplementationClass-pairs and <code><taskdef></code>
<br/>
<code><taskdef resource="net/sf/antcontrib/antlib.xml"/>
<for ... /></code>
</li>
<li>declare a bundle of tasks using an xml file named <samp>antlib.xml</samp>, XML namespace and
<a href="Types/antlib.html#antlibnamespace"><code>antlib:</code> protocol handler</a>
<br/>
<code><project xmlns:ac="antlib:net.sf.antcontrib"/>
<ac:for ... /></code>
</li>
</ul>
If you need a special function, you should
<ol>
<li>have a look at this manual, because Ant provides lot of tasks</li>
<li>have a look at the external task page <a href="https://ant.apache.org/external.html">online</a></li>
<li>have a look at the external task <a href="https://wiki.apache.org/ant/AntExternalTaskdefs">wiki
page</a></li>
<li>ask on the <a href="https://ant.apache.org/mail.html#User%20List">Ant user</a> list</li>
<li><a href="tutorial-writing-tasks.html">implement</a> (and share) your own</li>
</ol>
</body>
</html>
|
