Running Ant

The ant script (ant on Unix, ant.bat or ant.cmd on Windows) finds Java, builds a minimal class path and starts org.apache.tools.ant.launch.Launcher, which in turn starts Ant proper. Everything after the options is a list of targets. With no targets, Ant runs the default target named on the <project> element; with no -f option it looks for build.xml in the current directory. The command is the same in a terminal and in continuous integration (see CI & IDE Integration).

The examples below use this build file. It has a default target, descriptions, a deliberately failing target and a target that reads from the console, which together exercise the options.

Running ant with no arguments compiles and packages, because jar is the default target and depends on compile:

Source: Apache Ant manual: Command Line

ant -help prints the list of options. The output below is the one printed by 1.10.18, including the three script options that only the Unix wrapper accepts.

The sections that follow group the options by what they do. Neither Maven nor Gradle has an equivalent single-letter zoo: the Maven options are on Running Maven (CLI) and the Gradle ones on Command-Line Interface.

Source: Apache Ant manual: Command-line Options Summary

-version prints the version and exits. -help (or -h) prints the table above. -diagnostics prints a report meant to be pasted into a bug report: the Ant version, the jars in ANT_HOME/lib and in ${user.home}/.ant/lib, which optional tasks are unavailable because a library is missing, the XML parser and XSLT processor in use, the system properties, the temporary directory and the proxy settings.

The start of the diagnostics report, and the "Tasks availability" section that explains most "task not found" surprises, look like this (the full report is a few hundred lines; the elisions are marked):

The user.home line was replaced by a placeholder here; the report is otherwise unedited. The jars to add to fix each missing dependency are in the optional-library table on Installation.

-projecthelp (-p) lists the targets of the build file and exits without running anything. A target with a description attribute is listed under "Main targets"; targets without one are "Other targets" and are shown only when there are no main targets or when -verbose or -debug is also given. The project <description> is printed first.

Adding -v also lists after-broken under "Other targets", because it has no description. This is why a build file meant to be used by others gives a description to every target that is a public entry point and none to internal ones; see Targets & Extension Points.

Source: Apache Ant manual: Command Line

-buildfile <file> (also -file and -f) names the build file. If the argument is a directory, Ant uses the build.xml in it. The default is build.xml in the current directory. The file name is arbitrary; the examples run noasc.xml, a one-target file, and the project directory itself:

A file that does not exist is not an Ant error with a stack trace; it is a short message and exit code 1:

-find [file] (also -s) searches for the build file in the current directory, then in its parent, and so on up to the root of the file system. By default it looks for build.xml. This is how a build can be started from any subdirectory of a single-build-file project. The catch, stated in the manual, is that if more options follow -find, the file name argument is required even when it is build.xml, because the next word would otherwise be consumed as the name. From a subdirectory two levels below the project:

The second command is the classic mistake: -s swallowed -q as the file name to search for. The third shows plain ant not looking upwards. The same rule applies to -find inside ANT_ARGS, described below.

Ant sets the basedir of the project to the directory containing the build file unless the basedir attribute says otherwise, so relative paths in the build file are relative to the build file, not to the current directory. That is why the same build behaves identically when started with -f ../other/build.xml from elsewhere.

Source: Apache Ant manual: Command Line

Targets are listed after the options and run in order, each one after the targets it depends on, and each target at most once per invocation. ant clean jar runs clean, then compile and jar. A target name that does not exist fails the build before anything runs:

A failing task stops the build at the first failure. The error line names the build file and the line of the failing task (build.xml:25, the <fail>):

-keep-going (-k) changes that: after a target fails, Ant carries on with the other requested targets that do not depend on the failed one. It still ends with BUILD FAILED and exit code 1.

-k is useful on a continuous integration server that should report as many independent failures as possible in one run, and in a build with several unrelated test targets. For target conditions (if, unless) and the lifecycle-like extension points, see Targets & Extension Points.

Source: Apache Ant manual: Command Line

-D<property>=<value> sets a property. Properties set on the command line are user properties: they cannot be overridden by a <property> task in the build file, because properties in Ant are immutable once set and the command line sets them first. That is how a build file’s defaults (<property name="greeting" .../>) are overridden from outside. The props target prints a few:

An unset property is not an error: the text ${ant.tmpdir} is left as is, which is the most common reason for a path like ${build.dir}/classes appearing literally in a directory listing. ant -v adds a line for each one that is used and unset (Property "ant.tmpdir" has not been set). Environment variables can be passed with -DMYVAR=$MYVAR (Unix) or -DMYVAR=%MYVAR% (Windows), or read inside the build file with <property environment="env"/>; how properties are resolved is on Properties.

-propertyfile <name> loads every property in a file as if each had been given with -D, so they too are user properties. When both are present the -D value wins. With this release.properties:

The Maven counterpart is -Dkey=value (system properties read by plugins) and the Gradle one is -Pname=value for project properties and -D for JVM system properties; see Comparing Ant, Maven & Gradle.

Source: Apache Ant manual: Command Line

Four options change the amount of logging, in order of increasing volume: -silent (-S) prints only task output and build failures, -quiet (-q) prints less than normal, the default, -verbose (-v) and -debug (-d). The messages Ant prints are produced at the levels error, warn, info, verbose and debug; tasks choose a level for each message (the <echo> task has a level attribute), and the option decides how many levels reach the screen.

-S is the option to use when a script captures Ant’s output: little but what the tasks print remains (here the <echo> text, with no [echo] prefix, after the Buildfile: line that 1.10.18 still prints).

-verbose shows, for this build, the version, the Java and OS detected, how the build file was found, the parsing of the build file, the base directory, the build sequence and every unset property that is used. -debug adds a message for each property set, each class loaded and each task configured. Both are the first thing to try when a build does something unexpected; the build sequence line is a quick way to see which targets will run and in which order.

-emacs (-e) removes the [task] prefix and the indentation so that each message starts at column 0. It was designed for editors that parse compiler messages from the log and for tools that dislike the leading spaces:

-logfile <file> (also -l) sends the output to a file instead of the console. Nothing is printed to the terminal, and the file receives exactly what the console would have shown at the chosen level:

Source: Apache Ant manual: Command Line

A logger formats and prints the build’s messages; a listener is notified of build events (target started, task finished, message logged) and may do anything. -logger <classname> replaces the default logger (org.apache.tools.ant.DefaultLogger) and there can be only one. -listener <classname> adds a listener, and there can be several. Ant ships several in org.apache.tools.ant.listener (for example TimestampedLogger, AnsiColorLogger, MailLogger, BigProjectLogger, ProfileLogger) and org.apache.tools.ant (XmlLogger, NoBannerLogger); -logger takes the first kind:

Passing a logger class to -listener is the classic mistake. Loggers are also listeners, but a logger given to -listener is never handed an output stream (that is done for the logger chosen with -logger), and the build ends with a stack trace after the "BUILD SUCCESSFUL" line and exit code 1:

Writing your own logger or listener is covered on Listeners, Loggers & Input Handlers, which also lists every provided class.

-noinput tells Ant that nobody is at the keyboard, so tasks such as <input> must not wait. With -noinput the ask target fails at once instead of hanging a CI job:

Without the option, a piped answer is read from the standard input:

-inputhandler <class> chooses the class that answers the <input> task. The provided PropertyFileInputHandler reads the answers from a Java properties file, using the prompt text as the key. The file is named by the Java system property ant.input.properties, not by an Ant property, so it is passed through ANT_OPTS; the same build with -D on the Ant command line fails (the property exists for Ant, but the handler reads the JVM’s):

With answers.properties containing the escaped key Station\ id?=BOS:

If the key is missing the build fails with Unable to find input for 'Station id?'. The <input> task itself is on Utility Tasks.

Source: Apache Ant manual: InputHandler

Source: Apache Ant manual: Loggers & Listeners

Since Ant 1.6 the jars that Ant itself, its optional tasks and third-party tasks run on come from library directories, not from the CLASSPATH. Two directories are scanned by default, ANT_HOME/lib and ${user.home}/.ant/lib; the first is shared by every user of the installation and the second is private to one user, so an administrator can lock the installation down while a developer still adds, say, the JSch jar for <scp>. More can be added with -lib <path>, a path of jars and directories (: or ; separated as the platform requires, or the option repeated). The order in which they are searched is:

The CLASSPATH environment variable is converted into one more -lib option, because the launcher starts Ant itself with a minimal class path. Ant is happy with an empty CLASSPATH; -noclasspath enforces that, and -nouserlib skips the user directory. The documentation recommends never setting CLASSPATH for Ant: most class path problems reported against Ant (and many quoting problems) come from it. Typical uses:

A directory that does not exist is ignored without a message, so a typo in -lib surfaces later as an unknown task or missing class rather than at the option itself:

The proper way for a project to bring its own task jars is to load them from the build file with a <taskdef> and a class path, or from an antlib (see Antlibs & Namespaces); -lib is for jars that must be on Ant’s own class loader. Downloading the libraries for the optional tasks is described on Installation; resolving a project’s own dependencies is the job of Ivy or the Maven Resolver Ant Tasks (see Ivy Overview and Maven Resolver Ant Tasks).

Source: Apache Ant manual: Library Directories

Source: Apache Ant manual: Command-line Options Summary

On Unix the ant script sources (reads and evaluates) /etc/ant.conf, $HOME/.ant/ant.conf and $HOME/.antrc before it does anything else; on Windows the batch file runs %HOME%\antrc_pre.bat first and %HOME%\antrc_post.bat last. They are the place to set variables that only Ant should see, such as JAVA_HOME for a different JDK or ANT_OPTS. The --noconfig script option suppresses them. A one-line .antrc in a scratch home directory:

A hidden .antrc is a classic reason why the same build behaves differently for two developers; --noconfig and --execdebug (below) are the way to find out.

Source: Apache Ant manual: Files

The wrapper scripts use these variables when they are set. The installation variables JAVA_HOME and ANT_HOME are described on Installation; Ant 1.10.x finds ANT_HOME from the script’s own location, so only JAVA_HOME is normally needed.

--execdebug prints the Java command the script is about to run, which shows precisely how the variables were applied:

ANT_ARGS prepends options to every run, which is a convenient way to set a team-wide default and a surprising one for a build that behaves differently on a machine that has it set:

A wrong JAVACMD produces the script’s own message, not an Ant one, and exit code 1:

Source: Apache Ant manual: Environment Variables

Some of Ant’s core classes read Java system properties. They are set with ANT_OPTS (or java -Dname=value when starting Ant by hand), because they must reach the JVM, not Ant’s own property table. A few of them are listed here; the manual has the full table.

Properties starting with ant. or org.apache.tools.ant. are reserved: the manual asks build files to avoid inventing names in those prefixes because future releases may add them.

Temporary directory. Tasks that need temporary files use java.io.tmpdir by default, and tmp directories shared between users can leak sensitive information or let an attacker inject source files into the build. Since Ant 1.10.8 the Ant property ant.tmpdir takes precedence over java.io.tmpdir when set, and, unlike the JVM property, can be set from the command line or from the build file. Since Ant 1.10.9, when ant.tmpdir is not set, Ant creates a build-specific directory under java.io.tmpdir, accessible only to the current user where the file system allows it. The manual recommends pointing ant.tmpdir at a directory owned by the user running Ant with 0700 permissions. Tasks that are not shipped with Ant ignore ant.tmpdir unless they were adapted to the 1.10.8 API.

Source: Apache Ant manual: Java System Properties

Source: Apache Ant manual: Temporary Directories

The scripts are a convenience. Ant can be started from any process with a JVM, which is how an IDE or a build server does it when it does not use the scripts. There are two entry points:

Handing -lib to Main is rejected, with an explanation of the common cause (a mismatch between the script and Ant itself, for instance a newer ant script on the PATH with an older ANT_HOME):

Starting Ant from Java code, with a Project object and a build listener, is on Embedding Ant. Calling another build from a build file is the <ant> and <subant> tasks, on Multi-File Builds: import, include & subant.

Source: Apache Ant manual: Running Ant via Java

The start-up scripts return the exit code of the Java process: 0 for a successful build and a non-zero value, in practice 1, for a failed one. That covers every case shown above: a failed task (ant broken), an unknown target, a missing build file, -k with a failure, an unusable JAVACMD, and a logging exception as in the -listener mistake. A CI job needs nothing more than that status: the failure of the job follows the failure of the command. To change the exit behaviour, the manual suggests subclassing org.apache.tools.ant.Main, overriding exit(int) (for example to not exit the JVM when Ant is run inside another program) and starting Ant with -lib pointing at that class (not run here). The <fail> task has a status attribute for a build that wants a specific exit code.

Source: Apache Ant manual: return code

The same ideas under Maven and Gradle are on Running Maven (CLI) and Command-Line Interface; the tool-independent view is on Build Automation Fundamentals. The properties that a build reads are the subject of Properties.