If you've installed Apache Ant as described in
the
Installing Ant
section, running Ant
from the command-line is simple: just type
ant
.
When no arguments are specified, Ant looks for
a
build.xml
file in the current directory and, if found,
uses that file as the build file and runs the target specified in
the
default
attribute of the
<project>
tag. To make Ant use a build file other than
build.xml
,
use the command-line option
-buildfile
file
,
where
file
is the name of the build file you want to use (or
a directory containing a
build.xml
file).
If you use the
-find [
file
]
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
build.xml
. To have it search for a
build file other than
build.xml
, specify a file
argument.
Note
: If you include any other flags or
arguments on the command line after the
-find
flag, you
must include the file argument for the
-find
flag, even
if the name of the build file you want to find
is
build.xml
.
You can also set
properties
on
the command line. This can be done with
the
-D
property
=
value
option,
where
property
is the name of the property,
and
value
is the value for that property. If you specify a
property that is also set in the build file (see
the
property
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
-DMYVAR=%MYVAR%
(Windows)
or
-DMYVAR=$MYVAR
(Unix) to Ant. You can then access
these variables inside your build file as
${MYVAR}
. You
can also access environment variables using
the
property
task's
environment
attribute.
Options that affect the amount of logging output by Ant
are:
-quiet
, which instructs Ant to print less
information to the console;
-verbose
, which causes Ant to
print additional information to the console;
-debug
,
which causes Ant to print considerably more additional information;
and
-silent
which makes Ant print nothing but task output
and build failures (useful to capture Ant output by scripts).
It is also possible to specify one or more targets that should be
executed. When omitted, the target that is specified in
the
default
attribute of
the
project
tag is
used.
The
-projecthelp
option prints out a list of the build
file's targets. Targets that include a
description
attribute are listed as "Main targets", those without
a
description
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
-verbose
or
-debug
mode).
Command-line Options Summary
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
For more information about -logger
and -listener see Loggers &
Listeners.
For more information about -inputhandler
see InputHandler.
Easiest way of changing the exit-behaviour is subclassing the
original main class:
public class CustomExitCode extends org.apache.tools.ant.Main {
protected void exit(int exitCode) {
// implement your own behaviour, e.g. NOT exiting the JVM
and starting Ant with access (-lib path-to-class)
to this class.
Library Directories
Prior to Ant 1.6, all jars in the ANT_HOME/lib would
be added to the CLASSPATH used to run Ant. This was done
in the scripts that started Ant. Since Ant 1.6, two
directories are scanned by default and more can be added as
required. The default directories scanned
are ANT_HOME/lib and a user specific
directory, ${user.home}/.ant/lib. 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.
Additional directories to be searched may be added by using
the -lib option. The -lib 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:
jars in the order specified by the -lib options on the command line
jars from ${user.home}/.ant/lib (unless -nouserlib is set)
jars from ANT_HOME/lib
Note that the CLASSPATH
environment variable is passed
to Ant using a -lib option. Ant itself is started with a
very minimalistic classpath. Ant should work perfectly well with an
empty CLASSPATH
environment variable, something the
the -noclasspath option actually enforces. We get many more
support calls related to classpath problems (especially quoting
problems) than we like.
The location of ${user.home}/.ant/lib is somewhat
dependent on the JVM. On Unix systems ${user.home} maps
to the user's home directory whilst on recent versions of Windows it
will be somewhere such
as C:\Users\username\.ant\lib
. You should consult
your JVM documentation for more details.
Examples
runs Ant using the build.xml file in the current
directory, on the default target.
ant -buildfile test.xml
runs Ant using the test.xml file in the current
directory, on the default target.
ant -buildfile test.xml dist
runs Ant using the test.xml file in the current
directory, on the target called dist.
ant -buildfile test.xml -Dbuild=build/classes dist
runs Ant using the test.xml file in the current
directory, on the target called dist, setting
the build
property to the value build/classes
.
ant -lib /home/ant/extras
runs Ant picking up additional task and support jars from
the /home/ant/extras location
ant -lib one.jar;another.jar
ant -lib one.jar -lib another.jar
adds two jars to Ants classpath.
Files
The Ant wrapper script for Unix will source (read and evaluate) the
file ~/.antrc before it does anything. On Windows, the
Ant wrapper batch-file invokes %HOME%\antrc_pre.bat at
the start and %HOME%\antrc_post.bat 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.
Environment Variables
The wrapper scripts use the following environment variables (if set):
JAVACMD
—full path of the Java executable. Use this
to invoke a different JVM than JAVA_HOME/bin/java(.exe).
ANT_OPTS
—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.
ANT_ARGS
—Ant command-line arguments. For example,
set ANT_ARGS
to point to a different logger, include a
listener, and to include the -find flag.
Note: If you include -find
in ANT_ARGS
, you should include the name of the build file
to find, even if the file is called build.xml.
Java System Properties
Some of Ant's core classes can be configured via system properties.
Here is the result of a search through the codebase. Because system
properties are available via Project instance, I searched for them with a
grep -r -n "getPropert" * > ..\grep.txt
command. After that I filtered out the often-used but
not-so-important values (most of them read-only
values): path.separator
, ant.home
, basedir
,
user.dir
, os.name
, line.separator
,
java.home
, java.version
, java.version
,
user.home
, java.class.path
And I filtered out the getPropertyHelper
access.
property name
valid values/default value
description
ant.build.javac.source
Source-level version number
Default
source value
for
<javac>
/
<javadoc>
ant.build.javac.target
Class-compatibility version number
Default
target value for
<javac>
ant.executor.class
classname; default is
org.apache.tools.ant.helper.DefaultExecutor
Since Ant 1.6.3 Ant will delegate Target invocation to
the
org.apache.tools.ant.Executor
implementation specified here.
ant.file
read only: full filename of the build file
This is set to the name of the build
file. In
<import>-ed files,
this is set to the containing build file.
ant.file.*
read only: full filename of the build file of Ant projects
This is set to the name of a file by project; this lets you
determine the location
of
<import>-ed files.
ant.input.properties
filename (required)
Name of the file holding the values for
the
PropertyFileInputHandler.
ant.logger.defaults
filename (optional, default
/org/apache/tools/ant/listener/defaults.properties
)
Name of the file holding the color mappings for
the
AnsiColorLogger.
ant.netrexxc.*
several formats
Use specified values as defaults
for
netrexxc.
ant.PropertyHelper
Ant reference name (optional)
Specify the PropertyHelper to use. The object must be of the
type
org.apache.tools.ant.PropertyHelper
. By
default, an object
of
org.apache.tools.ant.PropertyHelper
will be used as PropertyHelper.
ant.regexp.regexpimpl
classname
classname for a RegExp implementation; by default the
java.util.regex
implementation;
RegExp
Mapper "Choice of regular expression implementation".
ant.reuse.loader
boolean
allow to reuse classloaders used
in
org.apache.tools.ant.util.ClasspathUtil
.
ant.XmlLogger.stylesheet.uri
filename (default
log.xsl
)
Name for the stylesheet to include in the logfile
by
XmlLogger.
build.compiler
Specify the default compiler to use;
see
javac,
EJB
Tasks (
compiler
attribute),
javah.
build.compiler.emacs
boolean (default
false
)
Enable emacs-compatible error messages;
see
javac "Jikes Notes".
build.compiler.fulldepend
boolean (default false)
Enable full dependency checking;
see
javac "Jikes Notes".
build.compiler.jvc.extensions
Deprecated
Enable Microsoft extensions of their Java compiler;
see
javac "Jvc Notes".
build.compiler.pedantic
boolean (default
false
)
Enable pedantic warnings;
see
javac "Jikes Notes".
build.compiler.warnings
Deprecated
See
javac "Jikes Notes"
build.rmic
Control the
rmic compiler
build.sysclasspath
No default value
See
its dedicated page
file.encoding
name of a supported character set (e.g. UTF-8, ISO-8859-1, US-ASCII)
use as default character set of email messages; use as default
for
srcencoding,
destencoding
and
bundleencoding
in
translate see JavaDoc
of
java.nio.charset.Charset for more information
about character sets (not used in Ant, but has nice docs).
jikes.class.path
The specified path is added to the classpath if Jikes is used as compiler.
MailLogger.properties.file
,
MailLogger.*
filename (optional, defaults derived from Project instance)
Name of the file holding properties for sending emails by
the
MailLogger. Override
properties set inside the buildfile or via command line.
org.apache.tools.ant.ProjectHelper
classname (optional, default
org.apache.tools.ant.ProjectHelper2
)
specifies the classname to use as ProjectHelper. The class must
extend
org.apache.tools.ant.ProjectHelper
.
org.apache.tools.ant.ArgumentProcessor
classname (optional)
specifies the classname to use as ArgumentProcessor. The class
must extend
org.apache.tools.ant.ArgumentProcessor
.
websphere.home
Points to home directory of WebSphere;
see
EJB Tasks
XmlLogger.file
filename (default
log.xml
)
Name for the logfile
for
MailLogger.
ant.project-helper-repo.debug
boolean (default
false
)
Set it to
true
to enable debugging with
Ant's
ProjectHelper internal
repository.
ant.argument-processor-repo.debug
boolean (default
false
)
Set it to
true
to enable debugging with
Ant's
ArgumentProcessor
internal repository.
ant.tstamp.now
number, seconds since the epoch (midnight 1970-01-01)
The value to use as current time and date
for
<tstamp>
ant.tstamp.now.iso
ISO-8601 timestamp string like
1972-04-17T08:07:00Z
java.io.tmpdir
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.
See also
Temporary Directories.
ant.tmpdir
Since Ant 1.10.8
Some tasks need to create temporary files and will write them to
the directory specified by this property. This property takes
precedence over
java.io.tmpdir
if it has been
set. Unlike
java.io.tmpdir
this property can be set
from within the build file.
See also
Temporary Directories.
ant.disable.graal.nashorn.compat
boolean (default
false
)
Since Ant 1.10.9
By default Ant will enable GraalVM JavaScript's Nashorn
compatibility mode for
script
and friends. You can
disable this behavior by setting this property to
true
.
See also the
script task manual.
If new properties get added (it happens), expect them to appear under
the
ant.
and
org.apache.tools.ant.
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.
return code
Ant start up scripts (in their Windows and Unix version) return the
return code of the
java
program. So a successful build
returns
0
, failed builds return other values.
Temporary Directories
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
java.io.tmpdir
. The default value of it depends
on the platform and the JVM implementation.
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 ant(.cmd)
wrapper scripts you can do so with the
help of the ANT_OPTS
environment variable.
Starting with Ant 1.10.8 we've introduced a new Ant
property ant.tmpdir
that takes precedence
over java.io.tmpdir
when set. As this is a normal Ant
property it can be set via the command line or even from within a
build file.
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.
Starting with Ant 1.10.9 Ant will try to create a build process
specific temporary directory inside java.io.tmpdir
with
permissions set to be accessible by the current user only and use
that if ant.tmpdir
has not been set and Ant is able to
set permissions on the filesystem in question.
Tasks not provided with the Ant distribution will ignore
the ant.tmpdir
property or the process subdirectory and
use java.io.tmpdir
unless they have been adapted to the
changed API of Ant 1.10.8.
Security Note: Using the default temporary directory
specified by java.io.tmpdir
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 ant.tmpdir
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.
Cygwin Users
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
<exec>
task, executable names such as
/bin/sh
will not work, even
though these work from the Cygwin shell from which Ant was
launched. You can use an executable name such as
sh
and rely on
that command being available in the Windows path.
OS/2 Users
The OS/2 launch script was developed to perform complex tasks. It has
two parts:
ant.cmd which calls Ant
and
antenv.cmd which sets the environment for Ant. Most
often you will just call
ant.cmd using the same command
line options as described above. The behaviour can be modified by a
number of ways explained below.
Script
ant.cmd first verifies whether the Ant environment
is set correctly. The requirements are:
Environment variable JAVA_HOME
is set.
Environment variable ANT_HOME
is set.
Environment variable CLASSPATH
is set and contains at least one element from
JAVA_HOME
and at least one element from ANT_HOME
.
If any of these conditions is violated, script
antenv.cmd
is called. This script first invokes configuration scripts if there
exist: the system-wide configuration
antconf.cmd from
the
%ETC% directory and then the user
configuration
antrc.cmd from the
%HOME%
directory. At this moment both
JAVA_HOME
and
ANT_HOME
must be defined
because
antenv.cmd now adds
classes.zip
or
tools.jar (depending on version of JVM) and everything
from
%ANT_HOME%\lib except
ant-*.jar
to
CLASSPATH
. Finally
ant.cmd calls
per-directory configuration
antrc.cmd. All settings made
by
ant.cmd are local and are undone when the script
ends. The settings made by
antenv.cmd are persistent
during the lifetime of the shell (of course unless called
automatically from
ant.cmd). It is thus possible to
call
antenv.cmd manually and modify some settings before
calling
ant.cmd.
Scripts
envset.cmd and
runrc.cmd perform
auxiliary tasks. All scripts have some documentation inside.
Running Ant as a background process on Unix(-like) systems
If you start Ant as a background process (like in
ant
&) 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.
Tasks that create such new processes
include
<exec>
,
<apply>
or
<java>
when the
fork attribute
is
true
.
Running Ant via Java
If you have installed Ant in the do-it-yourself way, Ant can be
started from one of two entry points:
java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]
java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]
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
-lib option and all required classes are
loaded from the
CLASSPATH
. You must ensure that all
required jars are available. At a minimum the
CLASSPATH
should include:
ant.jar and ant-launcher.jar
jars/classes for your XML parser
the JDK's required jar/zip files
The latter method supports
the
-lib,
-nouserlib,
-noclasspath
options and will load jars from the
specified
ANT_HOME
. You should start the latter with the
most minimal classpath possible, generally just
the
ant-launcher.jar.
Ant can be started in Ant via the
<java>
command.
Here is an example:
<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"/>