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
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
|
<!DOCTYPE html>
<!--
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
https://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 lang="en">
<head>
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
<title>Running Apache Ant</title>
</head>
<body>
<h1>Running Apache Ant</h1>
<h2 id="commandline">Command Line</h2>
<p>If you've installed Apache Ant as described in
the <a href="install.html">Installing Ant</a> section, running Ant
from the command-line is simple: just type <kbd>ant</kbd>.</p>
<p>When no arguments are specified, Ant looks for
a <samp>build.xml</samp> file in the current directory and, if found,
uses that file as the build file and runs the target specified in
the <var>default</var> attribute of the <code><project></code>
tag. To make Ant use a build file other than <samp>build.xml</samp>,
use the command-line option <kbd>-buildfile <i>file</i></kbd>,
where <code><i>file</i></code> is the name of the build file you want to use (or
a directory containing a <samp>build.xml</samp> file).</p>
<p>If you use the <kbd>-find [<i>file</i>]</kbd> option, Ant will
search for a build file first in the current directory, then in the
parent directory, and so on, until either a build file is found or the
root of the filesystem has been reached. By default, it will look for
a build file called <samp>build.xml</samp>. To have it search for a
build file other than <samp>build.xml</samp>, specify a file
argument. <strong>Note</strong>: If you include any other flags or
arguments on the command line after the <kbd>-find</kbd> flag, you
must include the file argument for the <kbd>-find</kbd> flag, even
if the name of the build file you want to find
is <samp>build.xml</samp>.</p>
<p>You can also set <a href="using.html#properties">properties</a> on
the command line. This can be done with
the <kbd>-D<i>property</i>=<i>value</i></kbd> option,
where <em>property</em> is the name of the property,
and <em>value</em> is the value for that property. If you specify a
property that is also set in the build file (see
the <a href="Tasks/property.html">property</a> task), the value
specified on the command line will override the value specified in the
build file. Defining properties on the command line can also be used
to pass in the value of environment variables; just
pass <kbd>-DMYVAR=%MYVAR%</kbd> (Windows)
or <kbd>-DMYVAR=$MYVAR</kbd> (Unix) to Ant. You can then access
these variables inside your build file as <code>${MYVAR}</code>. You
can also access environment variables using
the <a href="Tasks/property.html">property</a>
task's <var>environment</var> attribute.</p>
<p>Options that affect the amount of logging output by Ant
are: <kbd>-quiet</kbd>, which instructs Ant to print less
information to the console; <kbd>-verbose</kbd>, which causes Ant to
print additional information to the console; <kbd>-debug</kbd>,
which causes Ant to print considerably more additional information;
and <kbd>-silent</kbd> which makes Ant print nothing but task output
and build failures (useful to capture Ant output by scripts).</p>
<p>It is also possible to specify one or more targets that should be
executed. When omitted, the target that is specified in
the <var>default</var> attribute of
the <a href="using.html#projects"><code>project</code></a> tag is
used.</p>
<p>The <kbd>-projecthelp</kbd> option prints out a list of the build
file's targets. Targets that include a <var>description</var>
attribute are listed as "Main targets", those without
a <var>description</var> are listed as "Other targets", then
the "Default" target is listed ("Other targets" are only
displayed if there are no main targets, or if Ant is invoked
in <kbd>-verbose</kbd> or <kbd>-debug</kbd> mode).</p>
<h3 id="options">Command-line Options Summary</h3>
<pre class="output">ant [options] [target [target2 [target3] ...]]
Options:
-help, -h print this message and exit
-projecthelp, -p print project help information and exit
-version print the version information and exit
-diagnostics print information that might be helpful to
diagnose or report problems and exit
-quiet, -q be extra quiet
-silent, -S print nothing but task outputs and build failures
-verbose, -v be extra verbose
-debug, -d print debugging information
-emacs, -e produce logging information without adornments
-lib <path> specifies a path to search for jars and classes
-logfile <file> use given file for log
-l <file> ''
-logger <classname> the class which is to perform logging
-listener <classname> add an instance of class as a project listener
-noinput do not allow interactive input
-buildfile <file> use given buildfile
-file <file> ''
-f <file> ''
-D<property>=<value> use value for given property
-keep-going, -k execute all targets that do not depend
on failed target(s)
-propertyfile <name> load all properties from file with -D
properties taking precedence
-inputhandler <class> the class which will handle input requests
-find <file> (s)earch for buildfile towards the root of
-s <file> the filesystem and use it
-nice number A niceness value for the main thread:
1 (lowest) to 10 (highest); 5 is the default
-nouserlib Run ant without using the jar files from ${user.home}/.ant/lib
-noclasspath Run ant without using CLASSPATH
-autoproxy Java 5+ : use the OS proxies
-main <class> override Ant's normal entry point
</pre>
<p>For more information about <kbd>-logger</kbd>
and <kbd>-listener</kbd> see <a href="listeners.html">Loggers &
Listeners</a>.
<p>For more information about <kbd>-inputhandler</kbd>
see <a href="inputhandler.html">InputHandler</a>.
<p>Easiest way of changing the exit-behaviour is subclassing the
original main class:</p>
<pre>
public class CustomExitCode extends org.apache.tools.ant.Main {
protected void exit(int exitCode) {
// implement your own behaviour, e.g. NOT exiting the JVM
}
}
</pre>
<p>and starting Ant with access (<kbd>-lib <i>path-to-class</i></kbd>)
to this class.</p>
<h3 id="libs">Library Directories</h3>
<p>Prior to Ant 1.6, all jars in the <samp>ANT_HOME/lib</samp> would
be added to the <samp>CLASSPATH</samp> used to run Ant. This was done
in the scripts that started Ant. <em>Since Ant 1.6</em>, two
directories are scanned by default and more can be added as
required. The default directories scanned
are <samp>ANT_HOME/lib</samp> and a user specific
directory, <samp>${user.home}/.ant/lib</samp>. This arrangement allows
the Ant installation to be shared by many users while still allowing
each user to deploy additional jars. Such additional jars could be
support jars for Ant's optional tasks or jars containing third-party
tasks to be used in the build. It also allows the main Ant
installation to be locked down which will please system
administrators.</p>
<p>Additional directories to be searched may be added by using
the <kbd>-lib</kbd> option. The <kbd>-lib</kbd> option specifies
a search path. Any jars or classes in the directories of the path will
be added to Ant's classloader. The order in which jars are added to
the classpath is as follows:</p>
<ul>
<li>jars in the order specified by the <kbd>-lib</kbd> options on the command line</li>
<li>jars from <samp>${user.home}/.ant/lib</samp> (unless <kbd>-nouserlib</kbd> is set)</li>
<li>jars from <samp>ANT_HOME/lib</samp></li>
</ul>
<p>Note that the <code>CLASSPATH</code> environment variable is passed
to Ant using a <kbd>-lib</kbd> option. Ant itself is started with a
very minimalistic classpath. Ant should work perfectly well with an
empty <code>CLASSPATH</code> environment variable, something the
the <kbd>-noclasspath</kbd> option actually enforces. We get many more
support calls related to classpath problems (especially quoting
problems) than we like.</p>
<p>The location of <samp>${user.home}/.ant/lib</samp> is somewhat
dependent on the JVM. On Unix systems <samp>${user.home}</samp> maps
to the user's home directory whilst on recent versions of Windows it
will be somewhere such
as <code>C:\Users\<i>username</i>\.ant\lib</code>. You should consult
your JVM documentation for more details.</p>
<h3>Examples</h3>
<pre class="input">ant</pre>
<p>runs Ant using the <samp>build.xml</samp> file in the current
directory, on the default target.</p>
<pre class="input">ant -buildfile test.xml</pre>
<p>runs Ant using the <samp>test.xml</samp> file in the current
directory, on the default target.</p>
<pre class="input">ant -buildfile test.xml dist</pre>
<p>runs Ant using the <samp>test.xml</samp> file in the current
directory, on the target called <samp>dist</samp>.</p>
<pre class="input">ant -buildfile test.xml -Dbuild=build/classes dist</pre>
<p>runs Ant using the <samp>test.xml</samp> file in the current
directory, on the target called <samp>dist</samp>, setting
the <code>build</code> property to the value <q>build/classes</q>.</p>
<pre class="input">ant -lib /home/ant/extras</pre>
<p>runs Ant picking up additional task and support jars from
the <samp>/home/ant/extras</samp> location</p>
<pre class="input">ant -lib one.jar;another.jar</pre>
<pre class="input">ant -lib one.jar -lib another.jar</pre>
<p>adds two jars to Ants classpath.</p>
<h3 id="files">Files</h3>
<p>The Ant wrapper script for Unix will source (read and evaluate) the
file <samp>~/.antrc</samp> before it does anything. On Windows, the
Ant wrapper batch-file invokes <samp>%HOME%\antrc_pre.bat</samp> at
the start and <samp>%HOME%\antrc_post.bat</samp> at the end. You can
use these files, for example, to set/unset environment variables that
should only be visible during the execution of Ant. See the next
section for examples.</p>
<h3 id="envvars">Environment Variables</h3>
<p>The wrapper scripts use the following environment variables (if set):</p>
<ul>
<li><code>JAVACMD</code>—full path of the Java executable. Use this
to invoke a different JVM than <samp>JAVA_HOME/bin/java(.exe)</samp>.</li>
<li><code>ANT_OPTS</code>—command-line arguments that should be
passed to the JVM. For example, you can define system properties or set
the maximum Java heap size here.</li>
<li><code>ANT_ARGS</code>—Ant command-line arguments. For example,
set <code>ANT_ARGS</code> to point to a different logger, include a
listener, and to include the <kbd>-find</kbd> flag.<br/>
<strong>Note</strong>: If you include <kbd>-find</kbd>
in <code>ANT_ARGS</code>, you should include the name of the build file
to find, even if the file is called <samp>build.xml</samp>.</li>
</ul>
<h3 id="sysprops">Java System Properties</h3>
<p>Some of Ant's core classes can be configured via system properties.</p>
<p>Here is the result of a search through the codebase. Because system
properties are available via Project instance, I searched for them with a</p>
<pre class="input">grep -r -n "getPropert" * > ..\grep.txt</pre>
<p>command. After that I filtered out the often-used but
not-so-important values (most of them read-only
values): <code>path.separator</code>, <code>ant.home</code>, <code>basedir</code>,
<code>user.dir</code>, <code>os.name</code>, <code>line.separator</code>,
<code>java.home</code>, <code>java.version</code>, <code>java.version</code>,
<code>user.home</code>, <code>java.class.path</code><br/>
And I filtered out the <code>getPropertyHelper</code> access.</p>
<table>
<tr>
<th scope="col">property name</th>
<th scope="col">valid values/default value</th>
<th scope="col">description</th>
</tr>
<tr>
<td><code>ant.build.javac.source</code></td>
<td>Source-level version number</td>
<td>Default <var>source</var> value
for <code><javac></code>/<code><javadoc></code></td>
</tr>
<tr>
<td><code>ant.build.javac.target</code></td>
<td>Class-compatibility version number</td>
<td>Default <var>target</var> value for <code><javac></code></td>
</tr>
<tr>
<td><code>ant.executor.class</code></td>
<td>classname; default is <q>org.<wbr>apache.<wbr>tools.<wbr>ant.<wbr>helper.<wbr>DefaultExecutor</q></td>
<td><em>Since Ant 1.6.3</em> Ant will delegate Target invocation to
the <code class="code">org.apache.tools.ant.Executor</code>
implementation specified here.</td>
</tr>
<tr>
<td><code>ant.file</code></td>
<td>read only: full filename of the build file</td>
<td>This is set to the name of the build
file. In <a href="Tasks/import.html"><import>-ed</a> files,
this is set to the containing build file.</td>
</tr>
<tr>
<td><code>ant.file.*</code></td>
<td>read only: full filename of the build file of Ant projects</td>
<td>This is set to the name of a file by project; this lets you
determine the location
of <a href="Tasks/import.html"><import>-ed</a> files.</td>
</tr>
<tr>
<td><code>ant.input.properties</code></td>
<td>filename (required)</td>
<td>Name of the file holding the values for
the <a href="inputhandler.html">PropertyFileInputHandler</a>.</td>
</tr>
<tr>
<td><code>ant.logger.defaults</code></td>
<td>filename (optional, default <q>/org/<wbr>apache/<wbr>tools/<wbr>ant/<wbr>listener/<wbr>defaults.properties</q>)</td>
<td>Name of the file holding the color mappings for
the <a href="listeners.html#AnsiColorLogger">AnsiColorLogger</a>.</td>
</tr>
<tr>
<td><code>ant.netrexxc.*</code></td>
<td>several formats</td>
<td>Use specified values as defaults
for <a href="Tasks/netrexxc.html">netrexxc</a>.</td>
</tr>
<tr>
<td><code>ant.PropertyHelper</code></td>
<td>Ant reference name (optional)</td>
<td>Specify the PropertyHelper to use. The object must be of the
type <code class="code">org.apache.tools.ant.PropertyHelper</code>. By
default, an object
of <code class="code">org.apache.tools.ant.PropertyHelper</code>
will be used as PropertyHelper.</td>
</tr>
<tr>
<td><code>ant.regexp.regexpimpl</code></td>
<td>classname</td>
<td>classname for a RegExp implementation; by default the <code>java.util.regex</code>
implementation; <a href="Types/mapper.html#regexp-mapper">RegExp
Mapper</a> "Choice of regular expression implementation".</td>
</tr>
<tr>
<td><code>ant.reuse.loader</code></td>
<td>boolean</td>
<td>allow to reuse classloaders used
in <code class="code">org.apache.tools.ant.util.ClasspathUtil</code>.</td>
</tr>
<tr>
<td><code>ant.XmlLogger.stylesheet.uri</code></td>
<td>filename (default <q>log.xsl</q>)</td>
<td>Name for the stylesheet to include in the logfile
by <a href="listeners.html#XmlLogger">XmlLogger</a>.</td>
</tr>
<tr>
<td><code>build.compiler</code></td>
<td>name</td>
<td>Specify the default compiler to use;
see <a href="Tasks/javac.html">javac</a>, <a href="Tasks/ejb.html#ejbjar_weblogic">EJB
Tasks</a> (<var>compiler</var>
attribute), <a href="Tasks/javah.html">javah</a>.</td>
</tr>
<tr>
<td><code>build.compiler.emacs</code></td>
<td>boolean (default <q>false</q>)</td>
<td>Enable emacs-compatible error messages;
see <a href="Tasks/javac.html#jikes">javac</a> "Jikes Notes".</td>
</tr>
<tr>
<td><code>build.compiler.fulldepend</code></td>
<td>boolean (default false)</td>
<td>Enable full dependency checking;
see <a href="Tasks/javac.html#jikes">javac</a> "Jikes Notes".</td>
</tr>
<tr>
<td><code>build.compiler.jvc.extensions</code></td>
<td><em><u>Deprecated</u></em></td>
<td>Enable Microsoft extensions of their Java compiler;
see <a href="Tasks/javac.html#jvc">javac</a> "Jvc Notes".</td>
</tr>
<tr>
<td><code>build.compiler.pedantic</code></td>
<td>boolean (default <q>false</q>)</td>
<td>Enable pedantic warnings;
see <a href="Tasks/javac.html#jikes">javac</a> "Jikes Notes".</td>
</tr>
<tr>
<td><code>build.compiler.warnings</code></td>
<td><em><u>Deprecated</u></em></td>
<td>See <a href="Tasks/javac.html#jikes">javac</a> "Jikes Notes"</td>
</tr>
<tr>
<td><code>build.rmic</code></td>
<td>name</td>
<td>Control the <a href="Tasks/rmic.html">rmic</a> compiler</td>
</tr>
<tr>
<td><code>build.sysclasspath</code></td>
<td>No default value</td>
<td>See <a href="sysclasspath.html">its dedicated page</a></td>
</tr>
<tr>
<td><code>file.encoding</code></td>
<td>name of a supported character set (e.g. UTF-8, ISO-8859-1, US-ASCII)</td>
<td>use as default character set of email messages; use as default
for <var>srcencoding</var>, <var>destencoding</var>
and <var>bundleencoding</var>
in <a href="Tasks/translate.html">translate</a><br/> see JavaDoc
of <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html"
target="_top">java.nio.charset.Charset</a> for more information
about character sets (not used in Ant, but has nice docs).</td>
</tr>
<tr>
<td><code>jikes.class.path</code></td>
<td>path</td>
<td>The specified path is added to the classpath if Jikes is used as compiler.</td>
</tr>
<tr>
<td><code>MailLogger.properties.file</code>, <code>MailLogger.*</code></td>
<td>filename (optional, defaults derived from Project instance)</td>
<td>Name of the file holding properties for sending emails by
the <a href="listeners.html#MailLogger">MailLogger</a>. Override
properties set inside the buildfile or via command line.</td>
</tr>
<tr>
<td><code>org.apache.tools.ant.ProjectHelper</code></td>
<td>classname (optional, default <q>org.<wbr>apache.<wbr>tools.<wbr>ant.<wbr>ProjectHelper2</q>)</td>
<td>specifies the classname to use as ProjectHelper. The class must
extend <code class="code">org.apache.tools.ant.ProjectHelper</code>.</td>
</tr>
<tr>
<td><code>org.apache.tools.ant.ArgumentProcessor</code></td>
<td>classname (optional)</td>
<td>specifies the classname to use as ArgumentProcessor. The class
must extend <code class="code">org.apache.tools.ant.ArgumentProcessor</code>.</td>
</tr>
<tr>
<td><code>websphere.home</code></td>
<td>path</td>
<td>Points to home directory of WebSphere;
see <a href="Tasks/ejb.html#ejbjar_websphere">EJB Tasks</a></td>
</tr>
<tr>
<td><code>XmlLogger.file</code></td>
<td>filename (default <q>log.xml</q>)</td>
<td>Name for the logfile
for <a href="listeners.html#MailLogger">MailLogger</a>.</td>
</tr>
<tr>
<td><code>ant.project-helper-repo.debug</code></td>
<td>boolean (default <q>false</q>)</td>
<td>Set it to <q>true</q> to enable debugging with
Ant's <a href="projecthelper.html#repository">ProjectHelper internal
repository</a>.</td>
</tr>
<tr>
<td><code>ant.argument-processor-repo.debug</code></td>
<td>boolean (default <q>false</q>)</td>
<td>Set it to <q>true</q> to enable debugging with
Ant's <a href="argumentprocessor.html#repository">ArgumentProcessor
internal repository</a>.</td>
</tr>
<tr>
<td><code>ant.tstamp.now</code></td>
<td>number, seconds since the epoch (midnight 1970-01-01)</td>
<td rowspan="2">The value to use as current time and date
for <code><tstamp></code></td>
</tr>
<tr>
<td><code>ant.tstamp.now.iso</code></td>
<td>ISO-8601 timestamp string like <code>1972-04-17T08:07:00Z</code></td>
</tr>
<tr>
<td><code>java.io.tmpdir</code></td>
<td>path</td>
<td>Some tasks need to create temporary files and will write them to
the directory specified by this property. This property is set by
the Java VM but can be overridden when Ant is started.<br/>
See also <a href="#tmpdir">Temporary Directories</a>.</td>
</tr>
<tr>
<td><code>ant.tmpdir</code></td>
<td>path</td>
<td><em>Since Ant 1.10.8</em><br/>
Some tasks need to create temporary files and will write them to
the directory specified by this property. This property takes
precedence over <code>java.io.tmpdir</code> if it has been
set. Unlike <code>java.io.tmpdir</code> this property can be set
from within the build file.<br/>
See also <a href="#tmpdir">Temporary Directories</a>.</td>
</tr>
<tr>
<td><code>ant.disable.graal.nashorn.compat</code></td>
<td>boolean (default <q>false</q>)</td>
<td><em>Since Ant 1.10.9</em><br/>
By default Ant will enable GraalVM JavaScript's Nashorn
compatibility mode for <code>script</code> and friends. You can
disable this behavior by setting this property to <q>true</q>.<br/>
See also the <a href="Tasks/script.html">script task manual</a>.</td>
</tr>
</table>
<p>
If new properties get added (it happens), expect them to appear under
the <code>ant.</code> and <code>org.apache.tools.ant.</code> prefixes,
unless the developers have a very good reason to use another
prefix. Accordingly, please avoid using properties that begin with
these prefixes. This protects you from future Ant releases breaking
your build file.
</p>
<h3>return code</h3>
<p>
Ant start up scripts (in their Windows and Unix version) return the
return code of the <code>java</code> program. So a successful build
returns <q>0</q>, failed builds return other values.
</p>
<h2 id="tmpdir">Temporary Directories</h2>
Some Ant tasks and types need to create temporary files. By default
they use the default temporary directory of the Java VM they are
running in - which can be set by setting the system
property <code>java.io.tmpdir</code>. The default value of it depends
on the platform and the JVM implementation.</p>
<p>Setting a system property when invoking Ant is not straight forward
as the corresponding command line arguments must be sent to the Java
executable rather than Ant's main class. When using
the <code>ant(.cmd)</code> wrapper scripts you can do so with the
help of the <code>ANT_OPTS</code> environment variable.</p>
<p>Starting with Ant 1.10.8 we've introduced a new Ant
property <code>ant.tmpdir</code> that takes precedence
over <code>java.io.tmpdir</code> when set. As this is a normal Ant
property it can be set via the command line or even from within a
build file.</p>
<p>Tasks and types using the temporary directory will state the fact
inside of their respective manual page. In addition every execution
of an external command on OpenVMS will create a temporary file
holding a DCL script that invokes the actual command.</p>
<p>Starting with Ant 1.10.9 Ant will try to create a build process
specific temporary directory inside <code>java.io.tmpdir</code> with
permissions set to be accessible by the current user only and use
that if <code>ant.tmpdir</code> has not been set and Ant is able to
set permissions on the filesystem in question.</p>
<p>Tasks not provided with the Ant distribution will ignore
the <code>ant.tmpdir</code> property or the process subdirectory and
use <code>java.io.tmpdir</code> unless they have been adapted to the
changed API of Ant 1.10.8.</p>
<p><b>Security Note:</b> Using the default temporary directory
specified by <code>java.io.tmpdir</code> can result in the leakage of
sensitive information or possibly allow an attacker to inject source
files into the build process. This is especially true in multi-user
environments. It is recommended that <code>ant.tmpdir</code> be set to
a directory owned by the user running Ant with 0700 permissions. Ant
1.10.8 and later will try to make temporary files created by it only
readable/writable by the current user but may silently fail to do so
depending on the OS and filesystem.</p>
<h2 id="cygwin">Cygwin Users</h2>
<p>
Unix launch script that come with Ant works correctly with Cygwin. You
should not have any problems launching Ant from the Cygwin shell. It
is important to note, however, that once Ant is running it is part of
the JDK which operates as a native Windows application. The JDK is not
a Cygwin executable, and it therefore has no knowledge of Cygwin
paths, etc. In particular when using the <code><exec></code>
task, executable names such as <q>/bin/sh</q> will not work, even
though these work from the Cygwin shell from which Ant was
launched. You can use an executable name such as <q>sh</q> and rely on
that command being available in the Windows path.
<h2 id="os2">OS/2 Users</h2>
<p>
The OS/2 launch script was developed to perform complex tasks. It has
two parts: <kbd>ant.cmd</kbd> which calls Ant
and <kbd>antenv.cmd</kbd> which sets the environment for Ant. Most
often you will just call <kbd>ant.cmd</kbd> using the same command
line options as described above. The behaviour can be modified by a
number of ways explained below.
</p>
<p>
Script <kbd>ant.cmd</kbd> first verifies whether the Ant environment
is set correctly. The requirements are:
</p>
<ol>
<li>Environment variable <code>JAVA_HOME</code> is set.</li>
<li>Environment variable <code>ANT_HOME</code> is set.</li>
<li>Environment variable <code>CLASSPATH</code> is set and contains at least one element from
<code>JAVA_HOME</code> and at least one element from <code>ANT_HOME</code>.</li>
</ol>
<p>
If any of these conditions is violated, script <kbd>antenv.cmd</kbd>
is called. This script first invokes configuration scripts if there
exist: the system-wide configuration <kbd>antconf.cmd</kbd> from
the <samp>%ETC%</samp> directory and then the user
configuration <kbd>antrc.cmd</kbd> from the <samp>%HOME%</samp>
directory. At this moment both <code>JAVA_HOME</code>
and <code>ANT_HOME</code> must be defined
because <kbd>antenv.cmd</kbd> now adds <samp>classes.zip</samp>
or <samp>tools.jar</samp> (depending on version of JVM) and everything
from <samp>%ANT_HOME%\lib</samp> except <samp>ant-*.jar</samp>
to <code>CLASSPATH</code>. Finally <kbd>ant.cmd</kbd> calls
per-directory configuration <kbd>antrc.cmd</kbd>. All settings made
by <kbd>ant.cmd</kbd> are local and are undone when the script
ends. The settings made by <kbd>antenv.cmd</kbd> are persistent
during the lifetime of the shell (of course unless called
automatically from <kbd>ant.cmd</kbd>). It is thus possible to
call <kbd>antenv.cmd</kbd> manually and modify some settings before
calling <kbd>ant.cmd</kbd>.
</p>
<p>
Scripts <kbd>envset.cmd</kbd> and <kbd>runrc.cmd</kbd> perform
auxiliary tasks. All scripts have some documentation inside.
</p>
<h2 id="background">Running Ant as a background process on Unix(-like) systems</h2>
<p>
If you start Ant as a background process (like in <kbd>ant
&</kbd>) and the build process creates another process, Ant will
immediately try to read from standard input, which in turn will most
likely suspend the process. In order to avoid this, you must redirect
Ant's standard input or explicitly provide input to each spawned
process via the input related attributes of the corresponding tasks.
</p>
<p>
Tasks that create such new processes
include <code><exec></code>, <code><apply></code>
or <code><java></code> when the <var>fork</var> attribute
is <q>true</q>.
</p>
<h2 id="viajava">Running Ant via Java</h2>
<p>
If you have installed Ant in the do-it-yourself way, Ant can be
started from one of two entry points:
</p>
<pre class="input">java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
<pre class="input">java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]</pre>
<p>
The first method runs Ant's traditional entry point. The second method
uses the Ant Launcher introduced in Ant 1.6. The former method does
not support the <kbd>-lib</kbd> option and all required classes are
loaded from the <code>CLASSPATH</code>. You must ensure that all
required jars are available. At a minimum the <code>CLASSPATH</code>
should include:
</p>
<ul>
<li><samp>ant.jar</samp> and <samp>ant-launcher.jar</samp></li>
<li>jars/classes for your XML parser</li>
<li>the JDK's required jar/zip files</li>
</ul>
<p>
The latter method supports
the <kbd>-lib</kbd>, <kbd>-nouserlib</kbd>, <kbd>-noclasspath</kbd>
options and will load jars from the
specified <code>ANT_HOME</code>. You should start the latter with the
most minimal classpath possible, generally just
the <samp>ant-launcher.jar</samp>.
</p>
<p id="viaant">
Ant can be started in Ant via the <code><java></code> command.
Here is an example:
</p>
<pre>
<java classname="org.apache.tools.ant.launch.Launcher"
fork="true"
failonerror="true"
dir="${sub.builddir}"
timeout="4000000"
taskname="startAnt">
<classpath>
<pathelement location="${ant.home}/lib/ant-launcher.jar"/>
</classpath>
<arg value="-buildfile"/>
<arg file="${sub.buildfile}"/>
<arg value="-Dthis=this"/>
<arg value="-Dthat=that"/>
<arg value="-Dbasedir=${sub.builddir}"/>
<arg value="-Dthe.other=the.other"/>
<arg value="${sub.target}"/>
</java>
</pre>
</body>
</html>
|
