Running Apache Ant

Command Line

If you've installed Apache Ant as described in the Installing Ant section,running Ant from the command-line is simple: just typeant.

When no arguments are specified, Ant looks for a build.xmlfile in the current directory and, if found, uses that file as thebuild file and runs the target specified in the defaultattribute of the <project> tag.To make Ant usea build file other than build.xml, use the command-lineoption -buildfile file,where file is the name of the build file you want to use(or a directory containing a build.xml file).

You can also set properties on thecommand line. This can be done withthe -Dproperty=value option,where property is the name of the property,and value is the value for that property. If you specify aproperty that is also set in the build file(see the property task),the value specified on thecommand line will override the value specified in thebuild file.Defining properties on the command line can also be used to pass inthe value of environment variables; just pass-DMYVAR=%MYVAR% (Windows) or-DMYVAR=$MYVAR (Unix)to Ant. You can then accessthese variables inside your build file as ${MYVAR}.You can also access environment variables using the property task'senvironment attribute.

Options that affect the amount of logging output by Ant are:-quiet,which instructs Ant to print lessinformation to the console;-verbose, which causes Ant to printadditional 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 thedefault attribute of theproject tag isused.

The -projecthelp option prints out a listof the build file's targets. Targets that include adescription 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 maintargets, 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 ${user.home}/.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 seeLoggers & Listeners.

For more information about -inputhandler seeInputHandler.

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 }}

Library Directories

Prior to Ant 1.6, all jars in the ANT_HOME/lib would be added to the CLASSPATHused 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. Thedefault directories scanned are ANT_HOME/lib and a user specific directory,${user.home}/.ant/lib. This arrangement allows the Ant installation to beshared 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 jarscontaining 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 directoriesof the path will be added to Ant's classloader. The order in which jars areadded to the classpath is as follows:

• -lib jars in the order specified by the -lib elements 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 -liboption. 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) thanwe like.

The location of ${user.home}/.ant/lib is somewhat dependent on the JVM. On Unixsystems ${user.home} maps to the user's home directory whilst on recentversions of Windows it will be somewhere such asC:Documents and Settingsusername.antlib. You should consult yourJVM documentation for more details.

Examples

ant

runs Ant using the build.xml file in the current directory, onthe default target.

ant -buildfile test.xml

runs Ant using the test.xml file in the current directory, onthe default target.

ant -buildfile test.xml dist

runs Ant using the test.xml file in the current directory, onthe target called dist.

ant -buildfile test.xml -Dbuild=build/classes dist

runs Ant using the test.xml file in the current directory, onthe target called dist, setting the build propertyto 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) thefile ~/.antrc before it does anything. On Windows, the Antwrapper batch-file invokes %HOME%antrc_pre.bat at the start and%HOME%antrc_post.bat at the end. You can use thesefiles, for example, to set/unset environment variables that should only bevisible during the execution of Ant. See the next section for examples.

Environment Variables

The wrapper scripts use the following environment variables (ifset):

• 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 areavailable via Project instance, I searched for them with a

 grep -r -n "getPropert" * > ..grep.txt

If new properties get added (it happens), expect them to appear under the"ant." and "org.apache.tools.ant" prefixes, unless the developers have avery good reason to use another prefix. Accordingly, please avoid usingproperties that begin with these prefixes. This protects you from futureAnt releases breaking your build file.

return code

the ant start up scripts (in their Windows and Unix version) returnthe 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. Youshould not have any problems launching Ant from the Cygwin shell. It isimportant to note, however, that once Ant is running it is part of the JDKwhich operates as a native Windows application. The JDK is not a Cygwinexecutable, and it therefore has no knowledge of Cygwin paths, etc. Inparticular when using the <exec> task, executable names suchas "/bin/sh" will not work, even though these work from the Cygwinshell 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 describedabove. The behaviour can be modified by a number of ways explained below.

Script ant.cmd first verifies whether the Ant environment is set correctly. Therequirements 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 fromJAVA_HOME and at least one element from ANT_HOME.

If any of these conditions is violated, script antenv.cmd is called. This scriptfirst invokes configuration scripts if there exist: the system-wide configurationantconf.cmd from the %ETC% directory and then the user configurationantrc.cmd from the %HOME% directory. At this moment bothJAVA_HOME and ANT_HOME must be defined because antenv.cmdnow adds classes.zip or tools.jar (depending on version of JVM) andeverything from %ANT_HOME%lib except ant-*.jar toCLASSPATH. Finally ant.cmd calls per-directory configurationantrc.cmd. All settings made by ant.cmd are local and are undone when thescript ends. The settings made by antenv.cmd are persistent during the lifetime of theshell (of course unless called automatically from ant.cmd). It is thus possible to callantenv.cmd manually and modify some settings before calling ant.cmd.

Scripts envset.cmd and runrc.cmd perform auxiliary tasks. All scriptshave 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 startedfrom 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 usesthe Ant Launcher introduced in Ant 1.6. The former method does not supportthe -lib option and all required classes are loaded from the CLASSPATH. You mustensure that all required jars are available. At a minimum the CLASSPATH shouldinclude:

• 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 minimalclasspath possible, generally just the ant-launcher.jar.

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