by
Version: @VERSION@
$Id$
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 those tools have limitations that Ant's 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, 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 have yet another format to use and remember.
Ant is different. Instead of a model where it is extended with shell-based commands, Ant 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 that implements a particular Task interface.
Granted, this removes some of the expressive power that is inherent in being
able to construct a shell command such as
`find . -name foo -exec rm {}`
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.
Both the binary and source distributions of Ant include the reference implementation of JAXP 1.0.
Please see http://java.sun.com/xml/ for more information.
If you wish to use a different JAXP-compliant parser, you should remove
jaxp.jar
and parser.jar
from Ant's lib/core
directory.
You can then either put the jars from your preferred parser into Ant's
lib/core
directory or put the jars on the system classpath.
For the current version of Ant, you will also need a JDK installed on your system, version 1.1 or later. A future version of Ant will require JDK 1.2 or later.
The binary distribution of Ant consists of four directories:
bin
,
docs
,
lib
and
src
. Only the bin
and lib
directories are required for running Ant. To run Ant, the
following must be done:
bin
directory to your path.ANT_HOME
environment variable.
This should be set to the directory
that contains the bin
and lib
directories.JAVA_HOME
environment variable.
(See the Advanced section below.)
This should be set to the directory where the JDK is installed.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 containant.jar
and any jars/classes needed for your chosen JAXP-compliant XML parser.When you need JDK functionality (such as for the javac task or the 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 thebin
directory, will add the required JDK classes automatically, if theJAVA_HOME
environment variable is set.When you are executing platform-specific applications (such as the exec task or the cvs task), the property
ant.home
must be set to the directory containing theantRun
shell script necessary to run exec's on Unix.
To build Ant, you should install the Ant source distribution. While the binary distribution includes the Ant source code, it is intended for reference purposes only. The bootstrap and build scripts used to build Ant itself are not included in the binary distribution.
Once you have installed the source distribution, go to the
jakarta-ant
directory.
Set the JAVA_HOME
environment variable
to the directory where the JDK is installed.
See Installing Ant
for examples on how to do this for your operating system.
Make sure you have downloaded any auxilliary jars required to
build tasks you are interested in. These should either be available
on the classpath or added to Ant's lib
directory. The list of auxilliary tasks and requirements is in
lib/README
.
Run bootstrap.bat
(Windows) or bootstrap.sh
(UNIX)
to build a bootstrap version of Ant.
When finished, use:
build -Ddist.dir=<directory_to_contain_Ant_distribution> dist
(Windows)
build.sh -Ddist.dir=<directory_to_contain_Ant_distribution> dist
(Unix)
to create a binary distribution of Ant. This distribution can be found in the directory you specified.
If you wish to install the build into the currentANT_HOME
directory, you can use:
You can avoid the lengthy Javadoc step, if desired, with:
build install
(Windows)
build.sh install
(Unix)
This will only install the
build mininstall
(Windows)
build.sh mininstall
(Unix)
bin
and lib
directories.
Both the install
and
mininstall
targets will overwrite
the current Ant version in ANT_HOME
.
Running Ant is simple, when you installed it as described in the previous
section. Just type ant
.
When nothing is specified, Ant looks for a build.xml
file in the current directory. If found, it uses that file as the
buildfile. If you use the -find
-buildfile file
,
where file is the buildfile you want to use.
You can also set properties that override properties specified in the
buildfile (see the property task).
This can be done with
the -Dproperty=value
-DMYVAR=%MYVAR%
-DMYVAR=$MYVAR
${MYVAR}
.
Two more options are: -quiet
-verbose
It is also possible to specify one or more targets that should be executed.
When omitted, the target that is specified in the
default
attribute of the <project>
tag is
used.
The -projecthelp
Command-line option summary:
ant [options] [target [target2 [target3] ...]] Options: -help print this message -projecthelp print project help information -version print the version information and exit -quiet be extra quiet -verbose be extra verbose -debug print debugging information -emacs produce logging information without adornments -logfile file use given file for log output -logger classname the class that is to perform logging -listener classname add an instance of class as a project listener -buildfile file use specified buildfile -find file search for buildfile towards the root of the filesystem and use the first one found -Dproperty=value set property to value
ant
runs Ant using the build.xml
file in the current directory, on
the default target.
ant -buildfile test.xml
runs Ant using the test.xml
file in the current directory, on
the default target.
ant -buildfile test.xml dist
runs Ant using the test.xml
file in the current directory, on a
target called dist
.
ant -buildfile test.xml -Dbuild=build/classes dist
runs Ant using the test.xml
file in the current directory, on a
target called dist
, setting the build
property to the
value build/classes
.
If you have installed Ant in the do-it-yourself way, Ant can be started with:
java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]
These instructions actually do exactly the same as the ant
command. The options and target are the same as when running Ant with the ant
command. This example assumes you have set your classpath to include:
ant.jar
Ant's buildfiles are written in XML. Each buildfile contains one project.
Each task 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. (For additional information, see the
Tasks section below.)
A project has three attributes:
Attribute | Description | Required |
name | the name of the project. | No |
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 beforehand. When this is done, it must be omitted in the project tag. If neither the attribute nor the property have been set, the parent directory of the buildfile will be used. | No |
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(s) 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 example, 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 these dependencies.
It should be noted, however, that Ant's depends
attribute
only specifies the order in which targets should be executed it
does not affect whether the target that specifies the dependency(s) gets
executed if the dependent target(s) did not (need to) run.
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 than one target depends on it (see the previous example).
A target also has 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 property defines, etc.). To make a 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.
The optional description
attribute can be used to provide a one-line description of this target, which is printed by the
-projecthelp
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".
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 target's 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, attributeN is the attribute name, and valueN is the value for this attribute.
There is a set of built-in tasks, along with a number of optional tasks, but it is also very easy to write your own.
All tasks share a task name attribute. The value of this attribute will be used in the logging messages generated by Ant.
Tasks can be assigned anid
attribute:
where taskname is the name of the task, and taskID is a unique name for this task. You can refer to the corresponding task object in scripts or other tasks via this name. For example, in scripts you could do:<taskname id="taskID" ... />
to set the<script ... > task1.setFoo("bar"); </script>
foo
attribute of this particular task instance.
In another task (written in Java), you can access the instance via
project.getReference("task1")
.
Note1: If "task1" has not been run yet, then it has not been configured (ie., no attributes have been set), and if it is going to be configured later, anything you've done to the instance may be overwritten.
Note2: Future versions of Ant will most likely not be backward-compatible with this behaviour, since there will likely be no task instances at all, only proxies.
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 may be used in the value of
task attributes. This is done by placing the property name between
"${
" and "}
" in the
attribute value. For example,
if there is a "builddir" property 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 has some built-in properties:
basedir the absolute path of the project's basedir (as set with the basedir attribute of <project>). ant.file the absolute path of the buildfile. ant.project.name the name of the project that is currently executing; it is set in the name attribute of <project>. ant.java.version the JVM version Ant detected; currently it can hold the values "1.1", "1.2" and "1.3".
<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="init"> <!-- Create the time stamp --> <tstamp/> <!-- Create the build directory structure used by compile --> <mkdir dir="${build}"/> </target> <target name="compile" depends="init"> <!-- Compile the java code from ${src} into ${build} --> <javac srcdir="${src}" destdir="${build}"/> </target> <target name="dist" depends="compile"> <!-- Create the distribution 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 potentially 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 as with documentation systems.
Note: If a token with the format @
token@
is found in a file, but no
filter is associated with that token, no changes take place;
therefore, no escaping
method is available but as long as you choose appropriate names for your
tokens, this should not cause problems.
You can specify PATH
- and CLASSPATH
-type
references using both
":
" and ";
" as separator
characters. Ant will
convert the separator 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 colon-
or semicolon-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 <classpath>
tag
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 a 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 that 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 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>The shortcuts previously mentioned for
<classpath>
are also valid for <path>
.For example:
<path id="base.path"> <pathelement path="${classpath}"/> </path>can be written as:
<path id="base.path" path="${classpath}"/>
Several tasks take arguments that will be passed to another
process on the command line. To make it easier to specify arguments
that contain space characters, nested arg
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. | |
path | A string that will 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"/>
represents two separate command-line arguments.
<arg path="/dir;/dir2:\dir3"/>
is a single command-line argument with the 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 example, 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 a 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 directory is matched, and so on. For example, when we have the pattern /?abc/*/*.java
and the path /xabc/foobar/test.java
,
the 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.
To 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 example:
/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.
For example, mypackage/test/
is interpreted as if it were
mypackage/test/**
.
Example patterns:
**/CVS/* |
Matches all files in CVS directories that can be located
anywhere in the directory tree.Matches: CVS/Repository org/apache/CVS/Entries org/apache/jakarta/tools/ant/CVS/EntriesBut not:
org/apache/CVS/foo/bar/Entries ( |
org/apache/jakarta/** |
Matches all files in the org/apache/jakarta directory tree.Matches: org/apache/jakarta/tools/ant/docs/index.html org/apache/jakarta/test.xmlBut 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 org/apache/jakarta/tools/ant/CVS/EntriesBut not: org/apache/CVS/foo/bar/Entries( foo/bar/ part does not match) |
**/test/** |
Matches all files that have a test
element 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 defined by ${src}
to the
destination directory defined by ${dist}
,
but excludes all *.gif
files from the copy.
This example can also be expressed using nested elements:
<copy todir="${dist}"> <fileset dir="${src}"/> <include name="**/images/*"/> <exclude name="**/*.gif"/> </fileset> </copy>
There are a set of definitions that are excluded by default from all directory-based tasks. They are:
**/*~ **/#*# **/%*% **/CVS **/CVS/** **/.cvsignoreIf 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,
patternset
s 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.
Note that while the includes
and
excludes
attributes accept
multiple elements separated by commas or spaces, the nested
<include> and <exclude> elements expect their name
attribute to hold a single pattern.
The nested <include> and <exclude> elements allow you to use if and unless arguments to specify that the element should only be used if a property is set, or that it should be used only if a property is not set.
For example
<patternset id="sources" > <include name="std/**/*.java"/> <include name="prof/**/*.java" if="professional"/> <exclude name="**/*Test*"/> </patternset>
will only include the files in the sub-directory prof if the property professional is set to some value.
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 tasks
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 above.
Some tasks take source files and create target files. Depending on
the task, it may be quite obvious which name a target file will have
(using javac, you know there will be
.class
files for your .java
files) in
other cases you may want to specify the target files, either to help
Ant or to get an extra bit of functionality.
While source files are usually specified as filesets, you don't specify target files directly
instead, you tell Ant how to find the target file(s) for one source file. An
instance of org.apache.tools.ant.util.FileNameMapper
is
responsible for this. It constructs target file names based on rules
that can be parameterized with from
and to
attributes the exact meaning of which is implementation-dependent.
These instances are defined in <mapper>
elements
with the following attributes:
Attribute | Description | Required |
type | specifies one of the built-in implementations. | Exactly one of both |
classname | specifies the implementation by class name. | |
classpath | the classpath to use when looking up
classname . |
No |
classpathref | the classpath to use, given as reference to a path defined elsewhere. | No |
from | the from attribute for the given
implementation. |
Depends on implementation. |
to | the to attribute for the given
implementation. |
Depends on implementation. |
The classpath can be specified via a nested
<classpath>
, as well that is,
a path-like structure.
The built-in mapper types are:
The target file name is identical to the source file name. Both
to
and from
will be ignored.
<mapper type="identity"/>
Source file name | Target file name |
A.java |
A.java |
foo/bar/B.java |
foo/bar/B.java |
C.properties |
C.properties |
Classes/dir/dir2/A.properties |
Classes/dir/dir2/A.properties |
The target file name is identical to the source file name, with all
leading directory information stripped off. Both to
and
from
will be ignored.
<mapper type="flatten"/>
Source file name | Target file name |
A.java |
A.java |
foo/bar/B.java |
B.java |
C.properties |
C.properties |
Classes/dir/dir2/A.properties |
A.properties |
The target file name will always be the same, as defined by
to
from
will be ignored.
<mapper type="merge" to="archive.tar"/>
Source file name | Target file name |
A.java |
archive.tar |
foo/bar/B.java |
archive.tar |
C.properties |
archive.tar |
Classes/dir/dir2/A.properties |
archive.tar |
Both to
and from
define patterns that may
contain at most one *
. For each source file that matches
the from
pattern, a target file name will be constructed
from the to
pattern by substituting the *
in
the to
pattern with the text that matches the
*
in the from
pattern. Source file names
that don't match the from
pattern will be ignored.
<mapper type="glob" from="*.java" to="*.java.bak"/>
Source file name | Target file name |
A.java |
A.java.bak |
foo/bar/B.java |
foo/bar/B.java.bak |
C.properties |
ignored |
Classes/dir/dir2/A.properties |
ignored |
<mapper type="glob" from="C*ies" to="Q*y"/>
Source file name | Target file name |
A.java |
ignored |
foo/bar/B.java |
ignored |
C.properties |
Q.property |
Classes/dir/dir2/A.properties |
Qlasses/dir/dir2/A.property |
Both to
and from
define regular
expressions. If the source file name matches the from
pattern, the target file name will be constructed from the
to
pattern, using \0
to \9
as
back-references for the full
match (\0
) or the matches of the subexpressions in
parentheses.
Source
files not matching the from
pattern will be ignored.
Note that you need to escape a dollar-sign ($
) with
another dollar-sign in Ant.
The regexp mapper needs a supporting library and an implementation
of org.apache.tools.ant.util.regexp.RegexpMatcher
that
hides the specifics of the library. Ant comes with implementations for
jakarta-regexp and jakarta-ORO. If you compile
from sources and plan to use one of them, make sure the libraries are
in your CLASSPATH
. For information about using gnu.regexp or gnu.rex with Ant, see this
article.
Ant will choose the regular-expression library based on the following algorithm:
ant.regexp.matcherimpl
has been set, it is taken as the
name of the class implementing
org.apache.tools.ant.util.regexp.RegexpMatcher
that
should be used.<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/>
Source file name | Target file name |
A.java |
A.java.bak |
foo/bar/B.java |
foo/bar/B.java.bak |
C.properties |
ignored |
Classes/dir/dir2/A.properties |
ignored |
<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>
Source file name | Target file name |
A.java |
ignored |
foo/bar/B.java |
foo/bar/bar-B.java |
C.properties |
ignored |
Classes/dir/dir2/A.properties |
Classes/dir/dir2/dir2-A.properties |
<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/>
Source file name | Target file name |
A.java |
java.A |
foo/bar/B.java |
java.foo/bar/B |
C.properties |
properties.C |
Classes/dir/dir2/A.properties |
properties.Classes/dir/dir2/A |
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 buildfiles 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"/>
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. The timestamp of each source file is compared to the timestamp of a target file which is defined by a nested mapper element. At least one fileset and exactly one mapper element are required.
Attribute | Description | Required |
executable | the command to execute without any command line arguments. | Yes |
dest | the directory where the target files will be placed. | 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. If false, command will be executed once for every file. Defaults to false. | 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.
By default the file names of the source files will be added to the
end of the command line. If you need to place it somewhere different,
use a nested <srcfile>
element between your
<arg>
elements to mark the insertion point.
<targetfile>
is similar to
<srcfile>
and marks the position of the target
filename on the command line. If omitted, the target filenames will
not be added to the command line at all.
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>
.
<apply executable="cc" dest="src/C" parallel="false"> <arg value="-c"/> <arg value="-o"/> <targetfile/> <srcfile/> <fileset dir="src/C" includes="*.c"/> <mapper type="glob" from="*.c" to="*.o"/> </apply>
invokes cc -c -o TARGETFILE SOURCEFILE
for each
.c
file that is newer than the corresponding
.o
, replacing TARGETFILE with the absolute filename of
the .o
and SOURCEFILE with the absolute name of the
.c
file.
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 |
classpathref | the classpath to use, given as reference to a path defined elsewhere. | 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 class org.whatever.Myclass is found in Ant's classpath.
<property name="jaxp.jar" value="./lib/jaxp11/jaxp.jar"/> <available file="${jaxp.jar}" property="jaxp.jar.present"/>
sets the property jaxp.jar.present
to the value "true"
if the file ./lib/jaxp11/jaxp.jar is found.
...in project ... <property name="jaxp.jar" value="./lib/jaxp11/jaxp.jar"/> <path id="jaxp" location="${jaxp.jar}"/> ...in target ... <available classname="javax.xml.transform.Transformer" classpathref="jaxp" property="jaxp11.present"/>
sets the property jaxp11.present
to the value "true"
if the class javax.xml.transform.Transformer is found in the classpath referenced by jaxp
(in this case, it is ./lib/jaxp11/jaxp.jar
).
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. |
preservelastmodified | Give the copied files the same last modified time as the original files. Defaults to "no". | No |
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". Note that you can achieve the same effect by using a flatten mapper | No |
includeEmptyDirs | Copy empty directories included with the nested FileSet(s). Defaults to "yes". | No |
You can define file name transformations by using a nested mapper element. The default mapper used by
<copy>
is the identity.
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>
Copy a set of files to a directory appending
".bak
" to the file name on the fly
<copy todir="../backup/dir" > <fileset dir="src_dir" /> <mapper type="glob" from="*" to="*.bak"/> </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}".
<cvs command="-q diff -u -N" output="patch.txt"/>
silently (-q) creates a file called patch.txt which contains a unified (-u) diff which includes new files added via "cvs add" (-N) and can be used as input to patch.
<cvs command="update -A -d"/>
Updates from the head of repository ignoring sticky bits (-A) and creating any new directories as necessary (-d).
Note: the text of the command is passed to cvs "as-is" so any cvs options should appear before the command, and any command options should appear after the command as in the diff example above. See the cvs manual for details, specifically the Guide to CVS commands
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 by default. To remove empty directories, use the includeEmptyDirs atribute.
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 |
quiet | If the file does not exist, do not display a diagnostic message or modify the exit status to reflect an error. This means that if a file or directory cannot be deleted, then no error is reported. This setting emulates the -f option to the Unix "rm" command. ("true"/"false"). Default is "false" meaning things are "noisy". | No |
includeEmptyDirs | Set to "true" to delete empty directores when using filesets. Default is "false". | 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 the lib
directory, including all files
and subdirectories of lib
.
<delete> <fileset dir="." includes="**/*.bak"/> </delete>
deletes all files with the extension ".bak
" from the current directory
and any sub-directories.
<delete includeEmptyDirs="true" > <fileset dir="build" /> </delete>
deletes all files and subdirectories of build
, but not
build
itself.
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 |
newenvironment | Do not propagate old environment when new environment variables are specified. | No, default is false |
<exec dir="${src}" executable="cmd.exe" os="Windows 2000" output="dir.txt"> <arg line="/c dir"/> </exec>
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 |
newenvironment | Do not propagate old environment when new environment variables are specified. | No, default is false |
parallel | Run the command only once, appending all files as arguments. If false, command will be executed once for every file. Defaults to false. | 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.
By default the file names of the source files will be added to the
end of the command line. If you need to place it somewhere different,
use a nested <srcfile>
element between your
<arg>
elements to mark the insertion point.
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.
<execon executable="somecommand" parallel="false" > <arg value="arg1"/> <srfile/> <arg value="arg2"/> <fileset dir="/tmp"/> </execon>
invokes somecommand arg1 SOURCEFILENAME arg2
for each
file in /tmp
replacing SOURCEFILENAME with the absolute
filename of each file in turn. If parallel
had been set
to true, SOURCEFILENAME would be replaced with the absolute filenames
of all files separated by spaces.
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 usetimestamp 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 |
usetimestamp | 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" usetimestamp="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. The extended fileset attributes from the zip task are also available in the jar task. 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.
(The Jar task is a shortcut for specifying the manifest file of a JAR file. The same thing can be accomplished by using the fullpath attribute of a zipfileset in a Zip task. The one difference is that if the manifest attribute is not specified, the Jar task will include an empty one for you.)
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 into 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 into 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 into 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 into 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 |
output | Name of a file to write the output to. | 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 four choices:
For JDK 1.1/1.2, classic is the default. For JDK 1.3, modern is the default. If you wish to use a different compiler interface than one of the four supplied, write a class that implements the CompilerAdapter interface (package org.apache.tools.ant.taskdefs.compilers). Supply the full classname in the "build.compiler" property.
Attribute | Description | Required |
srcdir | location of the java files. | Yes, unless nested <src> elements are present. |
destdir | location 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 that contains include patterns. | 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 that contains exclude patterns. | No |
defaultexcludes | indicates whether default excludes should be used
(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 a reference to a PATH defined elsewhere. | No |
bootclasspathref | location of bootstrap class files, given as a reference to a PATH defined elsewhere. | No |
extdirs | location of installed extensions. | No |
encoding | encoding of source files. | No |
debug | indicates whether source should be compiled with debug
information; defaults to off . |
No |
optimize | indicates whether source should be compiled with
optimization; defaults to off . |
No |
deprecation | indicates whether source should be compiled with
deprecation information; defaults to 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 |
includeAntRuntime | whether to include the Ant run-time libraries;
defaults to no . |
No |
includeJavaRuntime | whether to include the default run-time
libraries from the executing VM; defaults to no . |
No |
failonerror |
indicates whether the build will continue even if there are compilation errors; defaults to true .
|
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.
src
, classpath
, bootclasspath
and extdirs
Javac
's srcdir, classpath,
bootclasspath and extdirs attributes are path-like structures 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 ${src}
directory, and stores
the .class
files in the ${build}
directory.
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 ${src}
directory, and stores the
.class
files in the ${build}
directory.
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
from compilation.
<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 property src2
. This can also be represented using nested
<src>
elements as follows:
<javac destdir="${build}" classpath="xyz.jar" debug="on"> <src path="${src}"/> <src path="${src2}"/> <include name="mypackage/p1/**"/> <include name="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 JDKs < 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 | Comma 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 whatever groups you specify, one group per table. This performs the same role as the group attribute. 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 |
title | Title of the group | Yes |
packages | List of packages to include in that group | Yes |
The doclet nested element is used to specify the doclet that javadoc will
use to process the input source files. A number of the standard javadoc arguments
are actually arguments of the standard doclet. If these are specified in the javadoc
task's attributes, they will be passed to the doclet specified in the
<doclet>
nested element. Such attributes should only be specified,
therefore, if they can be interpreted by the doclet in use.
If the doclet requires additional parameters, these can be specified with
<param>
elements within the <doclet>
element. These paramaters are restricted to simple strings. An example usage
of the doclet element is shown below:
<javadoc ...> <doclet name="theDoclet" path="path/to/theDoclet"> <param name="-foo" value="foovalue"/> <param name="-bar" value="barvalue"/> </doclet> </javadoc>
Javadoc
's sourcepath, classpath and
bootclasspath attributes are PATH like
structure and can also be set via nested sourcepath,
classpath and bootclasspath elements
respectively.
<javadoc packagenames="com.dummy.test.*" sourcepath="src" destdir="docs/api" author="true" version="true" use="true" windowtitle="Test API" doctitle="<h1>Test</h1>" bottom="<i>Copyright © 2000 Dummy Corp. All Rights Reserved.</i>"> <group title="Group 1 Packages" packages="com.dummy.test.a*"/> <group title="Group 2 Packages" packages="com.dummy.test.b*"/> <link offline="true" href="http://java.sun.com/products/jdk/1.2/docs/api/" packagelistLoc="C:\tmp"/> <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/> </javadoc>
A task to send SMTP email.
Attribute | Description | Required |
from | Email address of sender. | Yes |
tolist | Comma-separated list of recipients. | Yes |
message | Message to send in the body of the email. | Yes |
files | Filename(s) of text to send in the body of the email. Multiple files are comma-separated. | |
mailhost | Host name of the mail server. | No, default to "localhost" |
subject | Email subject line. | No |
<mail from="me" tolist="you" subject="Results of nightly build" files="build.log"/>
Sends an eMail from me to you with a subject of Results of nightly build and includes the contents of build.log in the body of the message.
Creates a directory. Also non-existent parent directories are created, when necessary.
Attribute | Description | Required |
dir | the directory to create. | Yes |
<mkdir dir="${dist}"/>
creates a directory ${dist}
.
<mkdir dir="${dist}/lib"/>
creates a directory ${dist}/lib
.
Moves a file to a new file or directory, or sets of files to a new directory. By default, the destination file is overwritten if it already exists. When overwrite is turned off, then files are only moved if the source file is newer than the destination file, or when the destination file does not exist.
FileSets are used to select sets of files to move to the todir directory.
Attribute | Description | Required |
file | the file to move | One of file or at least one nested fileset element |
tofile | the file to move to | With the file attribute, either tofile or todir can be used. With a nested fileset, only todir is allowed. |
todir | the directory to move to | |
overwrite | overwrite existing files even if the destination files are newer (default is "true") | No |
filtering | indicates whether token filtering should take place during the move. See the filter task for a description of how filters work. | No |
flatten | ignore directory structure of source directory, copy all files into a single directory, specified by the todir attribute (default is "false").Note that you can achieve the same effect by using a flatten mapper | No |
includeEmptyDirs | Copy empty directories included with the nested FileSet(s). Defaults to "yes". | No |
You can define file name transformations by using a nested mapper element. The default mapper used by
<copy>
is the identity.
Move a single file (rename a file)
<move file="file.orig" tofile="file.moved"/>
Move a single file to a directory
<move file="file.orig" todir="dir/to/move/to"/>
Move a directory to a new directory
<move todir="new/dir/to/move/to"> <fileset dir="src/dir"/> </move>
Move a set of files to a new directory
<move todir="some/new/dir" > <fileset dir="my/src/dir" > <include name="**/*.jar"/> <exclude name="**/ant.jar"/> </fileset> </move>
Append ".bak"
to the names of all files
in a directory.
<move todir="my/src/dir" > <fileset dir="my/src/dir" > <exclude name="**/*.bak"/> </fileset> <mapper type="glob" from="*" to="*.bak"/> </move>
Applies a diff file to originals.
Attribute | Description | Required |
patchfile | the file that includes the diff output | Yes |
originalfile | the file to patch | No, tries to guess it from the diff file |
backups | Keep backups of the unpatched files | No |
quiet | Work silently unless an error occurs | No |
reverse | Assume patch was created with old and new files swapped. | No |
ignorewhitespace | Ignore whitespace differences. | No |
strip | Strip the smallest prefix containing num leading slashes from filenames. | No |
<patch patchfile="module.1.0-1.1.patch"/>
applies the diff included in module.1.0-1.1.patch to the files in base directory guessing the filename(s) from the diff output.
<patch patchfile="module.1.0-1.1.patch" strip="1"/>
like above but one leading directory part will be removed. i.e. if the diff output looked like
--- a/mod1.0/A Mon Jun 5 17:28:41 2000 +++ a/mod1.1/A Mon Jun 5 17:28:49 2000the leading a/ will be stripped.
Sets a property (by name and value), or set of properties (from file or resource) in the project.
When a property was set by the user, or was a property in a parent project (that started this project with the ant task), then this property cannot be set, and will be ignored. This means that properties set outside the current project always override the properties of the current project.
There are five ways to set properties:
Although combinations of the three ways are possible, only one should be used at a time. Problems might occur with the order in which properties are set, for instance.
The value part of the properties being set, might contain references to other properties. These references are resolved at the time these properties are set. This also holds for properties loaded from a property file.
Attribute | Description | Required |
name | the name of the property to set. | Yes |
value | the value of the property. | Yes |
refid | Reference to an object defined elsewhere. Only yields reasonable results for references to PATH like structures or properties. | |
resource | the resource name of the property file. | |
file | the filename of the property file . | |
location | Sets the property to the absolute filename of the given file. If the value of this attribute is an absolute path, it is left unchanged (with / and \ characters converted to the current platforms conventions). Otherwise it is taken as a path relative to the project's basedir and expanded. | |
classpath | the classpath to use when looking up a resource. | No |
classpathref | the classpath to use when looking up a resource, given as reference to a PATH defined elsewhere.. | No |
Property
's classpath attribute is a PATH like structure and can also be set via a nested
classpath element.
<property name="foo.dist" value="dist"/>
sets the property foo.dist
to the value "dist".
<property file="foo.properties"/>
reads a set of properties from a file called "foo.properties".
<property resource="foo.properties"/>
reads a set of properties from a resource called "foo.properties".
Note that you can reference a global properties file for all of your Ant builds using the following:
<property file="${user.home}/.ant-global.properties"/>
since the "user.home" property is defined by the Java virtual machine to be your home directory. This technique is more appropriate for Unix than Windows since the notion of a home directory doesn't exist on Windows. On the JVM that I tested, the home directory on Windows is "C:\". Different JVM implementations may use other values for the home directory on Windows.
This task has been deprecated. Use the Move task instead.
Renames a given file.
Attribute | Description | Required |
src | file to rename. | Yes |
dest | new name of the file. | Yes |
replace | Enable replacing of existing file (default: on). | No |
<rename src="foo.jar" dest="${name}-${version}.jar"/>
Renames the file foo.jar
to ${name}-${version}.jar
(assuming name
and version
being predefined properties). If a file named ${name}-${version}.jar
already exists, it will be removed prior to renaming foo.jar
.
Replace is a directory based task for replacing the occurrence of a given string with another string in selected file.
If you want to replace a text that crosses line boundaries, you
must use a nested <replacetoken>
element.
Attribute | Description | Required |
file | file for which the token should be replaced. | Exactly one of the two. |
dir | The base directory to use when replacing a token in multiple files. | |
token | the token which must be replaced. | Yes, unless a nested replacetoken
element is used. |
value | the new value for the token. When omitted, an empty string ("") is used. | No |
propertyFile | valid property file from which properties specified using nested <replacefilter> elements are drawn. |
Yes only if property attribute of <replacefilter> is used. |
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 |
<replace file="${src}/index.html" token="@@@" value="wombat"/>
replaces occurrences of the string "@@@" with the string
"wombat", in the file ${src}/index.html
.
This task forms an implicit FileSet and
supports all attributes of <fileset>
as well as the
nested <include>
, <exclude>
and
<patternset>
elements.
If either the text you want to replace or the replacement text cross line boundaries, you can use nested elements to specify them.
<replace dir="${src}" value="wombat"> <include name="**/*.html"/> <replacetoken><![CDATA[multi line token]]></replacetoken> </replace>
replaces occurrences of the string "multi
line\ntoken" with the string "wombat", in all
HTML files in the directory ${src}
.Where \n is
the platform specific line separator.
<replace file="${src}/index.html"> <replacetoken><![CDATA[two line token]]></replacetoken> <replacevalue><![CDATA[two line token]]></replacevalue> </replace>
In addition to allowing for multiple replacements, optional nested <replacefilter>
elements allow replacement values to be extracted from a property file. The name of this file is specified using the <replace>
attribute propertyFile.
Attribute | Description | Required |
token | The string to search for. | Yes |
value | The replacement string. | Either may be specified, but not both. Both can be omitted, if desired. |
property | Name of the property whose value is to serve as the replacement value. |
If neither value nor property is used, the value provided using the <replace>
attribute value and/or the <replacevalue>
element is used. If no value was specified using either of these options, the token is replaced with an empty string.
<replace file="configure.sh" value="defaultvalue" propertyFile="source/name.properties" > <replacefilter token="@token1@" /> <replacefilter token="@token2@" value="value2"/> <replacefilter token="@token3@" property="property.key"/> </replace>
In file configure.sh
, replace all instances of "@token1@" with "defaultvalue", all instances of "@token2@" with "value2", and all instances of "@token3@" with the value of the property "property.key", as it appears in property file src/name.properties
.
Note: It is possible to use either the token/<replacetoken>
and value/<replacevalue>
attributes/elements, the nested replacefilter elements, or both in the same operation.
Runs the rmic compiler for a certain class.
Rmic can be run on a single class (as specified with the classname attribute) or a number of classes at once (all classes below base that are neither _Stub nor _Skel classes).
It is possible to refine the set of files that are being rmiced. 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 base
) as well as the nested
<include>
, <exclude>
and
<patternset>
elements.
Attribute | Description | Required |
base | the location to store the compiled files. | Yes |
classname | the class for which to run rmic . |
No |
filtering | indicates whether token filtering should take place | No |
sourcebase | Pass the "-keepgenerated" flag to rmic and move the generated source file to the base directory. | No |
stubversion | Specify the JDK version for the generated stub code. Specify "1.1" to pass the "-v1.1" option to rmic. | No |
classpath | The classpath to use during compilation | No |
classpathref | The classpath to use during compilation, given as reference to a PATH defined elsewhere | 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 |
verify | check that classes implement Remote before handing them to rmic (default is false) | No |
iiop | indates that portable (RMI/IIOP) stubs should be generated | No |
iiopopts | additional arguments for IIOP class generation | No |
idl | indates that IDL output files should be generated | No |
idlopts | additional arguments for IDL file generation | No |
debug | generate debug info (passes -g to rmic). Defaults to false. | No |
Rmic
's classpath attribute is a PATH like structure and can also be set via a nested
classpath elements.
<rmic classname="com.xyz.FooBar" base="${build}/classes"/>
runs the rmic compiler for the class com.xyz.FooBar
. The
compiled files will be stored in the directory ${build}/classes
.
<rmic base="${build}/classes" includes="**/Remote*.class"/>
runs the rmic compiler for all classes with .class
files below ${build}/classes
whose classname starts with
Remote. The compiled files will be stored in the directory
${build}/classes
.
Signs a jar or zip file with the javasign command line tool.
Attribute | Description | Required |
jar | the jar file to sign | Yes. |
alias | the alias to sign under | Yes. |
storepass | password for keystore integrity. | Yes. |
keystore | keystore location | No |
storetype | keystore type | No |
keypass | password for private key (if different) | No |
sigfile | name of .SF/.DSA file | No |
signedjar | name of signed JAR file | No |
verbose | (true | false) verbose output when signing | No |
internalsf | (true | false) include the .SF file inside the signature block | No |
sectionsonly | (true | false) don't compute hash of entire manifest | No |
<signjar jar="${dist}/lib/ant.jar" alias="apache-group" storepass="secret"/>
signs the ant.jar with alias "apache-group" accessing the keystore and private key via "secret" password.
Process a set of documents via XSLT.
This is useful for building views of XML based documentation, or in generating code.
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 basedir
)
as well as the nested <include>
, <exclude>
and <patternset>
elements.
Style supports the use of a <param> element which is use to pass values to an <xsl:param> declaration.
Attribute | Description | Required |
basedir | where to find the source xml file. | Yes |
destdir | directory where to store the results. | Yes |
extension | desired file extension to be used for the targets. If not specified, the default is "html". | No |
style | name of the stylesheet to use. | Yes |
processor | name of the XSLT processor to use. Permissible values are "trax" for a TraX compliant processor, "xslp" for the XSL:P processor, "xalan" for the Apache XML Xalan (version 1) processor, or the name of an arbitrary XSLTLiaison class. Defaults to trax, followed by xslp then xalan (in that order). The first one found in your class path is the one that is used. | 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 |
in | specifies a single XML document to be styled. Should be used with the out attribute. | No |
out | specifies the output name for the sytled result from the in attribute. | No |
Param is used to pass a parameter to the XSL stylesheet.
Attribute | Description | Required |
name | Name of the XSL parameter | Yes |
expression | XSL expression to be placed into the param. To pass a text value into the style sheet it needs to be escaped using single quotes. | Yes |
<style basedir="doc" destdir="build/doc" extension="html" style="style/apache.xsl"/>
Using XSL parameters
<style basedir="doc" destdir="build/doc" extension="html" style="style/apache.xsl"> <param name="date" expression="'07-01-2000'"/> </style>This will replace an xsl:param definition<xsl:param name="date"></xsl:param> with the text value 07-01-2000
Creates a tar archive.
The basedir attribute is the reference directory from where to tar.
It is possible to refine the set of files that are being tarred. 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.
Note that this task does not perform compression. You might want to use the GZip task to come up with a .tar.gz package.
Attribute | Description | Required |
tarfile | the tar-file to create. | Yes |
basedir | the directory from which to zip the files. | 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 |
<tar tarfile="${dist}/manual.tar" basedir="htdocs/manual"/> <gzip zipfile="${dist}/manual.tar.gz" src="${dist}/manual.tar"/>
tars all files in the htdocs/manual
directory into a file called manual.tar
in the ${dist}
directory, then applies the gzip task to compress
it.
<tar tarfile="${dist}/manual.tar" basedir="htdocs/manual" excludes="mydocs/**, **/todo.html" />
tars all files in the htdocs/manual
directory into a file called manual.tar
in the ${dist}
directory. Files in the directory mydocs
,
or files with the name todo.html
are excluded.
Adds a task definition to the current project, such that this new task can be used in the current project. Two attributes are needed, the name that identifies this task uniquely, and the full name of the class (including the packages) that implements this task.
Taskdef should be used to add your own tasks to the system. See also "Writing your own task".
Attribute | Description | Required |
name | the name of the task | Yes |
classname | the full class name implementing the task | Yes |
classpath | the classpath to
use when looking up classname . | No |
Taskdef
's classpath attribute is a PATH like structure and can also be set via a nested
classpath element.
<taskdef name="myjavadoc" classname="com.mydomain.JavadocTask"/>
makes a task called myjavadoc
available to Ant. The class com.mydomain.JavadocTask
implements the task.
Changes the modification time of a file and possibly creates it at the same time.
For JDK 1.1 only the creation of new files with a modification time of now works, all other cases will emit a warning.
Attribute | Description | Required |
file | the name of the file | Yes |
millis | specifies the new modification time of the file in milliseconds since midnight Jan 1 1970 | No |
datetime | specifies the new modification time of the file in the format MM/DD/YYYY HH:MM AM_or_PM. | No |
If both millis
and datetime
are omitted
the current time is assumed.
<touch file="myfile"/>
creates myfile
if it doesn't exist and changes the
modification time to the current time.
<touch file="myfile" datetime="06/28/2000 2:02 pm"/>
creates myfile
if it doesn't exist and changes the
modification time to Jun, 28 2000 2:02 pm (14:02 for those used to 24
hour times).
Sets the DSTAMP, TSTAMP and TODAY properties in the current project. The DSTAMP is in the "yyyymmdd" format, the TSTAMP is in the "hhmm" format and TODAY is "month day year".
These properties can be used in the buildfile, for instance, to create timestamped filenames or used to replace placeholder tags inside documents to indicate, for example, the release date. The best place for this task is in your initialization target.
Attribute | Description | Required |
No parameters |
Attribute | Description | Required |
property | The property which is to receive the date/time string in the given pattern | Yes |
pattern | The date/time pattern to be used. The values are defined by the Java SimpleDateFormat class | Yes |
Set the standard DSTAMP, TSTAMP and TODAY properties according to the formats above
<tstamp/>
As for the above example, set the standard properties and also set the property "TODAY_UK" with the date/time pattern "d MMM yyyy"
<tstamp> <format property="TODAY_UK" pattern="d MMMM yyyy"> </tstamp>
Sets a property if a target files are more up to date than a set of Source files. Source files are specified by nested <srcfiles> elements, these are FileSets, while target files are specified using a nested mapper element.
The value part of the property being set is true if the timestamp of the target files is more recent than the timestamp of every corresponding source file.
The default behavior is to use a merge
mapper whith the to
attribute set to the value of the
targetfile attribute.
Normally, this task is used to set properties that are useful to avoid target execution depending on the relative age of the specified files.
Attribute | Description | Required |
property | the name of the property to set. | Yes |
targetfile | the file for which we want to determine the status. | Yes, unless a nested mapper element is present. |
<uptodate property="xmlBuild.notRequired" targetfile="${deploy}\xmlClasses.jar" > <srcfiles dir= "${src}/xml" includes="**/*.dtd"/> </uptodate>
sets the property xmlBuild.notRequired
to the value "true"
if the ${deploy}/xmlClasses.jar is more up to date than any of the DTD files in the ${src}/xml directory.
This can be written as
<uptodate property="xmlBuild.notRequired" > <srcfiles dir= "${src}/xml" includes="**/*.dtd"/> <mapper type="merge" to="${deploy}\xmlClasses.jar"/> </uptodate>
as well.
Unzips a zip-, war- or jarfile.
For JDK 1.1 "last modified time" field is set to current time instead of being carried from zipfile.
File permissions will not be restored on extracted files.
Attribute | Description | Required |
src | zipfile to expand. | Yes |
dest | directory where to store the expanded files. | Yes |
<unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}" />
Untars a tarfile.
File permissions will not be restored on extracted files.
For JDK 1.1 "last modified time" field is set to current time instead of being carried from tarfile.
Attribute | Description | Required |
src | tarfile to expand. | Yes |
dest | directory where to store the expanded files. | Yes |
<gunzip src="tools.tar.gz"/>
<untar src="tools.tar" dest="${tools.home}"/>
An extension of the Jar task with special
treatment for files that should end up in the
WEB-INF/lib
, WEB-INF/classes
or
WEB-INF
directories of the Web Application Archive.
(The War task is a shortcut for specifying the particular layout of a WAR file. The same thing can be accomplished by using the prefix and fullpath attributes of zipfilesets in a Zip or Jar task.)
The extended zipfileset element from the zip task (with attributes prefix, fullpath, and src) is available in the War task.
Attribute | Description | Required |
warfile | the war-file to create. | Yes |
webxml | The deployment descriptor to use (WEB-INF/web.xml). | 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 |
The nested lib
element specifies a FileSet. All files included in this fileset will
end up in the WEB-INF/lib
directory of the war file.
The nested classes
element specifies a FileSet. All files included in this fileset will
end up in the WEB-INF/classes
directory of the war file.
The nested webinf
element specifies a FileSet. All files included in this fileset will
end up in the WEB-INF
directory of the war file. If this
fileset includes a file named web.xml
, the file is
ignored and you will get a warning.
Assume the following structure in the project's base directory:
thirdparty/libs/jdbc1.jar thirdparty/libs/jdbc2.jar build/main/com/myco/myapp/Servlet.class src/metadata/myapp.xml src/html/myapp/index.html src/jsp/myapp/front.jsp src/graphics/images/gifs/small/logo.gif src/graphics/images/gifs/large/logo.gifthen the war file
myapp.war
created with
<war warfile="myapp.war" webxml="src/metadata/myapp.xml"> <fileset dir="src/html/myapp"/> <fileset dir="src/jsp/myapp"/> <lib dir="thirdparty/libs"> <exclude name="jdbc1.jar"/> </lib> <classes dir="build/main"/> <zipfileset dir="src/graphics/images/gifs" prefix="images"/> </war>will consist of
WEB-INF/web.xml WEB-INF/lib/jdbc2.jar WEB-INF/classes/com/myco/myapp/Servlet.class META-INF/MANIFEST.MF index.html front.jsp images/small/logo.gif images/large/logo.gifusing Ant's default manifest file. The content of
WEB-INF/web.xml
is identical to
src/metadata/myapp.xml
.
Creates a zipfile.
The basedir attribute is the reference directory from where to zip.
Note that file permissions will not be stored in the resulting zipfile.
It is possible to refine the set of files that are being zipped. 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.
Or, you may place within it nested file sets, or references to file sets.
In this case basedir
is optional; the implicit file set is only used
if basedir
is set. You may use any mixture of the implicit file set
(with basedir
set, and optional attributes like includes
and optional subelements like <include>
); explicit nested
<fileset>
elements so long as at least one fileset total is specified. The ZIP file will
only reflect the relative paths of files within each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes (described below).
The whenempty
parameter controls what happens when no files match.
If skip
(the default), the ZIP is not created and a warning is issued.
If fail
, the ZIP is not created and the build is halted with an error.
If create
, an empty ZIP file (explicitly zero entries) is created,
which should be recognized as such by compliant ZIP manipulation tools.
Attribute | Description | Required |
zipfile | the zip-file to create. | Yes |
basedir | the directory from which to zip 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 |
whenempty | Behavior when no files match. | No |
The zip task supports any number of nested <fileset>
elements to specify
the files to be included in the archive.
A <zipfileset>
has three additional attributes: prefix, fullpath, and src. The
prefix and fullpath attributes modify the location of the files when they are placed
inside the archive. If the prefix attribute is set, all files in the fileset are prefixed
with that path in the archive. If the fullpath attribute is set, the file described by the fileset is placed at that
exact location in the archive. (The fullpath attribute can only be set for filesets that represent a single file. The prefix and fullpath attributes cannot both be set on the same fileset.) The src attribute
may be used in place of the dir attribute to specify a zip file whose
contents will be extracted and included in the archive. As with directories, include and exclude patterns may be used to specify a subset of the zip file
for inclusion in the archive.
<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" />
zips all files in the htdocs/manual
directory into a file called manual.zip
in the ${dist}
directory.
<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" excludes="mydocs/**, **/todo.html" />
zips all files in the htdocs/manual
directory. Files in the directory mydocs
,
or files with the name todo.html
are excluded.
<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" includes="api/**/*.html" excludes="**/todo.html" />
zips all files in the htdocs/manual
directory. Only html files under the directory api
are zipped, and files with the name todo.html
are excluded.
<zip zipfile="${dist}/manual.zip"> <fileset dir="htdocs/manual"/> <fileset dir="." includes="ChangeLog.txt"/> </zip>
zips all files in the htdocs/manual
directory, and also adds the file ChangeLog.txt
in the
current directory. ChangeLog.txt
will be added to the top of the ZIP file, just as if
it had been located at htdocs/manual/ChangeLog.txt
.
<zip zipfile="${dist}/manual.zip"> <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/> <zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/> <zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/> </zip>
zips all files in the htdocs/manual
directory into the docs/user-guide
directory
in the archive, adds the file ChangeLog27.txt
in the
current directory as docs/ChangeLog.txt
, and includes all the html files in examples.zip
under docs/examples
. The archive might end up containing the files:
docs/user-guide/html/index.html
docs/ChangeLog.txt
docs/examples/index.html
The tasks listed here are not included in the ant.jar included in the binary distribution of Ant. To use them you should download optional.jar and put in the lib-subdirectory of your Ant-installation. Additionaly some of these tasks require external libraries to be put on your CLASSPATH.
The cab task creates Microsoft cab archive files. It is invoked similar to the jar or zip tasks. This task will only work on Windows, and will be silently ignored on other platforms. You must have the Microsoft cabarc tool available in your executable path.
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.
Attribute | Description | Required |
cabfile | the name of the cab file to create. | Yes |
basedir | the directory to start archiving files from. | Yes |
verbose | set to "yes" if you want to see the output from the cabarc tool. defaults to "no". | No |
compress | set to "no" to store files without compressing. defaults to "yes". | No |
options | use to set additional command-line options for the cabarc tool. should not normally be necessary. | 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 |
<cab cabfile="${dist}/manual.cab" basedir="htdocs/manual" />
cabs all files in the htdocs/manual directory into a file called manual.cab in the ${dist} directory.
<cab cabfile="${dist}/manual.cab" basedir="htdocs/manual" excludes="mydocs/**, **/todo.html" />
cabs all files in the htdocs/manual directory into a file called manual.cab in the ${dist} directory. Files in the directory mydocs, or files with the name todo.html are excluded.
<cab cabfile="${dist}/manual.cab" basedir="htdocs/manual" includes="api/**/*.html" excludes="**/todo.html" verbose="yes" />
cab all files in the htdocs/manual directory into a file called manual.cab in the ${dist} directory. Only html files under the directory api are archived, and files with the name todo.html are excluded. Output from the cabarc tool is displayed in the build output.
Note: The ftp-task uses the NetComponents-Package which you will need to download from http://www.savarese.org and add to your classpath.
The ftp task implements a basic FTP client that can send, receive, list, and delete files. See below for descriptions and examples of how to perform each task.
The ftp task makes no attempt to determine what file system syntax is required by the remote server, and defaults to Unix standards. remotedir must be specified in the exact syntax required by the ftp server. If the usual Unix conventions are not supported by the server, separator can be used to set the file separator that should be used instead.
See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.
Attribute | Description | Required |
server | the address of the remote ftp server. | Yes |
port | the port number of the remote ftp server. Defaults to port 21. | No |
userid | the login id to use on the ftp server. | Yes |
password | the login password to use on the ftp server. | Yes |
remotedir | the directory to which to upload files on the ftp server. | No |
action | the ftp action to perform, defaulting to "send". Currently supports"put", "get", "del", and "list". | No |
binary | selects binary-mode ("yes") or text-mode ("no") transfers. Defaults to "yes" | No |
passive | selects passive-mode ("yes") transfers. Defaults to "no" | No |
verbose | displays information on each file transferred if set to "yes". Defaults to "no". | No |
depends | transfers only new or changed files if set to "yes". Defaults to "no". | No |
newer | a synonym for depends. | No |
separator | sets the file separator used on the ftp server. Defaults to "/". | No |
listing | the file to write results of the "list" action. Required for the "list" action, ignored otherwise. | No |
The easiest way to describe how to send files is with a couple of examples:
<ftp server="ftp.apache.org" userid="anonymous" password="me@myorg.com"> <fileset dir="htdocs/manual"/> </ftp>
Logs in to ftp.apache.org
as anonymous
and
uploads all files in the htdocs/manual
directory
to the default directory for that user.
<ftp server="ftp.apache.org" remotedir="incoming" userid="anonymous" password="me@myorg.com" depends="yes" > <fileset dir="htdocs/manual"/> </ftp>
Logs in to ftp.apache.org
as anonymous
and
uploads all new or changed files in the htdocs/manual
directory
to the incoming
directory relative to the default directory
for anonymous
.
<ftp server="ftp.apache.org" port="2121" remotedir="/pub/incoming" userid="coder" password="java1" depends="yes" binary="no" > <fileset dir="htdocs/manual"> <include name="**/*.html"/> </fileset> </ftp>
Logs in to ftp.apache.org
at port 2121
as
coder
with password java1
and uploads all new or
changed HTML files in the htdocs/manual
directory to the
/pub/incoming
directory. The files are transferred in text mode. Passive mode has been switched on to send files from behind a firewall.
<ftp server="ftp.nt.org" remotedir="c:\uploads" userid="coder" password="java1" separator="\" verbose="yes"
> <fileset dir="htdocs/manual"> <include name="**/*.html"/> </fileset> </ftp>
Logs in to the Windows-based ftp.nt.org
as
coder
with password java1
and uploads all
HTML files in the htdocs/manual
directory to the
c:\uploads
directory. Progress messages are displayed as each
file is uploaded.
Getting files from an FTP server works pretty much the same way as sending them does. The only difference is that the nested filesets use the remotedir attribute as the base directory for the files on the FTP server, and the dir attribute as the local directory to put the files into. The file structure from the FTP site is preserved on the local machine.
<ftp action="get" server="ftp.apache.org" userid="anonymous" password="me@myorg.com"> <fileset dir="htdocs/manual" > <include name="**/*.html"/> </fileset> </ftp>
Logs in to ftp.apache.org
as anonymous
and
recursively downloads all .html files from default directory for that user
into the htdocs/manual
directory on the local machine.
<ftp action="del" server="ftp.apache.org" userid="anonymous" password="me@myorg.com" > <fileset> <include name="**/*.tmp"/> </fileset> </ftp>
Logs in to ftp.apache.org
as anonymous
and
tries to delete all *.tmp files from the default directory for that user.
If you don't have permission to delete a file, a BuildException is thrown.
<ftp action="list" server="ftp.apache.org" userid=quot;anonymous" password="me@myorg.com" listing="data/ftp.listing" > <fileset> <include name="**"/> </fileset> </ftp>
This provides a file listing in data/ftp.listing
of all the files on
the FTP server relative to the default directory of the anonymous
user. The listing is in whatever format the FTP server normally lists files.
Compiles a NetRexx source tree within the running (Ant) VM.
The source and destination directory will be recursively scanned for NetRexx source files to compile. Only NetRexx files that have no corresponding class file or where the class file is older than the java file will be compiled.
Files in the source tree are copied to the destination directory, allowing support files to be located properly in the classpath. The source files are copied because the NetRexx compiler cannot produce class files in a specific directory via parameters
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.
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 |
binary | Whether literals are treated as the java binary type rather than the NetRexx types | No |
classpath | The classpath to use during compilation | No |
comments | Whether comments are passed through to the generated java source | No |
compact | Whether error messages come out in compact or verbose format | No |
compile | Whether the NetRexx compiler should compile the generated java code | No |
console | Whether or not messages should be displayed on the 'console' | No |
crossref | Whether variable cross references are generated | No |
decimal | Whether decimal arithmetic should be used for the NetRexx code | No |
defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | No |
destDir | the destination directory into which the NetRexx source files should be copied and then compiled | Yes |
diag | Whether diagnostic information about the compile is generated | 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 |
explicit | Whether variables must be declared explicitly before use | No |
format | Whether the generated java code is formatted nicely or left to match NetRexx line numbers for call stack debugging | 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 |
java | Whether the generated java code is produced | No |
keep | Sets whether the generated java source file should be kept after compilation. The generated files will have an extension of .java.keep, not .java | No |
logo | Whether the compiler text logo is displayed when compiling | No |
replace | Whether the generated .java file should be replaced when compiling | No |
savelog | Whether the compiler messages will be written to NetRexxC.log as well as to the console | No |
sourcedir | Tells the NetRexx compiler to store the class files in the same directory as the source files. The alternative is the working directory | No |
srcDir | Set the source dir to find the source Netrexx files | Yes |
strictargs | Tells the NetRexx compiler that method calls always
need parentheses, even if no arguments are needed, e.g.
aStringVar.getBytes vs.
aStringVar.getBytes() |
No |
strictassign | Tells the NetRexx compile that assignments must match exactly on type | No |
strictcase | Specifies whether the NetRexx compiler should be case sensitive or not | No |
strictimport | Whether classes need to be imported explicitly using an
import statement. By default the NetRexx compiler will
import certain packages automatically |
No |
strictprops | Whether local properties need to be qualified
explicitly using this |
No |
strictsignal | Whether the compiler should force catching of exceptions by explicitly named types | No |
symbols | Whether debug symbols should be generated into the class file | No |
time | Asks the NetRexx compiler to print compilation times to the console | No |
trace | Turns on or off tracing and directs the resultant trace output | No |
utf8 | Tells the NetRexx compiler that the source is in UTF8 | No |
verbose | Whether lots of warnings and error messages should be generated | Yes |
<netrexxc srcDir="/source/project" includes="vnr/util/*" destDir="/source/project/build" classpath="/source/project2/proj.jar" comments="true" crossref="false" replace="true" keep="true"/>
This task has been deprecated. Use the move task with a glob mapper instead.
Renames files in the srcDir
directory ending with the
fromExtension
string so that they end with the
toExtension
string. Files are only replaced if
replace
is true
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 |
defaultexcludes | indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. | 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 |
fromExtention | The string that files must end in to be renamed | 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 |
replace | Whether the file being renamed to should be replaced if it already exists | No |
srcDir | The starting directory for files to search in | Yes |
toExtension | The string that renamed files will end with on completion | Yes |
<renameext srcDir="/source/project1" includes="**" excludes="**/samples/*" fromExtension=".java.keep" toExtension=".java" replace="true"/>
Execute a script in a BSF supported language.
All items (tasks, targets, etc) of the running project are
accessible from the script, using either their name
or
id
attributes.
Scripts can do almost anything a task written in Java could do.
Attribute | Description | Required |
language | The programming language the script is written in. Must be a supported BSF language | No |
src | The location of the script as a file, if not inline | No |
<project name="squares" default="main" basedir="."> <target name="setup"> <script language="javascript"> <![CDATA[ for (i=1; i<=10; i++) { echo = squares.createTask("echo"); main.addTask(echo); echo.setMessage(i*i); } ]]> </script> </target> <target name="main" depends="setup"/> </project>
generates
setup: main: 1 4 9 16 25 36 49 64 81 100 BUILD SUCCESSFUL
Another example, using references by id and two different scripting languages:
<project name="testscript" default="main"> <target name="sub"> <echo id="theEcho"/> </target> <target name="sub1"> <script language="netrexx"><![CDATA[ theEcho.setMessage("In sub1") sub.execute ]]></script> </target> <target name="sub2"> <script language="javascript"><![CDATA[ theEcho.setMessage("In sub2"); sub.execute(); ]]></script> </target> <target name="main" depends="sub1,sub2"/> </project>
generates
sub1: In sub1 sub2: In sub2 main: BUILD SUCCESSFUL
Plays a sound-file at the end of the build, according to whether
the build failed or succeeded. You can specify either a specific
sound-file to play, or, if a directory is specified, the
<sound>
task will randomly select a file to play.
Note: At this point, the random selection is based on all the files
in the directory, not just those ending in appropriate suffixes
for sound-files, so be sure you only have sound-files in the
directory you specify.
Attribute | Description | Required |
loops | the number of extra times to play the sound-file;
default is 0 .
|
No |
duration | the amount of time (in milliseconds) to play the sound-file. | No |
To specify the sound-files or the sound-file directories, use the
nested <success>
and <fail>
elements:
<success> the path to a sound-file directory, or the name of a specific sound-file, to be played if the build succeeded. <fail> the path to a sound-file directory, or the name of a specific sound-file, to be played if the build succeeded.
plays the<target name="fun" if="fun" unless="fun.done"> <sound loops="2"> <success source="${user.home}/sounds/bell.wav"/> <fail source="${user.home}/sounds/ohno.wav"/> </sound> <property name="fun.done" value="true"/> </target>
bell.wav
sound-file if the build succeeded, or
the ohno.wav
sound-file if the build failed, three times,
if the fun
property is set to true
.
If the target
is a dependency of an "initialization" target that other
targets depend on, the
fun.done
property prevents the target from being executed
more than once.
randomly selects a sound-file to play when the build succeeds or fails.<target name="fun" if="fun" unless="fun.done"> <sound> <success source="//intranet/sounds/success"/> <fail source="//intranet/sounds/failure"/> </sound> <property name="fun.done" value="true"/> </target>
If you do specify a userid and password, the system will assume a common unix prompt to wait on. This behavior can be easily over-ridden.
Attribute | Values | Required |
---|---|---|
userid | the login id to use on the telnet server. | No |
password | the login password to use on the telnet server. | No |
server | the address of the remote telnet server. | Yes |
port | the port number of the remote telnet server. Defaults to port 23. | No |
initialCR | send a cr after connecting ("yes"). Defaults to "no". | No |
timeout | set a default timeout to wait for a response. Specified in seconds. Default is no timeout. | No |
This task can be rewritten as:<telnet userid="bob" password="badpass" server="localhost"> <read>/home/bob</read> <write>ls</write> <read string="/home/bob"/> </telnet>
A timeout can be specified at the <telnet> level or at the <read> level. This will connect, issue a sleep command that is suppressed from displaying and wait 10 seconds before quitting.<telnet server="localhost"> <read>ogin:</read> <write>bob</write> <read>assword:</read> <write>badpass</write> <read>/home/bob</read> <write>ls</write> <read>/home/bob</read> </telnet>
The task can be used with other ports as well:<telnet userid="bob" password="badpass" server="localhost" timeout="20"> <read>/home/bob</read> <write echo="false">sleep 15</write> <read timeout="10">/home/bob</read> </telnet>
<telnet port="80" server="localhost" timeout="20"> <read/> <write>GET / http/0.9</write> <write/> <read timeout="10"></HTML></read> </telnet>
If you specify two or more attributes from version, date and label only one will be used in the order version, date, label.
Attribute | Values | Required |
---|---|---|
login | username,password | No |
vsspath | SourceSafe path | Yes |
localpath | Override the working directory and get to the specified path | No |
writable | true or false | No |
recursive | true or false | No |
version | a version number to get | No |
date | a date stamp to get at | No |
label | a label to get for | No |
ssdir | directory where ss.exe resides. By default the
task expects it to be in the PATH. |
No |
Note that only one of version, date or label should be specified
<vssget localPath="C:\mysrc\myproject" recursive="true" label="Release1" login="me,mypassword" vsspath="/source/aProject" writable="true"/>
Does a get on the VSS-Project $/source/aproject using the username me and the password mypassword. It will recursively get the files which are labeled Release1 and write them to the local directory C:\mysrc\myproject. The local files will be writable.
To use build events you need to create an ant Project
object. You can then call the
addBuildListener
method to add your listener to the project. Your listener must implement
the org.apache.tools.antBuildListener
interface. The listener will receive BuildEvents
for the following events
-listener
option. For example:
will run Ant with a listener that generates an XML representation of the build progress. This listener is included with Ant, as is the default listener, which generates the logging to standard output.ant -listener org.apache.tools.ant.XmlLogger
It is very easy to write your own task:
org.apache.tools.ant.Task
.public void
method that takes a single argument. The
name of the method must begin with set
, followed by the
attribute name, with the first character of the name in uppercase, and the rest in
lowercase. The type of the attribute can be:
String
true
,
yes
, or on
)
Class
File
(in which case the value of the attribute is interpreted relative to the
project's basedir)
String
argument
org.apache.tools.ant.types.EnumeratedAttribute
as an argument
to your setter method. See
org/apache/tools/ant/taskdefs/FixCRLF.java
for
an example.public void
addText(String)
method.public
method that takes no arguments and returns
an Object
type. The name of the create method must begin with
create
, followed by the element name. An add method must be
a public void
method that takes a single argument of an
Object
type with a no-argument constructor.
The name of the add method
must begin with add
, followed by the element name.
public void execute
method, with no arguments, that
throws a BuildException
. This method implements the task
itself.project
and
location
variables.id
attribute to this task,
the project
registers a reference to this newly created task, at parser
time.target
variable.init()
is called at parser time.createXXX()
methods or
instantiated and added to this task via its addXXX()
methods, at parser time.setXXX
methods, at runtime.addText
method, at runtime.setXXX
methods, at runtime.execute()
is called at runtime. While the above initialization
steps only occur once, the execute() method may be
called more than once, if the task is invoked more than once. For example,
if target1
and target2
both depend
on target3
, then running
'ant target1 target2'
will run all tasks in
target3
twice.Let's write our own task, which prints a message on the
System.out
stream.
The
task has one attribute, called message
.
package com.mydomain; import org.apache.tools.ant.BuildException; import org.apache.tools.ant.Task; public class MyVeryOwnTask extends Task { private String msg; // The method executing the task public void execute() throws BuildException { System.out.println(msg); } // The setter for the "message" attribute public void setMessage(String msg) { this.msg = msg; } }
It's really this simple ;-)
Adding your task to the system is rather simple too:
<taskdef>
element to your project.
This actually adds your task to the system.<?xml version="1.0"?> <project name="OwnTaskExample" default="main" basedir="."> <taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/> <target name="main"> <mytask message="Hello World! MyVeryOwnTask works!"/> </target> </project>
Another way to add a task (more permanently), is to add the task name and
implementing class name to the default.properties
file in the
org.apache.tools.ant.taskdefs
package. Then you can use it as if it were a built-in task.
There is an on-line FAQ for Ant at jakarta.apache.org. This FAQ is interactive, which means you can ask and answer questions on line.
One of the questions popping up quite often is "Is there a DTD for buildfiles?" Please refer to the FAQ for an answer.
To provide feedback on this software, please subscribe to the Ant User Mail List (ant-user-subscribe@jakarta.apache.org)
If you want to contribute to Ant or stay current with the latest development, join the Ant Development Mail List (ant-dev-subscribe@jakarta.apache.org)
Archives of both lists can be found at http://archive.covalent.net/. Many thanks to Covalent Technologies. A searchable archive can be found at http://marc.theaimsgroup.com. If you know of any additional archive sites, please report them to the lists.
Copyright © 2000,2001 Apache Software Foundation. All rights Reserved.