Running Ant

Running Ant from the command-line is simple:

%ant [options] [target [target2 [target3] ...]]

Command-Line Options

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.

Tip

Entering ant -help on the command line generates a list of command-line options.

Table 1-14. Ant command-line options

Name

Description

-buildfile file, or -f file, or -file file

Runs the build file specified by file.

-Dproperty=value

Sets a property called property with a value of value, and passes it to Ant.

-debug, -d

Prints debugging information.

-diagnostics

Prints diagnostics about Ant.

-emacs, -e

Creates plain, emacs-friendly logging information.

-find file, or -s file

Searches for the build file (named file) along the directory structure towards the root.

-help, -h

Prints help information.

-inputhandler class

Specifies the class that will handle user text input.

-keep-going, -k

Continues to execute targets even if prior targets fail. Only targets that do not depend on failed targets are attempted.

-l file, or -l file

Uses file to log to.

-lib path

Specifies the classpath on which to search for JARs and library classes.

-listener classname

Adds an instance of classname as a listener, which is alerted when build events occur (e.g., starting and stopping of the build process).

-logger classname

Specifies the class to handle logging of Ant's output.

-noinput

Turns off interactive input.

-projecthelp, -p

Prints the project's help information (if there is any).

-propertyfile file

Loads properties from the specified file.

-quiet, -q

Reduces Ant messages to the minimum possible.

-verbose, -v

Specifies verbose output.

-version

Prints the version of Ant being used.

Executing Ant

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

Tip

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 a build file with the supplied name is found or the root of the filesystem is reached.

Customizable Environment Variables

Ant scripts, which start Ant, use some customizable environment variables:

JAVACMD

Holds the full path of the Java executable. Use this to launch a different JVM than JAVA_HOME /bin/java(.exe).

ANT_OPTS

Command-line arguments that should be passed to the JVM unchanged.

ANT_ARGS

Ant command-line arguments. These may be used, for example, to point to a different logger, a new listener, or to include the -find flag 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.

Failed Builds

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 seconds

Tip

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.

Verbose Output

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 seconds

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

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

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

Logging and Libraries

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.