Running Ant from the command-line is simple:
%ant [options] [target [target2 [target3] ...]]
options are one or more of the command-line options that begin
with a hyphen, listed in Table
1-14; target,
target2, etc., are the specific targets you
want to run in the event you don't want to defer to the project element's default target.
Table 1-14. Ant command-line options
If you want to use a build file named
build.xml and want to run the default target,
enter ant in the directory
containing the build file:
%ant
For example, if you ran the build file from Example 1-2, that command gives this result:
-bash-2.05b$ ant
Buildfile: build.xml
compile:
[javac] Compiling 1 source file
compress:
[jar] Building jar: /home/httpd/vhosts/builder/Project.jar
main:
[echo]
[echo] Building the .jar file.
[echo]
BUILD SUCCESSFUL
Total time: 2 seconds Each build file requires a default target, but you can
specify the target(s) you want Ant to run via the command line. For
example, add a target named clean
to the build file (using Example
1-2 as a starting point):
<project default="main">
<target name="main" depends="compile, compress">
<echo>
Building the .jar file.
</echo>
</target>
<target name="compile">
<javac srcdir="."/>
</target>
<target name="compress">
<jar jarfile="Project.jar" basedir="." includes="*.class" />
</target>
<target name="clean">
<delete file="*.class"/>
<delete file="*.jar"/>
</target>
</project>You can then specify the clean target from the command line:
%ant clean
If you want to run multiple targets, you can list them (in the order they should be run):
%ant clean compile compress
Tip
If you don't want to allow a target to be run from the command
line, you can start the target name with a hyphen (e.g., -clean). This will make Ant think the
target is a command-line option, and since -clean isn't a valid command-line option,
Ant will refuse to run that target directly.
By default, the build file that Ant looks for is build.xml, but you can name the file as you want.
Tip
The downloadable example code for Ant has multiple build filenames to make the separation of examples clearer.
For example, if you have a build file named
project.xml that you want to use, you can specify
that Ant should use that build file with -f (or -file or -buildfile):
%ant -f project.xml
Ant scripts, which start Ant, use some customizable environment variables:
JAVACMDHolds the full path of the Java executable. Use this to launch a different JVM than
JAVA_HOME/bin/java(.exe).ANT_OPTSCommand-line arguments that should be passed to the JVM unchanged.
ANT_ARGSAnt command-line arguments. These may be used, for example, to point to a different logger, a new listener, or to include the
-findflag in all invocations of Ant.
Tip
The Ant wrapper script for Unix will read the file
~/.antrc before it starts running. On Windows,
the Ant wrapper batchfile ant.bat invokes
%HOME%
\antrc_pre.bat at the start of the Ant process
and %HOME%
\antrc_post.bat at the end of that process. You
can use these files to set or unset environment variables that
should only be used during the execution of Ant.
Every Ant developer has builds that fail for one reason
or another. Ant does its best to pinpoint the problem. For example,
say you misspelled the name of the javac task:
<?xml version="1.0" ?>
<project default="main">
<target name="main" depends="compile, compress">
<echo>
Building the .jar file.
</echo>
</target>
<target name="compile">
<jjavac srcdir="."/>
</target>
.
.
.Ant will diagnose this problem when it runs and give you some feedback:
%ant build.xml:10: Could not create task or type of type: jjavac. Ant could not find the task or a class this task relies upon. This is common and has a number of causes; the usual solutions are to read the manual pages then download and install needed JAR files, or fix the build file: - You have misspelt 'jjavac'. Fix: check your spelling. - The task needs an external JAR file to execute and this is not found at the right place in the classpath. Fix: check the documentation for dependencies. Fix: declare the task. - The task is an Ant optional task and optional.jar is absent Fix: look for optional.jar in ANT_HOME/lib, download if needed - The task was not built into optional.jar as dependent libraries were not found at build time. Fix: look in the JAR to verify, then rebuild with the needed libraries, or download a release version from apache.org - The build file was written for a later version of Ant Fix: upgrade to at least the latest release version of Ant - The task is not an Ant core or optional task and needs to be declared using <taskdef>. Remember that for JAR files to be visible to Ant tasks implemented in ANT_HOME/lib, the files must be in the same directory or on the classpath Please neither file bug reports on this problem, nor email the Ant mailing lists, until all of these causes have been explored, as this is not an Ant bug. Total time: 0 seconds
Sometimes errors won't stop a build, and you may want to
change that behavior so the build will terminate when there's been any
kind of problem. Most tasks have a failonerror attribute, which is set to false
by default. Setting this attribute's value to true makes the build
fail if the task encounters an error, allowing you to stop a build if
a specific task generates errors .
Keep in mind that this won't affect your build in the case where you've previously executed the build and your output files are up to date. By default, Ant tasks check to see if the output files they're supposed to create are current (i.e., the output file is more recent than the files used to create it); if they are, Ant tasks won't recreate them because Ant considers the target executed. For example, here's what you'd see when you run the example build file a second timeAnt displays the names of the various targets but, because they're up to date, it doesn't execute them:
%ant
Buildfile: build.xml
compile:
compress:
main:
[echo]
[echo] Building the .jar file.
[echo]
BUILD SUCCESSFUL
Total time: 3 secondsTip
Ant doesn't come with a built-in debugger, which can make it tough to troubleshoot build files. However, one of the items under development in the Java Eclipse IDE is an Ant build file debugger. Chapter 11 has more on integrating Ant into Eclipse.
You can control the amount of output Ant gives you when
it runs with the -verbose, -quiet, and -debug command-line options. If you ask Ant
to be quiet, it won't display anything except for build failure or
success, total build time, and any text you specifically output via
the echo task. Here's an example of
a quiet build:
%ant -quiet
[echo]
[echo] Building the .jar file.
[echo]
BUILD SUCCESSFUL
Total time: 2 secondsOn the other side of the coin, the -verbose option gives you a lot more
information than normal, including whether Ant is skipping up-to-date
output files, what OS or JDK you're using, and a lot more. Here's what
you might see from a verbose build on Unix:
-bash-2.05b$ ant -verbose
Apache Ant version 1.6.1 compiled on February 12 2004
Buildfile: build.xml
Detected Java version: 1.4 in: /opt/j2sdk1.4.2_02/jre
Detected OS: Linux
parsing buildfile /home/build.xml
Project base dir set to: /home
Build sequence for target `main' is [compile, compress, main]
Complete build sequence is [compile, compress, main, clean, ]
compile:
[javac] Project.class skipped - don't know how to handle it
[javac] Project.jar skipped - don't know how to handle it
[javac] Project.java omitted as Project.class is up to date.
[javac] build.xml skipped - don't know how to handle it
compress:
[jar] Project.class omitted as Project.class is up to date.
main:
[echo]
[echo] Building the .jar file.
[echo]
BUILD SUCCESSFUL
Total time: 1 secondThis output shows that Ant is skipping up-to-date output targets. Here's similar output in Windows:
%ant -verbose
Apache Ant version 1.6.1 compiled on February 12 2004
Buildfile: build.xml
Detected Java version: 1.4 in: C:\jdk1.4
Detected OS: Windows 2000
parsing buildfile C:\ant\ch01\build.xml with URI = file:///C:/ant/ch01/build.xml
Project base dir set to: C:\ant\ch01
Build sequence for target `main' is [compile, compress, main]
Complete build sequence is [compile, compress, main, clean, ]
compile:
[javac] Project.class skipped - don't know how to handle it
[javac] Project.jar skipped - don't know how to handle it
[javac] Project.java omitted as Project.class is up to date.
[javac] build.xml skipped - don't know how to handle it
compress:
[jar] Project.class omitted as Project.class is up to date.
main:
[echo]
[echo] Building the .jar file.
[echo]
BUILD SUCCESSFUL
Total time: 2 secondsThe -debug options
prints out even more information—often pages of it—which isn't
reproduced here. Included in a debugging build is information about
classes as they're loaded, classes that Ant looked for but couldn't
find, the locations where Ant is picking up library files, and almost
everything else you could think of.
Another useful command-line option for displaying
information is the -projecthelp
option, which 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 "Subtargets", and then the
"Default" target is listed.
Here's the example build file, with the addition of a
description attribute for each
target element:
<?xml version="1.0" ?>
<project default="main">
<target name="main" depends="compile, compress" description="Main target">
<echo>
Building the .jar file.
</echo>
</target>
<target name="compile" description="Compilation target">
<javac srcdir="."/>
</target>
<target name="compress" description="Compression target">
<jar jarfile="Project.jar" basedir="." includes="*.class" />
</target>
</project>
Here's what you'd see
when running Ant with the -projecthelp option:
%ant -projecthelp Buildfile: build.xml Main targets: compile Compilation target compress Compression target main Main target Default target: main
You can log the output of running Ant using the -logfile option. For example, here's how
you'd sent output to a file named
file.log:
%ant -logfile file.log
You can log part of a build file's results with the
record task; for example, if you
were using the javac task to
compile code and wanted to log the output of this task to a file named
log.txt, you could start and stop that logging
this way:
<record name="log.txt" action="start"/>
<javac ... />
<record name="log.txt" action="stop"/>Another handy option is the -lib option, which adds additional
directories to be searched for .jar or
.class files. Here's an example, which adds
/home/ant/morejars to the library search
path:
%ant -lib /home/ant/morejars
The -lib option is
useful when you're working on a system where you don't have access to
the Ant lib directory as is often the case when
dealing with Internet Service Providers (ISPs). Using this option, you
can make sure Ant has access to JAR files needed for Ant's optional
tasks without having to load them into directories you don't have
permission to access.
Tip
Before Ant 1.6, all JARS in the ANT_HOME /lib would
be added to the CLASSPATH used to
run Ant. Since Ant 1.6, two directories are scanned—ANT_HOME /lib and
.ant/lib—in the Java user home directory. You
can place additional library files in this directory if you don't
have access to ANT_HOME
/lib. The location of the Java user home
directory depends on your JVM settings. In Unix, it's usually your
home directory (so you'd store additional Ant libraries in, for
example, /home/
username /.ant/lib).
In Windows, it's usually C:\Documents and
Settings\ username (so you'd
store additional Ant libraries in C:\Documents and
Settings\ username
\.ant\lib). To determine where your Java user
home is, use this element in a build file:
<echo>${user.home}</echo>Get Ant: The Definitive Guide, 2nd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
