Running Ant

Running Ant is simple, when you installed it as described in the previous section. Just type ant.

When nothing is specified, Ant looks for a build.xml file in the current directory. If found, it uses that file as the buildfile. If you use the -find option, Ant will search for a buildfile in the parent directory, and so on, until the root of the filesystem has been reached. To make Ant use another buildfile, use the command-line option -buildfile file, where file is the buildfile you want to use.

You can also set properties that override properties specified in the buildfile (see the property task). 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. This can also be used to pass in the value of some environment variables. You can also access environment variables using the property task. Just pass -DMYVAR=%MYVAR% (Windows) or -DMYVAR=$MYVAR (Unix) to Ant - you can then access these variables inside your buildfile as ${MYVAR}.

Two more options are: -quiet, which instructs Ant to print less information on the console when running, and -verbose, which causes Ant to print additional information to the console.

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 the description of the project, if it exists, followed by a list of this project's targets. First those with a description, then those without one.

Command-line option summary:

ant [options] [target [target2 [target3] ...]]
Options:
-help                  print this message
-projecthelp           print project help information
-version               print the version information and exit
-quiet                 be extra quiet
-verbose               be extra verbose
-debug                 print debugging information
-emacs                 produce logging information without adornments
-logfile file          use given file for log output
-logger classname      the class that is to perform logging
-listener classname    add an instance of class as a project listener
-buildfile file        use specified buildfile
-find file             search for buildfile towards the root of the filesystem and use the first one found
-Dproperty=value       set property to value

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 a target called dist.

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

runs Ant using the test.xml file in the current directory, on a target called dist, setting the build property to the value build/classes.

Files

The Ant wrapper script for Unix will source (read and evaluate) the file ~/.antrc before it does anything - the Windows batch file invokes %HOME%\antrc_pre.bat at the start and %HOME%\antrc_post.bat at the end. You can use these files to set/unset environment variables that should only be visible during the execution of Ant. See the next section for example.

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 properties or set the maximum Java heap size here.

Running Ant by Hand

If you have installed Ant in the do-it-yourself way, Ant can be started with:

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]

These instructions actually do exactly the same as the ant command. The options and target are the same as when running Ant with the ant command. This example assumes you have set your classpath to include:

ant.jar
jars/classes for your XML parser
the JDK's required jar/zip files