mirror of
https://github.com/apache/ant.git
synced 2025-05-17 13:35:43 +00:00
362f5f0c59
* Ant 1.10 requires jdk 8 doc update * Updated the manual to reflect ant requires JDK 8 +
691 lines
29 KiB
HTML
691 lines
29 KiB
HTML
<!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>
|