by
Version 1.2 - 2000/10/24
Ant is a Java based build tool. In theory it is kind of like make without make's wrinkles.
Why another build tool when there is already make, gnumake, nmake, jam, and others? Because all of those tools have limitations that its original author couldn't live with when developing software across multiple platforms. Make like tools are inherently shell based. They evaluate a set of dependencies and then execute commands not unlike what you would issue on a shell. This means that you can easily extend these tools by using or writing any program for the OS that you are working on. However, this also means that you limit yourself to the OS, or at least the OS type such as Unix, that you are working on.
Makefiles are inherently evil as well. Anybody who has worked on them for any time has run into the dreaded tab problem. "Is my command not executing because I have a space in front of my tab!!!" said the original author of Ant way too many times. Tools like Jam took care of this to a great degree, but still use yet another format to use and remember.
Ant is different. Instead a model where it is extended with shell based commands, it is extended using Java classes. Instead of writing shell commands, the configuration files are XML based calling out a target tree where various tasks get executed. Each task is run by an object which implements a particular Task interface.
Granted, this removes some of the expressive power that is inherent by being able to construct a shell command such as `find . -name foo -exec rm {}` but it gives you the ability to be cross platform. To work anywhere and everywhere. And hey, if you really need to execute a shell command, Ant has an exec rule that allows different commands to be executed based on the OS that it is executing on.
The latest stable version of Ant can be downloaded from http://jakarta.apache.org/builds/ant/release/v1.2/bin/. If you like living on the edge, you can download the latest version from http://jakarta.apache.org/builds/ant/nightly/.
If you prefer the source edition, you can download Ant from http://jakarta.apache.org/builds/ant/release/v1.2/src/ (latest stable) or from http://jakarta.apache.org/from-cvs/jakarta-ant/ (current). See the section Building Ant on how to build Ant from the source code.
To build and use ant you must have a JAXP compliant XML parser installed and available on your classpath.
If you do not have a JAXP compliant XML parse installed, you may use the reference implementation available from Sun. It is available from http://java.sun.com/xml. Once installed make sure the "jaxp.jar" and "parser.jar" files are in your classpath.
You will also need the JDK installed on your system, version 1.1 or later.
Go to the directory jakarta-ant.
Make sure the JDK is in you path.
Set the JAVA_HOME environment variable. This should be set to the directory where the JDK is installed. See Installing Ant for examples on how to do this for your operating system.
Run bootstrap.bat (Windows) or bootstrap.sh (UNIX)
to build a bootstrap version of Ant.
When finished, use
build.bat -Dant.dist.dir=<directory to install Ant> dist
for Windows, and
build.sh -Dant.dist.dir=<directory to install Ant> dist
for UNIX, to create a binary distribution of Ant. This distribution can be found in the directory you specified.
The binary distribution of Ant consists of three directories: bin,
docs and lib. Only the bin and lib
directory are crucial for running Ant. To run Ant, the following must be done:
bin directory to your path.bin and lib directory.Assume Ant is installed in c:\ant\. The following sets up the
environment:
set ANT_HOME=c:\ant set JAVA_HOME=c:\jdk1.2.2 set PATH=%PATH%;%ANT_HOME%\bin
Assume Ant is installed in /usr/local/ant. The following sets up
the environment:
export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk-1.2.2
export PATH=${PATH}:${ANT_HOME}/bin
There are lots of variants that can be used to run Ant. What you need is at least the following:
The classpath for Ant must contain ant.jar and any jars/classes
needed for your chosen JAXP compliant XML parser.
When you need JDK functionality (like a javac task, or a
rmic task), then for JDK 1.1, the classes.zip
file of the JDK must be added to the classpath; for JDK 1.2 or JDK 1.3, tools.jar
must be added. The scripts supplied with ant, in the bin directory, will add
tools.jar automatically if the JAVA_HOME environment variable is set.
When you are executing platform specific applications (like the exec task, or the cvs task), the property ant.home
must be set to the directory containing a bin directory, which contains the antRun
shell script necessary to run execs on Unix.
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. When found, it uses that file as a
buildfile, otherwise it searches in the parent directory and so on
until the root of the filesystem has been reached. To make Ant use
another buildfile, use the commandline option -buildfile
<file>, where <file> is the buildfile you want
to use.
You can also set properties which override properties specified in the buildfile (see the property task). This can be done with the -D<property>=<value> option, where <property> is the name of the property and <value> the value. This can also be used (and is the only way since Java can not access them) to have access to your 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}.
Two more options are -quiet which instructs Ant to print less information on the console when running. The option -verbose on the other hand makes Ant print more information on the console.
It is also possible to specify one or more targets that should be executed. When omitted the target that is mentioned in the default attribute of the project is used.
The -projecthelp option gives a list of this projects targets. First those with a description and then those without one.
Commandline 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 -logger <classname> the class which is to perform logging -listener <classname> add an instance of class as a project listener -buildfile <file> use given buildfile -D<property>=<value> use value for given property
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. It also sets the build property to the
value build/classes.
When 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 up your classpath to include
The buildfile is written in XML. Each buildfile contains one project.
Each element of the buildfile can have an id attribute and
can later be referred to by the value supplied to this. The value has
to be unique.
A project has three attributes:
| Attribute | Description | Required |
| name | the name of the target. | Yes |
| default | the default target to use when no target is supplied. | Yes |
| basedir | the base directory from which all path calculations are done. This attribute might be overridden by setting the "basedir" property on forehand. When this is done, it might be omitted in the project tag. | Yes |
Each project defines one or more targets. A target is a set of tasks you want to be executed. When starting Ant, you can select which target you want to have executed. When no target is given, the project's default is used.
A target can depend on other targets. You might have a target for compiling, for instance, and a target for creating a distributable. You can only build a distributable when you have compiled first, so the distribute target depends on the compile target. Ant resolves all these dependencies.
Ant tries to execute the targets in the depends attribute in the order they appear (from left to right). Keep in mind that it is possible that a target can get executed earlier when an earlier target depends on it:
<target name="A"/> <target name="B" depends="A"/> <target name="C" depends="B"/> <target name="D" depends="C,B,A"/>
Suppose we want to execute target D. From its depends attribute, you might think that first target C, then B and then A is executed. Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.
A target gets executed only once. Even when more targets depend on it (see the previous example).
A target has also the ability to perform its execution if (or unless) a property has been set. This allows, for example, better control on the building process depending on the state of the system (java version, OS, command line properties, etc...). To make target sense this property you should add the if (or unless) attribute with the name of the property that the target should react to, for example
<target name="build-module-A" if="module-A-present"/><target name="build-own-fake-module-A" unless="module-A-present"/>
If no if and no unless attribute is present, the target will always be executed.
It is a good practice to place your tstamp tasks in a so called initialization target, on which all other targets depend. Make sure that target is always the first one in the depends list of the other targets. In this manual, most initialization targets have the name "init".
The optional description attribute can be used to provide a one line description of this target that is printed by the -projecthelp commandline option.
A target has the following attributes:
| Attribute | Description | Required |
| name | the name of the target. | Yes |
| depends | a comma separated list of names of targets on which this target depends. | No |
| if | the name of the property that must be set in order for this target to execute. | No |
| unless | the name of the property that must not be set in order for this target to execute. | No |
| description | a short description of this targets function. | No |
A task is a piece of code that can be executed.
A task can have multiple attributes (or arguments if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed.
Tasks have a common structure:
<name attribute1="value1" attribute2="value2" ... />
where name is the name of the task, attribute-x the attribute name, and value-x the value of this attribute.
There is a set of built in tasks, but it is also very easy to write your own.
All tasks share a taskname attribute. The value of
this attribute will be used in the logging messages generated by
Ant.
A project can have a set of properties. These might be set in the buildfile by the property task, or might be set outside Ant. A property has a name and a value. Properties might be used in in the value of task attributes. This is done by placing the property name between "${" and "}" in the attribute value.
If there is a property called "builddir" with the value "build", then this could be used in an attribute like this: "${builddir}/classes". This is resolved as "build/classes".
Ant provides access to all system properties as if they had been defined using a property task, for example ${os.name} expands to the name of the operating system.
In addition Ant knows some built in properties:
<project name="MyProject" default="dist" basedir=".">
<!-- set global properties for this build -->
<property name="src" value="." />
<property name="build" value="build" />
<property name="dist" value="dist" />
<target name="prepare">
<!-- Create the time stamp -->
<tstamp/>
<!-- Create the build directory structure used by compile -->
<mkdir dir="${build}" />
</target>
<target name="compile" depends="prepare">
<!-- Compile the java code from ${src} into ${build} -->
<javac srcdir="${src}" destdir="${build}" />
</target>
<target name="dist" depends="compile">
<!-- Create the ${dist}/lib directory -->
<mkdir dir="${dist}/lib" />
<!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
<jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}" />
</target>
<target name="clean">
<!-- Delete the ${build} and ${dist} directory trees -->
<delete dir="${build}" />
<delete dir="${dist}" />
</target>
</project>
A project can have a set of tokens that might be automatically expanded if found when a file is copied, when the filtering-copy behavior is selected in the tasks that support this. These might be set in the buildfile by the filter task.
Since this can be a very harmful behavior, the tokens in the files must be of the form @token@ where token is the token name that is set in the filter task. This token syntax matches the syntax of other build systems that perform such filtering and remains sufficiently orthogonal to most programming and scripting languages, as well with documentation systems.
Note: in case a token with the format @token@ is found in a file but no filter is associated with that token, no changes take place. So, no escaping method is present, but as long as you choose appropriate names for your tokens, this should not cause problems.
You can specify PATH and CLASSPATH variables using both ":" and ";" as separator characters, Ant will convert it to the correct character of the current operating system.
Wherever PATH like values need to be specified a nested element can be used. This takes the general form of
<classpath>
<pathelement path="${classpath}" />
<pathelement location="lib/helper.jar" />
</classpath>
The location attribute specifies a single file or
directory relative to the project's base directory (or an absolute
filename), while the path attribute accepts ":"
or ";" separated lists of locations. The path
attribute is intended to be used with predefined paths - in any other
case multiple elements with location attributes should be
preferred.
As a shortcut the surrounding PATH element supports path and location attributes of its own, so
<classpath>
<pathelement path="${classpath}" />
</classpath>
can be abreviated to
<classpath path="${classpath}" />
In addition, FileSets can be specified via
nested <fileset> elements. The order in which the files
building up FileSet are added to the PATH like structure is not
defined.
<classpath>
<pathelement path="${classpath}" />
<fileset dir="lib">
<include name="**/*.jar" />
</fileset;>
<pathelement location="classes" />
</classpath>
Builds a PATH which holds the value of ${classpath}
followed by all JAR files in the lib directory, followed
by the classes directory.
If you want to use the same PATH like structure for several tasks,
you can define them with a <path> element at the
same level as targets and reference them via their
id attribute - see References for an
example.
A PATH like structure can include a reference to another PATH like
structure via a nested <path> elements.
<path id="base.path">
<pathelement path="${classpath}" />
<fileset dir="lib">
<include name="**/*.jar" />
</fileset;>
<pathelement location="classes" />
</path>
<path id="tests.path">
<path refid="base.path" />
<pathelement location="testclasses" />
</path>
Several tasks take arguments that shall be passed to another process on the command line. To make it easier to specify arguments that contain space characters, nested elements can be used.
| Attribute | Description | Required |
| value | a single command line argument, can contain space characters. | Exactly one of these. |
| line | a space delimited list of command line arguments. | |
| file | The name of a file as a single command line argument. Will be replaced with the absolute filename of the file by Ant. | |
| path | A string that shall be treated as a PATH like string as a single command line argument. You can use ; or : as path separators and Ant will convert it to the platform's local conventions. |
<arg value="-l -a" />
is a single command line argument containing a space character.
<arg line="-l -a" />
stands for two separate command line arguments.
<arg path="/dir;/dir2:\dir3" />
is a single command line argument with value
\dir;\dir2;\dir3 on DOS based systems and
/dir:/dir2:/dir3 on Unix like systems.
The id attribute of the buildfile's elements can be
used to refer to them. This can useful if you are going to replicate
the same snippet of XML over and over again - using a
<classpath> structure more than once for
example.
The following example
<project ... >
<target ... >
<rmic ...>
<classpath>
<pathelement location="lib/" />
<pathelement path="${java.class.path}/" />
<pathelement path="${additional.path}" />
</classpath>
</rmic>
</target>
<target ... >
<javac ...>
<classpath>
<pathelement location="lib/" />
<pathelement path="${java.class.path}/" />
<pathelement path="${additional.path}" />
</classpath>
</javac>
</target>
</project>
could be rewritten as
<project ... >
<path id="project.class.path">
<pathelement location="lib/" />
<pathelement path="${java.class.path}/" />
<pathelement path="${additional.path}" />
</path>
<target ... >
<rmic ...>
<classpath refid="project.class.path" />
</rmic>
</target>
<target ... >
<javac ...>
<classpath refid="project.class.path" />
</javac>
</target>
</project>
All tasks that use nested elements for PatternSets, FileSets or PATH like structures accept references to these structures as well.
Some tasks use directory trees for the task they perform. For instance, the Javac task which works upon a directory tree with .java files. Sometimes it can be very useful to work on a subset of that directory tree. This section describes how you can select a subset of such a directory tree.
Ant gives you two ways to create a subset, both of which can be used at the same time:
When both inclusion and exclusion are used, only files/directories that match the include patterns, and don't match the exclude patterns are used.
Patterns can be specified inside the buildfile via task attributes or nested elements and via external files. Each line of the external file is taken as pattern that is added to the list of include or exclude patterns.
As described earlier, patterns are used for the inclusion and exclusion. These patterns look very much like the patterns used in DOS and UNIX:
'*' matches zero or more characters, '?' matches one character.
Examples:
'*.java' matches '.java', 'x.java' and 'FooBar.java', but not 'FooBar.xml' (does not end with '.java').
'?.java' matches 'x.java', 'A.java', but not '.java' or 'xyz.java' (both don't have one character before '.java').
Combinations of '*'s and '?'s are allowed.
Matching is done per-directory. This means that first the first directory in the pattern is matched against the first directory in the path to match. Then the second directories are matched, and so on. E.g. when we have the pattern '/?abc/*/*.java' and the path '/xabc/foobar/test.java', then first '?abc' is matched with 'xabc', then '*' is matched with 'foobar' and finally '*.java' is matched with 'test.java'. They all match so the path matches the pattern.
Too make things a bit more flexible, we add one extra feature, which makes it possible to match multiple directory levels. This can be used to match a complete directory tree, or a file anywhere in the directory tree. To do this, '**' must be used as the name of a directory. When '**' is used as the name of a directory in the pattern, it matches zero or more directories. For instance: '/test/**' matches all files/directories under '/test/', such as '/test/x.java', or '/test/foo/bar/xyz.html', but not '/xyz.xml'.
There is one "shorthand", if a pattern ends with '/' or '\', then '**' is appended. E.g. "mypackage/test/" is interpreted as were it "mypackage/test/**".
Examples:
| **/CVS/* | Matches all files in CVS directories, that can be located
anywhere in the directory tree.
Matches: CVS/Repository But not: org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match) |
| org/apache/jakarta/** | Matches all files in the org/apache/jakarta directory tree.
Matches: org/apache/jakarta/tools/ant/docs/index.html But not: org/apache/xyz.java ('jakarta'/' part is missing) |
| org/apache/**/CVS/* | Matches all files in CVS directories, that are located
anywhere in the directory tree under org/apache.
Matches: org/apache/CVS/Entries But not: org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match) |
| **/test/** | Matches all files which have a directory 'test' in their path, including 'test' as a filename. |
When these patterns are used in inclusion and exclusion, you have a powerful way to select just the files you want.
<copy todir="${dist}" >
<fileset dir="${src}"
includes="**/images/*"
excludes="**/*.gif"
/>
</copy>
This copies all files in directories called "images", that are located in the directory tree "${src}" to the destination "${dist}", but excludes all "*.gif" files from the copy.
This example can also be expressed using nested elements as
<copy todir="${dist}" >
<fileset dir="${src}" />
<include name="**/images/*"/>
<exclude name="**/*.gif" />
</fileset>
</copy>
There are a set of definitions which are excluded by default from all directory based tasks. They are:
"**/*~",
"**/#*#",
"**/%*%",
"**/CVS",
"**/CVS/*",
"**/.cvsignore"
If you do not want these default excludes applied, you may disable them with the
defaultexcludes="no" attribute.
Patterns can be grouped to sets and later be referenced by their id
attribute. They are defined via a patternset element -
which can appear nested into a FileSet or a
directory based task that constitutes an implicit FileSet. In addition
patternsets can be defined at the same level as
target - i.e. as children of project
Patterns can be specified by nested <include> or
<exclude> elements or the following attributes.
| Attribute | Description |
| includes | comma separated list of patterns of files that must be included. All files are included when omitted. |
| includesfile | the name of a file. Each line of this file is taken to be an include pattern |
| excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. |
| excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern |
<patternset id="non.test.sources" > <include name="**/*.java" /> <exclude name="**/*Test*" /> </patternset>
Builds a set of patterns, that matches all .java files
that do not contain the text Test in their name. This set
can be referred to via
<patternset refid="non.test.sources"
/> by tasks that support this feature or by FileSets.
FileSets are groups of files. These files can be found in a
directory tree starting in a base directory and are matched by
patterns taken from a number of PatternSets. FileSets can appear inside task
that support this feature or at the same level as target
- i.e. as children of project.
PatternSets can be specified as nested
<patternset>
elements. In addition FileSet holds an implicit PatternSet and
supports the nested <include> and
<exclude> elements of PatternSet directly as well
as PatternSet's attributes.
| Attribute | Description | Required |
| dir | The root of the directory tree of this FileSet. | Yes |
| defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
| includes | comma separated list of patterns of files that must be included. All files are included when omitted. | No |
| includesfile | the name of a file. Each line of this file is taken to be an include pattern | No |
| excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. | No |
| excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern | No |
<fileset dir="${server.src}" >
<patternset id="non.test.sources" >
<include name="**/*.java" />
<exclude name="**/*Test*" />
</patternset>
</fileset>
Groups all files in directory ${server.src} that are Java
source files and don't have the text Test in their
name.
<fileset dir="${client.src}" >
<patternset refid="non.test.sources" />
</fileset>
Groups all files in directory ${client.src} using the
same patterns as the example before.
Runs Ant on a supplied buildfile. This can be used to build subprojects.
When the antfile attribute is omitted, the file "build.xml" in the supplied directory (dir attribute) is used.
If no target attribute is supplied, the default target of the new project is used.
The properties of the current project will be available in the new project. These properties will override the properties that are set in the new project. (See also the properties task). You can set properties in the new project from the old project by using nested property tags. This allows you to parameterize your subprojects.
| Attribute | Description | Required |
| antfile | the buildfile to use. Defaults to "build.xml". | No |
| dir | the directory to use as a basedir for the new Ant project. Defaults to the current directory. | No |
| target | the target of the new Ant project that should be executed. | No |
| output | Filename to write the ant output to. | No |
<ant antfile="subproject/subbuild.xml" dir="subproject" target="compile" />
<ant dir="subproject" />
<ant antfile="subproject/property_based_subbuild.xml">
<property name="param1" value="version 1.x" />
<property file="config/subproject/default.properties" />
</ant>
Call another target within the same build-file optionally specifying some properties (param's in this context)
| Attribute | Description | Required |
| target | The target to execute. | Yes |
Specifies the properties to set before running the specified target. See property for usage guidelines.
<target name="default">
<antcall target="doSomethingElse">
<param name="param1" value="value"/>
</antcall>
</target>
<target name="doSomethingElse">
<echo message="param1=${param1}"/>
</target>
Will run the target 'doSomethingElse' and echo 'param1=value'.
Generates a DTD for Ant build files which contains information about all tasks currently known to Ant.
Note that the DTD generated by this task is incomplete, you can
always add XML entities using <taskdef>. See here for
a way to get around this problem.
This task doesn't know about required attributes, all will be
listed as #IMPLIED.
| Attribute | Description | Required |
| output | file to write the DTD to. | Yes |
<antstructure output="project.dtd" />
Sets a property if a resource is available at runtime. This resource can be a file resource, a class in classpath or a JVM system resource.
If the resource is present, the property value is set to true by default, otherwise the property is not set. You can set the value to something specific by using the value attribute.
Normally, this task is used to set properties that are useful to avoid target execution depending on system parameters.
| Attribute | Description | Required |
| property | the name of the property to set. | Yes |
| value | the value to set the property to. Defaults to "true". | No |
| classname | the class to look for in classpath. | Yes |
| resource | the resource to look for in the JVM | |
| file | the file to look for. | |
| classpath | the classpath to
use when looking up classname. | No |
Available's classpath attribute is a PATH like structure and can also be set via a nested
classpath element.
<available classname="org.whatever.Myclass" property="Myclass.present" />
sets the property Myclass.present to the value "true"
if the org.whatever.Myclass is found in Ant's classpath.
Changes the permissions of a file or all files inside specified directories. Right now it has effect only under Unix. The permissions are also UNIX style, like the argument for the chmod command.
See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.
This task holds an implicit FileSet and
supports all of FileSet's attributes and nested elements
directly. More FileSets can be specified using nested
<fileset> elements.
| Attribute | Description | Required |
| file | the file or single directory of which the permissions must be changed. | exactly one of the two or nested <fileset> elements. |
| dir | the directory which holds the files whose permissions must be changed. | |
| perm | the new permissions. | Yes |
| includes | comma separated list of patterns of files that must be included. All files are included when omitted. | No |
| includesfile | the name of a file. Each line of this file is taken to be an include pattern | No |
| excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. | No |
| excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern | No |
| defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
| parallel | process all specified files using a single
chmod command. Defaults to true. |
No |
| type | One of file, dir or both. If set to file, only the permissions of plain files are going to be changed. If set to dir, only the directories are considered. | No, default is file |
<chmod file="${dist}/start.sh" perm="ugo+rx" />
makes the "start.sh" file readable and executable for anyone on a UNIX system.
<chmod dir="${dist}/bin" perm="ugo+rx" includes="**/*.sh" />
makes all ".sh" files below ${dist}/bin
readable and executable for anyone on a UNIX system.
<chmod perm="g+w" />
<fileset dir="shared/sources1" >
<exclude name="**/trial/**" />
</fileset>
<fileset refid="other.shared.sources" />
</chmod>
makes all files below shared/sources1 (except those
below any directory named trial) writable for members of the same
group on a UNIX system. In addition all files belonging to a FileSet
with id other.shared.sources get the same
permissions.
Copies a file or Fileset to a new file or directory. Files are only copied if the source file is newer than the destination file, or when the destination file does not exist. However, you can explicitly overwrite files with the overwrite attribute.
FileSets are used to select files to copy. To use a fileset, the todir attribute must be set.
| Attribute | Description | Required |
| file | The file to copy. | One of either file or at least one nested fileset element. |
| tofile | The file to copy to. | With the file attribute, either tofile or todir can be used. With nested filesets, only todir is allowed. |
| todir | The directory to copy to. | |
| overwrite | Overwrite existing files even if the destination files are newer. Defaults to "no". | No |
| filtering | Indicates whether token filtering should take place during the copy. Defaults to "no". | No |
| flatten | Ignore directory structure of source directory, copy all files into a single directory, specified by the todir attribute. Defaults to "no". | No |
| includeEmptyDirs | Copy empty directories included with the nested FileSet(s). Defaults to "yes". | No |
Copy a single file
<copy file="myfile.txt" tofile="mycopy.txt" />
Copy a file to a directory
<copy file="myfile.txt" todir="../some/dir/tree" />
Copy a directory to another directory
<copy todir="../new/dir">
<fileset dir="src_dir"/>
</copy>
Copy a set of files to a directory
<copy todir="../dest/dir" >
<fileset dir="src_dir" >
<exclude name="**/*.java" />
</fileset>
</copy>
<copy todir="../dest/dir" >
<fileset dir="src_dir" excludes="**/*.java" />
</copy>
This task has been deprecated. Use the Copy task instead.
Copies a directory tree from the source to the destination.
It is possible to refine the set of files that are being copied. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.
This task forms an implicit FileSet and
supports all attributes of <fileset>
(dir becomes src) as well as the nested
<include>, <exclude> and
<patternset> elements.
| Attribute | Description | Required |
| src | the directory to copy. | Yes |
| dest | the directory to copy to. | Yes |
| includes | comma separated list of patterns of files that must be included. All files are included when omitted. | No |
| includesfile | the name of a file. Each line of this file is taken to be an include pattern | No |
| excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. | No |
| excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern | No |
| defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
| filtering | indicates whether token filtering should take place during the copy | No |
| flatten | ignore directory structure of source directory, copy all files into a single directory - specified by the dest attribute (default is false). | No |
| forceoverwrite | overwrite existing files even if the destination files are newer (default is false). | No |
<copydir src="${src}/resources"
dest="${dist}"
/>
copies the directory ${src}/resources to ${dist}.
<copydir src="${src}/resources"
dest="${dist}"
includes="**/*.java"
excludes="**/Test.java"
/>
copies the directory ${src}/resources to ${dist}
recursively. All java files are copied, except for files with the name Test.java.
<copydir src="${src}/resources"
dest="${dist}"
includes="**/*.java"
excludes="mypackage/test/**" />
copies the directory ${src}/resources to ${dist}
recursively. All java files are copied, except for the files under the mypackage/test
directory.
This task has been deprecated. Use the Copy task instead.
Copies a file from the source to the destination. The file is only copied if the source file is newer than the destination file, or when the destination file does not exist.
| Attribute | Description | Required |
| src | the filename of the file to copy. | Yes |
| dest | the filename of the file where to copy to. | Yes |
| filtering | indicates whether token filtering should take place during the copy | No |
| forceoverwrite | overwrite existing files even if the destination files are newer (default is false). | No |
<copyfile src="test.java" dest="subdir/test.java" />
<copyfile src="${src}/index.html" dest="${dist}/help/index.html" />
Handles packages/modules retrieved from a CVS repository.
When doing automated builds, the get task should be preferred over the checkout command, because of speed.
| Attribute | Description | Required |
| command | the CVS command to execute. | No, default "checkout" |
| cvsRoot | the CVSROOT variable. | No |
| dest | the directory where the checked out files should be placed. | No, default is project's basedir. |
| package | the package/module to check out. | No |
| tag | the tag of the package/module to check out. | No |
| date | Use the most recent revision no later than the given date | No |
| quiet | suppress informational messages. | No, default "false" |
| noexec | report only, don't change any files. | No, default "false" |
| output | the file to direct standard output from the command. | No, default output to ANT Log as MSG_INFO. |
| error | the file to direct standard error from the command. | No, default error to ANT Log as MSG_WARN. |
<cvs cvsRoot=":pserver:anoncvs@jakarta.apache.org:/home/cvspublic"
package="jakarta-tools"
dest="${ws.dir}"
/>
checks out the package/module "jakarta-tools" from the CVS repository pointed to by the cvsRoot attribute, and stores the files in "${ws.dir}".
<cvs dest="${ws.dir}" command="update" />
updates the package/module that has previously been checked out into "${ws.dir}".
Deletes either a single file, all files in a specified directory and its sub-directories, or a set of files specified by one or more FileSets. When specifying a set of files, empty directories are not removed.
| Attribute | Description | Required |
| file | The file to delete. | at least one of the two |
| dir | The directory to delete files from. | |
| verbose | Show name of each deleted file ("true"/"false"). Default is "false" when omitted. | No |
| includes | Deprecated. Comma separated list of patterns of files that must be deleted. All files are in the current directory and any sub-directories are deleted when omitted. | No |
| includesfile | Deprecated. The name of a file. Each line of this file is taken to be an include pattern | No |
| excludes | Deprecated. Comma separated list of patterns of files that must be excluded from the deletion list. No files (except default excludes) are excluded when omitted. | No |
| excludesfile | Deprecated. The name of a file. Each line of this file is taken to be an exclude pattern | No |
| defaultexcludes | Deprecated. Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
<delete file="/lib/ant.jar" />
deletes the file /lib/ant.jar.
<delete dir="lib" />
deletes all files in the /lib directory.
<delete>
<fileset dir="." includes="**/*.bak" />
</delete>
deletes all files with the extension ".bak" from the current directory
and any sub-directories.
This task has been deprecated. Use the Delete task instead.
Deletes a directory with all its files and subdirectories.
| Attribute | Description | Required |
| dir | the directory to delete. | Yes |
<deltree dir="dist" />
deletes the directory dist, including its files and
subdirectories.
<deltree dir="${dist}" />
deletes the directory ${dist}, including its files and
subdirectories.
Echoes a message to System.out or a file.
| Attribute | Description | Required |
| message | the message to echo. | Yes, unless data is included in a character section within this element. |
| file | the file to write the message to. | No |
| append | Append to an existing file? | No - default is false. |
<echo message="Hello world" />
<echo> This is a longer message stretching over two lines. </echo>
Executes a system command. When the os attribute is specified, then the command is only executed when Ant is run on one of the specified operating systems.
| Attribute | Description | Required |
| command | the command to execute with all command line
arguments. deprecated, use executable and nested
<arg> elements instead. |
Exactly one of the two. |
| executable | the command to execute without any command line arguments. | |
| dir | the directory in which the command should be executed. | No |
| os | list of Operating Systems on which the command may be executed. | No |
| output | the file to which the output of the command should be redirected. | No |
| timeout | Stop the command if it doesn't finish within the specified time (given in milliseconds). | No |
| failonerror | Stop the buildprocess if the command exits with a returncode other than 0. | No |
<exec dir="${src}" executable="dir" os="windows" output="dir.txt" />
Command line arguments should be specified as nested
<arg> elements. See Command line arguments.
It is possible to specify environment variables to pass to the
system command via nested <env> elements.
Please note that the environment of the current Ant process is
not passed to the system command if you specify variables using
<env>.
| Attribute | Description | Required |
| key | The name of the environment variable. | Yes |
| value | The literal value for the environment variable. | Exactly one of these. |
| path | The value for a PATH like environment variable. You can use ; or : as path separators and Ant will convert it to the platform's local conventions. | |
| file | The value for the environment variable. Will be replaced by the absolute filename of the file by Ant. |
<exec executable="emacs" > <env key="DISPLAY" value=":1.0" /> </exec>
starts emacs on display 1 of the X Window System.
<exec ... >
<env key="PATH" path="${java.library.path}:${basedir}/bin" />
</exec>
adds ${basedir}/bin to the PATH of the
system command.
Note: Although it may work for you to specify arguments using a simple arg-element and seperate them by spaces it may fail if you switch to a newer version of the JDK. JDK < 1.2 will pass these as separate arguments to the program you are calling, JDK >= 1.2 will pass them as a single argument and cause most calls to fail.
Note2: If you are using Ant on Windows and a new DOS-Window pops up for every command which is excuted this may be a problem of the JDK you are using. This problem may occur with all JDK's < 1.2.
Executes a system command. When the os attribute is specified, then the command is only executed when Ant is run on one of the specified operating systems.
The files and/or directories of a number of FileSets are passed as arguments to the system
command. At least one nested <fileset> is required.
| Attribute | Description | Required |
| executable | the command to execute without any command line arguments. | Yes |
| dir | the directory in which the command should be executed. | No |
| os | list of Operating Systems on which the command may be executed. | No |
| output | the file to which the output of the command should be redirected. | No |
| timeout | Stop the command if it doesn't finish within the specified time (given in milliseconds). | No |
| failonerror | Stop the buildprocess if the command exits with a returncode other than 0. | No |
| parallel | Run the command only once, appending all files as arguments. Defaults to true. If false, command will be executed once for every file. | No |
| type | One of file, dir or both. If set to file, only the names of plain files will be sent to the command. If set to dir, only the names of directories are considered. | No, default is file |
You can use any number of nested <fileset>
elements to define the files for this task and refer to
<fileset>s defined elsewhere.
Command line arguments should be specified as nested
<arg> elements. See Command line arguments.
It is possible to specify environment variables to pass to the
system command via nested <env> elements. See the
description in the section about exec
Please note that the environment of the current Ant process is
not passed to the system command if you specify variables using
<env>.
<execon executable="ls" >
<arg value="-l" />
<fileset dir="/tmp">
<patternset>
<exclude name="**/*.txt" />
</patternset>
</fileset>
<fileset refid="other.files" />
</execon>
invokes ls -l, adding the absolute filenames of all
files below /tmp not ending in .txt and all
files of the FileSet with id other.files to
the command line.
Exits the current build (just throwing a BuildException), optionally printing additional information.
| Attribute | Description | Required |
| message | A message giving further information on why the build exited | No |
<fail/>
will exit the current build with no further information given.
BUILD FAILED build.xml:4: No message
<fail message="Something wrong here."/>
will exit the current build and print something like the following to whereever your output goes:
BUILD FAILED build.xml:4: Something wrong here.
Sets a token filter for this project or read multiple token filter from an input file and sets these as filters. Token filters are used by all tasks that perform file copying operations through the Project commodity methods.
Note 1: the token string must not contain the separators chars (@).
Note 2: Either token and value attributes must be provided, or only the
filterfile attribute.
| Attribute | Description | Required |
| token | the token string without @ | Yes* |
| value | the string that should be put to replace the token when the file is copied | Yes* |
| filtersfile | The file from which the filters must be read. This file must be a formatted as a property file. | Yes* |
* see notes 1 and 2 above parameters table.
<filter token="year" value="2000" />
<copy todir="${dest.dir}">
<fileset dir="${src.dir}" />
</copy>
will copy recursively all the files from the src.dir directory into the dest.dir directory replacing all the occurencies of the string @year@ with 2000.
<filter filterfile="deploy_env.properties" />will read all property entries from the deploy_env.properties file and set these as filters.
Adjusts a text file to local.
It is possible to refine the set of files that are being adjusted. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.
This task forms an implicit FileSet and
supports all attributes of <fileset>
(dir becomes srcdir) as well as the nested
<include>, <exclude> and
<patternset> elements.
| Attribute | Description | Required |
| srcDir | Where to find the files to be fixed up. | Yes |
| destDir | Where to place the corrected files. Defaults to srcDir (replacing the original file) | No |
| includes | comma separated list of patterns of files that must be included. All files are included when omitted. | No |
| includesfile | the name of a file. Each line of this file is taken to be an include pattern | No |
| excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. | No |
| excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern | No |
| defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
| cr | Specifies how carriage return (CR) characters are to
be handled. Valid values for this property are:
Note: Unless this property is specified as "asis", extra CR characters which do not precede a LF will be removed. |
No |
| tab | Specifies how tab characters are to be handled. Valid
values for this property are:
Note: Unless this property is specified as "asis", extra spaces and tabs after the last non-whitespace character on the line will be removed. |
No |
| tablength | The number of characters a TAB stop corresponds to. Must be a positive power of 2, default for this parameter is 8. | No |
| eof | Specifies how DOS end of file (control-Z) characters are
to be handled. Valid values for this property are:
|
No |
<fixcrlf srcdir="${src}"
cr="remove" eof="remove"
includes="**/*.sh"
/>
Removes carriage return and eof characters from the shell scripts. Tabs and spaces are left as is.
<fixcrlf srcdir="${src}"
cr="add"
includes="**/*.bat"
/>
Ensures that there are carriage return characters prior to evey line feed. Tabs and spaces are left as is. EOF characters are left alone if run on DOS systems, and are removed if run on Unix systems.
<fixcrlf srcdir="${src}"
tabs="add"
includes="**/Makefile"
/>
Adds or removes CR characters to match local OS conventions, and converts spaces to tabs when appropriate. EOF characters are left alone if run on DOS systems, and are removed if run on Unix systems. Many versions of make require tabs prior to commands.
<fixcrlf srcdir="${src}"
tabs="remove"
includes="**/README*"
/>
Adds or removes CR characters to match local OS conventions, and converts all tabs to spaces. EOF characters are left alone if run on DOS systems, and are removed if run on Unix systems. You never know what editor a user will use to browse README's.
Generates a key in keystore.
| Attribute | Description | Required |
| alias | the alias to add under | Yes. |
| storepass | password for keystore integrity. | Yes. |
| keystore | keystore location | No |
| storetype | keystore type | No |
| keypass | password for private key (if different) | No |
| sigalg | the algorithm to use in signing | No |
| keyalg | the method to use when generating name-value pair | No |
| verbose | (true | false) verbose output when signing | No |
| dname | The distinguished name for entity | Yes if dname element unspecified |
| validity | (integer) indicates how many days certificate is valid | No |
| keysize | (integer) indicates the size of key generated | No |
Alternatively you can specify the distinguished name by creating a sub-element named dname and populating it with param elements that have a name and a value. When using the subelement it is automatically encoded properly and , are replace
The following two examples are identical:
<genkey alias="apache-group" storepass="secret" dname="CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US" />
<genkey alias="apache-group" storepass="secret" > <dname> <param name="CN" value="Ant Group"/> <param name="OU" value="Jakarta Division"/> <param name="O" value="Apache.Org"/> <param name="C" value="US"/> </dname> </genkey>
Gets a file from a URL. When the verbose option is "on", this task displays a '.' for every 100 Kb retrieved.
This task should be preferred above the CVS task when doing automated builds. CVS is significantly slower than loading a compressed archive with http/ftp.
The usetimestamps option enables you to control downloads so that the remote file is only fetched if newer than the local copy. If there is no local copy, the download always takes place. When a file is downloaded, the timestamp of the downloaded file is set to the remote timestamp, if the JVM is Java1.2 or later. NB: This timestamp facility only works on downloads using the HTTP protocol.| Attribute | Description | Required |
| src | the URL from which to retrieve a file. | Yes |
| dest | the file where to store the retrieved file. | Yes |
| verbose | show verbose progress information ("on"/"off"). | No |
| ignoreerrors | Log errors but don't treat as fatal. | No |
| usetimestamps | conditionally download a file based on the timestamp of the local copy. HTTP only | No |
<get src="http://jakarta.apache.org/" dest="help/index.html" />
Gets the index page of http://jakarta.apache.org/, and stores it in the file help/index.html.
<get src="http://jakarta.apache.org/builds/tomcat/nightly/ant.zip" dest="optional.jar" verbose="true" usetimestamps="true"/>
Gets the nightly ant build from the tomcat distribution, if the local copy is missing or out of date. Uses the verbose option for progress information.
Expands a GZip file.
If dest is a directory the name of the destination file is the same as src (with the ".gz" extension removed if present). If dest is omitted, the parent dir of src is taken. The file is only expanded if the source file is newer than the destination file, or when the destination file does not exist.
| Attribute | Description | Required |
| src | the file to expand. | Yes |
| dest | the destination file or directory. | No |
<gunzip src="test.tar.gz"/>
expands test.tar.gz to test.tar
<gunzip src="test.tar.gz" dest="test2.tar"/>
expands test.tar.gz to test2.tar
<gunzip src="test.tar.gz" dest="subdir"/>
expands test.tar.gz to subdir/test.tar (assuming subdir is a directory).
GZips a file.
| Attribute | Description | Required |
| src | the file to gzip. | Yes |
| zipfile | the destination file. | Yes |
<gzip src="test.tar" zipfile="test.tar.gz" />
Jars a set of files.
The basedir attribute is the reference directory from where to jar.
Note that file permissions will not be stored in the resulting jarfile.
It is possible to refine the set of files that are being jarred. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.
This task forms an implicit FileSet and
supports all attributes of <fileset>
(dir becomes basedir) as well as the nested
<include>, <exclude> and
<patternset> elements.
You can also use nested file sets for more flexibility, and specify multiple ones to merge together different trees of files into one JAR. See the Zip task for more details and examples.
If the manifest is omitted, a simple one will be supplied by Ant. You should not include META-INF/MANIFEST.MF in your set of files.
The whenempty parameter controls what happens when no files match.
If create (the default), the JAR is created anyway with only a manifest.
If skip, the JAR is not created and a warning is issued.
If fail, the JAR is not created and the build is halted with an error.
| Attribute | Description | Required |
| jarfile | the jar-file to create. | Yes |
| basedir | the directory from which to jar the files. | No |
| compress | Not only store data but also compress them, defaults to true | No |
| includes | comma separated list of patterns of files that must be included. All files are included when omitted. | No |
| includesfile | the name of a file. Each line of this file is taken to be an include pattern | No |
| excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. | No |
| excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern | No |
| defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
| manifest | the manifest file to use. | No |
| whenempty | Behavior to use if no files match. | No |
<jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" />
jars all files in the ${build}/classes directory in a file
called app.jar in the ${dist}/lib directory.
<jar jarfile="${dist}/lib/app.jar"
basedir="${build}/classes"
excludes="**/Test.class"
/>
jars all files in the ${build}/classes directory in a file
called app.jar in the ${dist}/lib directory. Files
with the name Test.class are excluded.
<jar jarfile="${dist}/lib/app.jar"
basedir="${build}/classes"
includes="mypackage/test/**"
excludes="**/Test.class"
/>
jars all files in the ${build}/classes directory in a file
called app.jar in the ${dist}/lib directory. Only
files under the directory mypackage/test are used, and files with
the name Test.class are excluded.
<jar jarfile="${dist}/lib/app.jar">
<fileset dir="${build}/classes"
excludes="**/Test.class"
/>
<fileset dir="${src}/resources"/>
</jar>
jars all files in the ${build}/classes directory and also
in the ${src}/resources directory together in a file
called app.jar in the ${dist}/lib directory.
Files with the name Test.class are excluded.
If there are files such as ${build}/classes/mypackage/MyClass.class
and ${src}/resources/mypackage/image.gif, they will appear
in the same directory in the JAR (and thus be considered in the same package
by Java).
Executes a Java class within the running (Ant) VM or forks another VM if specified.
Be careful that the executed class doesn't call System.exit(), because it will terminate the VM and thus Ant. In case this happens, it's highly suggested that you set the fork attribute so that System.exit() stops the other VM and not the one that is currently running Ant.
| Attribute | Description | Required |
| classname | the Java class to execute. | Yes |
| args | the arguments for the class that is
executed. deprecated, use nested <arg>
elements instead. |
No |
| classpath | the classpath to use. | No |
| classpathref | the classpath to use, given as reference to a PATH defined elsewhere. | No |
| fork | if enabled triggers the class execution in another VM (disabled by default) | No |
| jvm | the command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec(). Ignored if fork is disabled. | No |
| jvmargs | the arguments to pass to the forked VM (ignored
if fork is disabled). deprecated, use nested
<jvmarg> elements instead. |
No |
| maxmemory | Max amount of memory to allocate to the forked VM (ignored if fork is disabled) | No |
| failonerror | Stop the buildprocess if the command exits with a returncode other than 0. Only available if fork is true. | No |
| dir | The directory to invoke the VM in. (ignored if fork is disabled) | No |
Use nested <arg> and <jvmarg>
elements to specify arguments for the or the forked VM. See Command line arguments.
Use nested <sysproperty>
elements to specify system properties required by the class.
These properties will be made available to the VM during the execution
of the class (either ANT's VM or the forked VM). The attributes
for this element are the same as for environment
variables.
Java's classpath attribute is a PATH like structure and can also be set via a nested
classpath element.
<java classname="test.Main" >
<arg value="-h" />
<classpath>
<pathelement location="\test.jar" />
<pathelement path="${java.class.path}" />
</classpath>
</java>
<java classname="test.Main" />
<java classname="test.Main"
fork="yes" >
<sysproperty key="DEBUG" value="true" />
<arg value="-h" />
<jvmarg value="-Xrunhprof:cpu=samples,file=log.txt,depth=3" />
</java>
Compiles a source tree within the running (Ant) VM.
The source and destination directory will be recursively scanned for Java source files to compile. Only Java files that have no corresponding class file or where the class file is older than the java file will be compiled.
The directory structure of the source tree should follow the package hierarchy.
It is possible to refine the set of files that are being compiled/copied. This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes attributes. With the includes or includesfile attribute you specify the files you want to have included by using patterns. The exclude or excludesfile attribute is used to specify the files you want to have excluded. This is also done with patterns. And finally with the defaultexcludes attribute, you can specify whether you want to use default exclusions or not. See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.
It is possible to use different compilers. This can be selected with the "build.compiler" property. There are three choices:
For JDK 1.1/1.2 is classic the default. For JDK 1.3 is modern the default.
| Attribute | Description | Required |
| srcdir | location of the java files. | Yes, unless nested <src> elements are present. |
| destdir | location where to store the class files. | No |
| includes | comma separated list of patterns of files that must be included. All files are included when omitted. | No |
| includesfile | the name of a file. Each line of this file is taken to be an include pattern | No |
| excludes | comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. | No |
| excludesfile | the name of a file. Each line of this file is taken to be an exclude pattern | No |
| defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
| classpath | the classpath to use. | No |
| bootclasspath | location of bootstrap class files. | No |
| classpathref | the classpath to use, given as reference to a PATH defined elsewhere. | No |
| bootclasspathref | location of bootstrap class files, given as by reference to a PATH defined elsewhere. | No |
| extdirs | location of installed extensions. | No |
| encoding | encoding of source files. | No |
| debug | indicates whether there should be compiled with debug information ("off"). | No |
| optimize | indicates whether there should be compiled with optimization ("off"). | No |
| deprecation | indicates whether there should be compiled with deprecation information ("off"). | No |
| target | Generate class files for specific VM version, e.g. "1.1" or "1.2". | No |
| verbose | asks the compiler for verbose output. | No |
| depend | enables dependency tracking for compilers that support this (jikes and classic) | No |
This task forms an implicit FileSet and
supports all attributes of <fileset>
(dir becomes srcdir) as well as the nested
<include>, <exclude> and
<patternset> elements.
Javac's srcdir, classpath,
bootclasspath and extdirs attributes are PATH like structure and can also be set via nested
src, classpath, bootclasspath and
extdirs elements respectively.
<javac srcdir="${src}"
destdir="${build}"
classpath="xyz.jar"
debug="on"
/>
compiles all .java files under the directory ${src}, and stores
the .class files in the directory ${build}.
The classpath used contains xyz.jar, and debug information is on.
<javac srcdir="${src}"
destdir="${build}"
includes="mypackage/p1/**,mypackage/p2/**"
excludes="mypackage/p1/testpackage/**"
classpath="xyz.jar"
debug="on"
/>
compiles .java files under the directory ${src}, and stores the
.class files in the directory ${build}.
The classpath used contains xyz.jar, and debug information is on.
Only files under mypackage/p1 and mypackage/p2 are
used. Files in the mypackage/p1/testpackage directory are excluded
form compilation and copy.
<javac srcdir="${src}:${src2}"
destdir="${build}"
includes="mypackage/p1/**,mypackage/p2/**"
excludes="mypackage/p1/testpackage/**"
classpath="xyz.jar"
debug="on"
/>
is the same as the previous example with the addition of a second source path, defined by
the propery src2. This can also be represented using nested elements as follows
<javac destdir="${build}"
classpath="xyz.jar"
debug="on">
<src path="${src}" />
<src path="${src2}" />
<include name="mypackage/p1/**,mypackage/p2/**" />
<exclude name="mypackage/p1/testpackage/**" />
</javac>
Note: If you are using Ant on Windows and a new DOS-Window pops up for every use of an external compiler this may be a problem of the JDK you are using. This problem may occur with all JDK's < 1.2.
Generates code documentation using the javadoc tool.
The source directory will be recursively scanned for Java source files to process but only those matching the inclusion rules will be passed to the javadoc tool. This allows wildcards to be used to choose between package names, reducing verbosity and management costs over time. This task, however, has no notion of "changed" files, unlike the javac task. This means all packages will be processed each time this task is run. In general, however, this task is used much less frequently.
This task works seamlessly between different javadoc versions (1.1 and 1.2), with the obvious restriction that the 1.2 attributes will be ignored if run in a 1.1 VM.
NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the same VM as ant without breaking functionality. For this reason, this task always forks the VM. This overhead is not significant since javadoc is normally a heavy application and will be called infrequently.
NOTE: the packagelist attribute allows you to specify the list of packages to document outside of the Ant file. It's a much better practice to include everything inside the build.xml file. This option was added in order to make it easier to migrate from regular makefiles, where you would use this option of javadoc. The packages listed in packagelist are not checked, so the task performs even if some packages are missing or broken. Use this option if you wish to convert from an existing makefile. Once things are running you should then switch to the regular notation.
DEPRECATION: the javadoc2 task simply points to the javadoc task and it's there for back compatibility reasons. Since this task will be removed in future versions, you are strongly encouraged to use javadoc instead.
| Attribute | Description | Availability | Required |
| sourcepath | Specify where to find source files | all | At least one of the two or nested
<sourcepath> |
| sourcepathref | Specify where to find source files by reference to a PATH defined elsewhere. | all | |
| destdir | Destination directory for output files | all | Yes |
| maxmemory | Max amount of memory to allocate to the javadoc VM | all | No |
| sourcefiles | Space separated list of source files | all | at least one of the two |
| packagenames | Comma separated list of package files (with terminating wildcard) | all | |
| packageList | The name of a file containing the packages to process | all | No |
| classpath | Specify where to find user class files | all | No |
| Bootclasspath | Override location of class files loaded by the bootstrap class loader | 1.2 | No |
| classpathref | Specify where to find user class files by reference to a PATH defined elsewhere. | all | No |
| bootclasspathref | Override location of class files loaded by the bootstrap class loader by reference to a PATH defined elsewhere. | 1.2 | No |
| Extdirs | Override location of installed extensions | 1.2 | No |
| Overview | Read overview documentation from HTML file | 1.2 | No |
| Public | Show only public classes and members | all | No |
| Protected | Show protected/public classes and members (default) | all | No |
| Package | Show package/protected/public classes and members | all | No |
| Private | Show all classes and members | all | No |
| Old | Generate output using JDK 1.1 emulating doclet | 1.2 | No |
| Verbose | Output messages about what Javadoc is doing | 1.2 | No |
| Locale | Locale to be used, e.g. en_US or en_US_WIN | 1.2 | No |
| Encoding | Source file encoding name | all | No |
| Version | Include @version paragraphs | all | No |
| Use | Create class and package usage pages | 1.2 | No |
| Author | Include @author paragraphs | all | No |
| Splitindex | Split index into one file per letter | 1.2 | No |
| Windowtitle | Browser window title for the documentation (text) | 1.2 | No |
| Doctitle | Include title for the package index(first) page (html-code) | 1.2 | No |
| Header | Include header text for each page (html-code) | 1.2 | No |
| Footer | Include footer text for each page (html-code) | 1.2 | No |
| bottom | Include bottom text for each page (html-code) | 1.2 | No |
| link | Create links to javadoc output at the given URL | 1.2 | No |
| linkoffline | Link to docs at <url> using package list at <url2> | 1.2 | No |
| group | Group specified packages together in overview page | 1.2 | No |
| nodeprecated | Do not include @deprecated information | all | No |
| nodeprecatedlist | Do not generate deprecated list | 1.2 | No |
| notree | Do not generate class hierarchy | all | No |
| noindex | Do not generate index | all | No |
| nohelp | Do not generate help link | 1.2 | No |
| nonavbar | Do not generate navigation bar | 1.2 | No |
| serialwarn | FUTURE: Generate warning about @serial tag | 1.2 | No |
| helpfile | FUTURE: Specifies the HTML help file to use | 1.2 | No |
| stylesheetfile | Specifies the CSS stylesheet to use | 1.2 | No |
| charset | FUTURE: Charset for cross-platform viewing of generated documentation | 1.2 | No |
| docencoding | Output file encoding name | 1.1 | No |
| doclet | Specifies the class file that starts the doclet used in generating the documentation. | 1.2 | No |
| docletpath | Specifies the path to the doclet class file that is specified with the -doclet option. | 1.2 | No |
| docletpathref | Specifies the path to the doclet class file that is specified with the -doclet option by reference to a PATH defined elsewhere. | 1.2 | No |
| additionalparam | Lets you add additional parameters to the javadoc command line. Useful for doclets | 1.2 | No |
| failonerror | Stop the buildprocess if the command exits with a returncode other than 0. | all | No |
Create link to javadoc output at the given URL. This performs the same role as the link and linkoffline attributes. You can use either syntax (or both at once), but with the nested elements you can easily specify multiple occurrences of the arguments.
| Attribute | Description | Required |
| href | The URL for the external documentation you wish to link to | Yes |
| offline | True if this link is not available online at the time of generating the documentation | No |
| packagelistLoc | The location to the directory containing the package-list file for the external documentation | Only if the offline attribute is true |
Separates packages on the overview page into wha