by
+by
Version 1.0.2 - 2000/01/26
+Version 1.0.3 - 2000/02/06
When finished, use
-+
build.bat -Ddist.dir=<directory to install Ant> dist
build.bat -Ddist.dir=<directory to install Ant> dist
for Windows, and
-+
build.sh -Ddist.dir=<directory to install Ant> dist
build.sh -Ddist.dir=<directory to install Ant> dist
for UNIX, to create a binary distribution of Ant. This distribution can be found in the directory you specified.
@@ -156,22 +157,22 @@ Options: -D<property>=<value> use value for given property-ant+ant
runs Ant using the build.xml file in the current directory, on
the default target.
-ant -buildfile test.xml+ant -buildfile test.xml
runs Ant using the test.xml file in the current directory, on
the default target.
-ant -buildfile test.xml dist+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+ant -buildfile test.xml -Dbuild=build/classes dist
runs Ant using the test.xml file in the current directory, on a
target called dist. It also sets the build property to the
@@ -180,7 +181,7 @@ value build/classes.
When you have installed Ant in the do-it-yourself way, Ant can be started with:
-set CLASSPATH=c:\ant\lib\ant.jar;c:\ant\lib\xml.jar;c:\jdk1.2.2\lib\tools.jar +set CLASSPATH=c:\ant\lib\ant.jar;c:\ant\lib\xml.jar;c:\jdk1.2.2\lib\tools.jar java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]
These instructions actually do exactly the same as the ant
@@ -264,7 +265,7 @@ 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" ... />+<name attribute1="value1" attribute2="value2" ... />
where name is the name of the task, attribute-x the attribute name, and value-x the value of this attribute.
@@ -281,7 +282,7 @@ task attributes. This is done by placing the property name between This is resolved as "build/classes".-<project name="foo" default="dist" basedir="."> +<project name="foo" default="dist" basedir="."> <target name="init"> <tstamp/> <property name="build" value="build" /> @@ -310,6 +311,95 @@ This is resolved as "build/classes".
Some tasks use directory trees for the task they perform. For instance, the Javac task which works upon a directory tree with .java files. +Sometimes it can be very useful to work on a subset of that directory tree. This +section describes how you can select a subset of such a directory tree.
+Ant gives you two ways to create a subset, which both 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.
+As described earlier, patterns are used for the inclusion and exclusion. +These patterns look very much like the patterns used in DOS and UNIX:
+'*' matches zero or more characters, '?' matches one character.
+Examples:
+'*.java' matches '.java', 'x.java' and 'FooBar.java', but not 'FooBar.xml' +(does not end with '.java').
+'?.java' matches 'x.java', 'A.java', but not '.java' or 'xyz.java' (both +don't have one character before '.java').
+Combinations of '*'s and '?'s are allowed.
+Matching is done per-directory. This means that first the first directory in +the pattern is matched against the first directory in the path to match. Then +the second directories are matched, and so on. E.g. when we have the pattern '/?abc/*/*.java' +and the path '/xabc/foobar/test.java', then first '?abc' is matched with 'xabc', +then '*' is matched with 'foobar' and finally '*.java' is matched with 'test.java'. +They all match so the path matches the pattern.
+Too make things a bit more flexible, we add one extra feature, which makes it +possible to match multiple directory levels. This can be used to match a +complete directory tree, or a file anywhere in the directory tree. To do this, '**' +must be used as the name of a directory. When '**' is used as the name of a +directory in the pattern, it matches zero or more directories. For instance: +'/test/**' matches all files/directories under '/test/', such as '/test/x.java', +or '/test/foo/bar/xyz.html', but not '/xyz.xml'.
+There is one "shorthand", if a pattern ends with '/' or '\', then '**' +is appended. E.g. "mypackage/test/" is interpreted as were it "mypackage/test/**".
+Examples:
+| **/CVS/* | +Matches all files in CVS directories, that can be located
+ anywhere in the directory tree.
+ Matches: +CVS/Repository But not: +org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match) |
+
| org/apache/jakarta/** | +Matches all files in the org/apache/jakarta directory tree.
+ Matches: +org/apache/jakarta/tools/ant/docs/index.html But not: +org/apache/xyz.java ('jakarta'/' part is missing) |
+
| org/apache/**/CVS/* | +Matches all files in CVS directories, that are located
+ anywhere in the directory tree under org/apache.
+ Matches: +org/apache/CVS/Entries But not: +org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match) |
+
| **/test/** | +Matches all files which have a directory 'test' in their + path, including 'test' as a filename. | +
When these patterns are used in inclusion and exclusion, you have a powerful +way to select just the files you want.
+ <copydir srcdir="${src}"
+ destdir="${dist}"
+ includes="**/images/*"
+ excludes="**/*.gif" />
+This copies all files in directories called "images", that are +located in the directory tree "${src}" to the destination "${dist}", +but excludes all "*.gif" files from the copy.
+--
<ant antfile="subproject/subbuild.xml" dir="subproject" -target="compile" />+
<ant dir="subproject" />+
<ant antfile="subproject/subbuild.xml" dir="subproject" + target="compile" />
<ant dir="subproject" />
-+
<chmod src="${dist}/start.sh" perm="ugo+rx" -/>
<chmod src="${dist}/start.sh" perm="ugo+rx" + />
makes the "start.sh" file readable and executable for anyone on a UNIX system.
@@ -411,11 +501,20 @@ UNIX system.Copies a directory tree from the source to the destination.
-It is possible to exclude a set of files from the files that are being -copied. This can be done with the ignore attribute. This attribute -contains the names of the files/directories that must be excluded from the copy. -The names specified in the ignore attribute are just names, they do not -contain any path information!
+It is possible to refine the set of files that are being copied. This can be +done with the includes, excludes and defaultexcludes +attributes. With the includes attribute you specify the files you want to +have included by using patterns. The exclude 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. The patterns are +relative to the src directory.
+The ignore attribute contains the names of the files/directories that +must be excluded from the copy. The names specified in the ignore +attribute are just names, they do not contain any path information! Note that +this attribute has been replaced by the excludes attribute.
| ignore | -comma separated list of filenames/directorynames to ignore. | +comma separated list of filenames/directorynames to ignore. + No files (except default excludes) are excluded when omitted. (deprecated, + use excludes instead). | +No | +
| includes | +comma separated list of patterns of files that must be + included. All files are included 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 | +|
| defaultexcludes | +indicates whether default excludes should be used or not + ("yes"/"no"). Default excludes are used when omitted. | No |
-+-
<copydir src="${src}/resources" dest="${dist}" -/>
<copydir src="${src}/resources"
+ dest="${dist}"
+ />
copies the directory ${src}/resources to ${dist}.
---
<copydir src="${src}/resources" dest="${dist}" -ignore="old, Test.java" />
copies the directory ${src}/resources to ${dist}.
-All files/directories with the names old and Test.java
-are excluded from the copy. When old or Test.java is
-the name of a directory, then that whole directory is excluded from the copy.
<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.
--
<copyfile src="test.java" dest="subdir/test.java" -/>+
<copyfile src="${src}/index.html" dest="${dist}/help/index.html" -/>+
<copyfile src="test.java" dest="subdir/test.java" + />
<copyfile src="${src}/index.html" dest="${dist}/help/index.html" + />
-+
<cvs cvsRoot=":pserver:anoncvs@jakarta.apache.org:/home/cvspublic" -package="jakarta-tools" dest="${ws.dir}" />
<cvs cvsRoot=":pserver:anoncvs@jakarta.apache.org:/home/cvspublic" + package="jakarta-tools" dest="${ws.dir}" />
This checks out the package/module "jakarta-tools" from the CVS repository pointed to by the cvsRoot attribute, and stores the files in "${ws.dir}".
@@ -545,8 +669,8 @@ repository pointed to by the cvsRoot attribute, and stores the files in "${--
<delete file="/lib/ant.jar" />+
<delete file="${ant}" />+
<delete file="/lib/ant.jar" />
<delete file="${ant}" />
--
<deltree dir="dist" />+
<deltree dir="${dist}" />+
<deltree dir="dist" />
<deltree dir="${dist}" />
-+
<echo message="Hello world" />
<echo message="Hello world" />
-+
<exec dir="${src}" command="dir" os="windows" -output="dir.txt" />
<exec dir="${src}" command="dir" os="windows" + output="dir.txt" />
-+
<expand src="${tomcat_src}/tools-src.zip" dest="${tools.home}" -/>
<expand src="${tomcat_src}/tools-src.zip" dest="${tools.home}" + />
-+
<get src="http://jakarta.apache.org/" dest="help/index.html" -/>
<get src="http://jakarta.apache.org/" dest="help/index.html" + />
-+
<gzip src="test.tar" zipfile="test.tar.gz" />
<gzip src="test.tar" zipfile="test.tar.gz" + />
Jars a set of files.
The basedir attribute is the reference directory from where to jar.
-When "*" is used for items, all files in the basedir, and its -subdirectories, will be jarred. Otherwise all the files and directories +
It is possible to refine the set of files that are being jarred. This can be +done with the includes, excludes and defaultexcludes +attributes. With the includes attribute you specify the files you want to +have included by using patterns. The exclude 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. The patterns are +relative to the basedir directory.
+The includes, excludes and defaultexcludes attributes +replace the items and ignore attributes. The following explains +how the deprecated items and ignore attribute behave.
+When "*" is used for items, all files in the basedir, and +its subdirectories, will be jarred. Otherwise all the files and directories mentioned in the items list will jarred. When a directory is specified, then all files within it are also jarred.
With the ignore attribute, you can specify files or directories to @@ -753,13 +891,34 @@ attribute are just names, they do not contain any path information!
-+-
<jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" -items="*" />
<jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" />
jars all files in the ${build}/classes directory in a file
called app.jar in the ${dist}/lib directory.
-+-
<jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" -items="*" ignore="Test.class" />
<jar jarfile="${dist}/lib/app.jar"
+ basedir="${build}/classes"
+ excludes="**/Test.class"
+ />
+jars all files in the ${build}/classes directory in a file
+called app.jar in the ${dist}/lib directory. Files
+with the name Test.class are excluded.
<jar jarfile="${dist}/lib/app.jar"
+ basedir="${build}/classes"
+ includes="mypackage/test/**"
+ excludes="**/Test.class"
+ />
+jars all files in the ${build}/classes directory in a file
+called app.jar in the ${dist}/lib directory. Only
+files under the directory mypackage/test are used, and files with
+the name Test.class are excluded.
<jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" items="*" />
+jars all files in the ${build}/classes directory in a file
+called app.jar in the ${dist}/lib directory.
<jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" items="*" ignore="Test.class" />
jars all files in the ${build}/classes directory in a file
called app.jar in the ${dist}/lib directory.
Files/directories with the name Test.class are excluded.
--
<java class="test.Main" />-
<java class="test.Main" args="-h" />+
<java class="test.Main" args="-h" -fork="yes" jvmargs="-Xrunhprof:cpu=samples,file=log.txt,depth=3" -/>+
<java class="test.Main" />+
<java class="test.Main" args="-h" />
<java class="test.Main" args="-h" + fork="yes" jvmargs="-Xrunhprof:cpu=samples,file=log.txt,depth=3" + />
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, excludes and defaultexcludes +attributes. With the includes attribute you specify the files you want to +have included by using patterns. The exclude 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. The patterns are +relative to the srcdir directory.
It is possible to use different compilers. This can be selected with the "build.compiler" property. There are three choices:
-+-
<javac srcdir="${src}" destdir="${build}" -classpath="xyz.jar" --debug="on" />
<javac srcdir="${src}"
+ destdir="${build}"
+ classpath="xyz.jar"
+ debug="on"
+ />
+compiles all .java files under the directory ${src}, and stores
+the .class files in the directory ${build}. It also copies the non-java
+files from the tree under ${src} to the tree under ${build}.
+The classpath used contains xyz.jar, and debug information is on.
<javac srcdir="${src}"
+ destdir="${build}"
+ includes="mypackage/p1/**,mypackage/p2/**"
+ excludes="mypackage/p1/testpackage/**"
+ classpath="xyz.jar"
+ debug="on"
+ />
+compiles .java files under the directory ${src}, and stores the
+.class files in the directory ${build}. It also copies the non-java
+files from the tree under ${src} to the tree under ${build}.
+The classpath used contains xyz.jar, and debug information is on.
+Only files under mypackage/p1 and mypackage/p2 are
+used. Files in the mypackage/p1/testpackage directory are excluded
+form compilation and copy.
Generates code documentation using the javadoc tool.
-The source directory will be recursively scanned for Java -source files to 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, but it's not used so frequently.
+The source directory will be recursively scanned for Java source files to 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, but it's +not used so 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.
@@ -968,7 +1188,8 @@ instead.-<javadoc packagenames="com.dummy.test.*" +<javadoc packagenames="com.dummy.test.*" sourcepath="src" destdir="docs/api" author="true" @@ -1228,8 +1449,8 @@ separator, which might we changed with the sep attribute.Examples
-+
<keysubst src="abc.txt" dest="def.txt" -keys="VERSION=1.0.3*DATE=2000-01-10" />
<keysubst src="abc.txt" dest="def.txt" + keys="VERSION=1.0.3*DATE=2000-01-10" />
Mkdir
@@ -1251,8 +1472,8 @@ necessary.Examples
--
<mkdir dir="${dist}" />+
<mkdir dir="${dist}/lib" />+
<mkdir dir="${dist}" />
<mkdir dir="${dist}/lib" />
Property
@@ -1310,9 +1531,9 @@ This also holds for properties loaded from a property file.Examples
--
<property name="foo.dist" value="dist"/>-
<property file="foo.properties" />+
<property resource="foo.properties" />+
<property name="foo.dist" value="dist"/>+
<property file="foo.properties" />
<property resource="foo.properties" />
Replace
@@ -1344,8 +1565,8 @@ the value attribute is omitted, it defaults to "".Examples
-+
<replace file="${src}/index.html" token="@@@" -value="wombat" />
<replace file="${src}/index.html" token="@@@" + value="wombat" />
Rmic
@@ -1371,8 +1592,8 @@ value="wombat" />Examples
-+
<rmic class="com.xyz.FooBar" -base="${build}/classes" />
<rmic class="com.xyz.FooBar" + base="${build}/classes" />
Taskdef
@@ -1403,15 +1624,15 @@ href="#writingowntask">Writing your own task".Examples
-+
<taskdef name="myjavadoc" value="com.mydomain.JavadocTask" -/>
<taskdef name="myjavadoc" value="com.mydomain.JavadocTask" + />
Tstamp
Description
-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".
+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 the init target.
Examples
-+
<tstamp/>
<tstamp/>
Zip
Description
Creates a zipfile.
The basedir attribute is the reference directory from where to zip.
-When "*" is used for items, all files in the basedir, and its -subdirectories, will be zipped. Otherwise all the files and directories +
It is possible to refine the set of files that are being zipped. This can be +done with the includes, excludes and defaultexcludes +attributes. With the includes attribute you specify the files you want to +have included by using patterns. The exclude 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. The patterns are +relative to the basedir directory.
+The includes, excludes and defaultexcludes attributes +replace the items and ignore attributes. The following explains +how the deprecated items and ignore attribute behave.
+When "*" is used for items, all files in the basedir, and +its subdirectories, will be zipped. Otherwise all the files and directories mentioned in the items list will zipped. When a directory is specified, then all files within it are also zipped.
-With the ignore attribute, you can specify names of files or -directories to ignore. These files will not be zipped. The items in the ignore -attribute override the items in the items attribute. The names specified -in the ignore attribute are just names, they do not contain any path -information!
+With the ignore attribute, you can specify files or directories to +ignore. These files will not be zipped. The items in the ignore attribute +override the items in the items attribute. The names specified in the ignore +attribute are just names, they do not contain any path information!
Parameters
@@ -1461,27 +1694,63 @@ information! items -a comma separated list of the files/directories to zip. -Yes +a comma separated list of the files/directories to zip. All + files are included when omitted. (deprecated, use includes + instead). +No + ignore -a comma separated list of the filenames/directorynames to - exclude from the zip. -No +comma separated list of filenames/directorynames to exclude + from the zip. No files (except default excludes) are excluded when + omitted. (deprecated, use excludes instead). +No ++ +includes +comma separated list of patterns of files that must be + included. All files are included 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 ++ defaultexcludes +indicates whether default excludes should be used or not + ("yes"/"no"). Default excludes are used when omitted. +No Examples
--+-
<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" -items="*" /><zip zipfile="${dist}/manual.zip" + basedir="htdocs/manual" + />zips all files in the
-htdocs/manualdirectory in a file calledmanual.zipin the${dist}directory.-+-
<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" -items="*" ignore="mydocs, todo.html"/><zip zipfile="${dist}/manual.zip" + basedir="htdocs/manual" + excludes="mydocs/**, **/todo.html" + />+zips all files in the
+htdocs/manualdirectory in a file calledmanual.zip+in the${dist}directory. Files in the directorymydocs, +or files with the nametodo.htmlare excluded.<zip zipfile="${dist}/manual.zip" + basedir="htdocs/manual" + includes="api/**/*.html" + excludes="**/todo.html" + />+zips all files in the
+htdocs/manualdirectory in a file calledmanual.zip+in the${dist}directory. Only html files under the directoryapi+are zipped, and files with the nametodo.htmlare excluded.Deprecated examples
+<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" items="*" />+zips all files in the
+htdocs/manualdirectory in a file calledmanual.zip+in the${dist}directory.<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" items="*" ignore="mydocs, todo.html"/>zips all files in the
@@ -1504,7 +1773,7 @@ it encounters for a specific task in the buildfile, before it executes is.htdocs/manualdirectory in a file calledmanual.zipin the${dist}directory. Files/directories with the namesmydocsandtodo.htmlare excluded.Let's write our own task, that prints a message on the System.out stream. The task has one attribute called "message".
-public class MyVeryOwnTask extends Task { +public class MyVeryOwnTask extends Task { private String msg; // The method executing the task @@ -1529,7 +1798,7 @@ task has one attribute called "message".Example
-<project name="TaskTest" default="test" basedir="."> +<project name="TaskTest" default="test" basedir="."> <target name="init"> <taskdef name="mytask" class="com.mydomain.MyVeryOwnTask"/> </target> @@ -1548,8 +1817,8 @@ package. Then you can use it as if it were a built in task.To provide feedback on this software, please subscribe to the Ant Development Mail List (ant-dev-subscribe@jakarta.apache.org)
-Copyright © 2000 Apache Software Foundation. All -rights Reserved.
+Copyright © 2000 Apache Software Foundation. All rights +Reserved.