Running Apache Ant

# Running Ant

## Command Line

If you've installed 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.

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 `-Dproperty=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; and `-debug`, which causes Ant to print considerably more additional information.

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
      -projecthelp, -p       print project help information
      -version               print the version information and exit
      -diagnostics           print information that might be helpful to
                             diagnose or report problems.
      -quiet, -q             be extra quiet
      -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 /home/kev/.ant/lib
      -noclasspath           Run ant without using CLASSPATH
      -autoproxy             Java 1.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. From 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, /home/kev/.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 adminstrators.

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:

- -lib jars in the order specified by the -lib elements on the command line
- jars from /home/kev/.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 /home/kev/.ant/lib is somewhat dependent on the JVM. On Unix systems /home/kev maps to the user's home directory whilst on recent versions of Windows it will be somewhere such as C:\Documents and Settings\username\.ant\lib. You should consult your JVM documentation for more details.

### Examples

>     ant

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

### 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. If not defined an object of org.apache.tools.ant.PropertyHelper will be used as PropertyHelper.
`ant.regexp.regexpimpl` | classname | classname for a RegExp implementation; if not set Ant tries to find another (JDK14+, Apache Oro...); 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` | name | 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` | boolean (default true) | 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 flag | see javac "Jikes Notes"
`build.rmic` | name | control the rmic compiler
`build.sysclasspath` | "only", something else | only: current threads get the actual class loader (AntClassLoader.setThreadContextLoader()). else: use core loader as default (ComponentHelper.initTasks()). Disable changing the classloader (oata.taskdefs.Classloader.execute() experimental task).
`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 source-, dest- 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` | 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.ProjectHelper') | specifies the classname to use as ProjectHelper. The class must extend org.apache.tools.ant.ProjectHelper.
`p4.port, p4.client, p4.user` | several formats | Specify defaults for port-, client- and user-setting of the perforce tasks.
`websphere.home` | path | Points to home directory of websphere. see EJB Tasks
`XmlLogger.file` | filename (default 'log.xml') | Name for the logfile for MailLogger.

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

the 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.

## Cygwin Users

The 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:

1. Environment variable `JAVA_HOME` is set.
2. Environment variable `ANT_HOME` is set.
3. 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 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="/home/kev/workspace/ant-core-171/bootstrap/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>