Return-Path: Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm Delivered-To: mailing list ant-dev@jakarta.apache.org Received: (qmail 9126 invoked by uid 500); 27 Jan 2000 03:48:46 -0000 Delivered-To: apmail-jakarta-ant-cvs@jakarta.apache.org Received: (qmail 9115 invoked from network); 27 Jan 2000 03:48:46 -0000 Received: from taz.hyperreal.org (HELO hyperreal.org) (209.133.83.16) by 63.211.145.10 with SMTP; 27 Jan 2000 03:48:46 -0000 Received: (qmail 17030 invoked by uid 2016); 27 Jan 2000 03:48:28 -0000 Delivered-To: apcore-jakarta-ant-cvs@apache.org Received: (qmail 17020 invoked from network); 27 Jan 2000 03:48:28 -0000 Received: from unknown (HELO locus.apache.org) (63.211.145.10) by taz.hyperreal.org with SMTP; 27 Jan 2000 03:48:28 -0000 Received: (qmail 9094 invoked by uid 1010); 27 Jan 2000 03:48:27 -0000 Date: 27 Jan 2000 03:48:27 -0000 Message-ID: <20000127034827.9093.qmail@locus.apache.org> From: stefano@locus.apache.org To: jakarta-ant-cvs@apache.org Subject: cvs commit: jakarta-ant/docs index.html stefano 00/01/26 19:48:26 Modified: docs index.html Log: MUCH! improved documentation (also up-to-date with latest changes) Revision Changes Path 1.2 +1548 -44 jakarta-ant/docs/index.html Index: index.html =================================================================== RCS file: /home/cvs/jakarta-ant/docs/index.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- index.html 2000/01/13 10:42:41 1.1 +++ index.html 2000/01/27 03:48:26 1.2 @@ -1,51 +1,1555 @@ + -BuildTool Readme - + + + +Ant + + - -

BuildTool

-

BuildTool is a Java based build tool. In theory it is kind of like make without - makes wrinkles.

-

Why?

-

Why another build tool when there is already make, gnumake, nmake, jam, and - others? Because all of those tools have limitations that its original author - couldn't live with when developming software across multiple platforms. Make - like tools are inherently shell based. They evaluate a set of dependencies and - then execute commands not unlike what you would issue on a shell. This means - that you can easily extend these tools by using or writing any program for the - OS that you are working on. However, this also means that you limit yourself - to the OS, or at least the OS type such as Unix, that you are working on.

-

Makefiles are inherently evil as well. Anybody who has worked on them for any - time has run into the dreaded tab problem. "Is my command not executing - because I have a space in front of my tab!!!" said the original author - of BuildTool way too many times. Tools like Jam took care of this to a great - degree, but still use yet another format to use and remember.

-

BuildTool is different. Instead a model where it is extended with shell based - commands, it is extended using Java classes. Instead of writing shell commands, - the configuration files are XML based calling out a target tree where various - tasks get executed. Each task is run by an object which implments a particular - Task interface.

-

Granted, this removes some of the expressive power that is inherent by being - able to construct a shell command such as `find . -name foo -exec rm {}` but - it gives you the ability to be cross platform. To work anywhere and everywhere.And - hey, if you really need to execute a shell command, BuildTool has an exec rule - that allows different commands to be executed based on the OS that it is executing - on.

-

How?

-

To get started using BuildTool check out the following topics:

- -

License

-

Feedback

-

To provide feedback on this software, please send mail to duncan@x180.com.

+

Ant User Manual

+

by 

+ +

Version 1.0.2 - 2000/01/26

+
+

Table of Contents

+ +
+

Introduction

+

Ant is a Java based build tool. In theory it is kind of like make without +makes wrinkles.

+

Why?

+

Why another build tool when there is already make, gnumake, nmake, jam, and +others? Because all of those tools have limitations that its original author +couldn't live with when developing software across multiple platforms. Make like +tools are inherently shell based. They evaluate a set of dependencies and then +execute commands not unlike what you would issue on a shell. This means that you +can easily extend these tools by using or writing any program for the OS that +you are working on. However, this also means that you limit yourself to the OS, +or at least the OS type such as Unix, that you are working on.

+

Makefiles are inherently evil as well. Anybody who has worked on them for any +time has run into the dreaded tab problem. "Is my command not executing +because I have a space in front of my tab!!!" said the original author of +Ant way too many times. Tools like Jam took care of this to a great degree, but +still use yet another format to use and remember.

+

Ant is different. Instead a model where it is extended with shell based +commands, it is extended using Java classes. Instead of writing shell commands, +the configuration files are XML based calling out a target tree where various +tasks get executed. Each task is run by an object which implements a particular +Task interface.

+

Granted, this removes some of the expressive power that is inherent by being +able to construct a shell command such as `find . -name foo -exec rm {}` but it +gives you the ability to be cross platform. To work anywhere and everywhere. And +hey, if you really need to execute a shell command, Ant has an exec rule that +allows different commands to be executed based on the OS that it is executing +on.

+
+

Getting Ant

+

Binary edition

+

The latest stable version of Ant can be downloaded from http://jakarta.apache.org/builds/tomcat/release/v3.0/ant.zip. +If you like living on the edge, you can download the latest version from http://jakarta.apache.org/builds/tomcat/nightly/ant.zip.

+

Source edition

+

If you prefer the source edition, you can download Ant from http://jakarta.apache.org/builds/tomcat/release/v3.0/src/jakarta-tools.src.zip +(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.

+
+

Building Ant

+

Go to the directory jakarta-ant.

+

Make sure the JDK is in you path.

+

Run bootstrap.bat (Windows) or bootstrap.sh (UNIX) +to build a bootstrap version of Ant.

+

When finished, use

+
+

build.bat -Ddist.dir=<directory to install Ant> dist

+
+

for Windows, and

+
+

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.

+
+

Installing Ant

+

The binary distribution of Ant consists of three directories: bin, +docs and lib. Only the bin and lib +directory are crucial for running Ant. To run Ant, the following must be done:

+ +

Windows

+

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
+

Unix (bash)

+

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
+

Advanced

+

There are lots of variants that can be used to run Ant. What you need is at +least the following:

+

The classpath for Ant must contain ant.jar and xml.jar.

+

When you need JDK functionality (like a javac task, or a +rmic task), then for JDK 1.1, the classes.zip +file of the JDK must be added to the classpath; for JDK 1.2, tools.jar +must be added.

+

When you are executing platform specific applications (like the exec task, or the cvs task), the property ant.home +must be set to the directory containing a bin directory, which contains antRun.bat +(Windows) or antRun (Unix).

+
+

Running Ant

+

Running Ant is simple, when you installed it as described in the previous +section. Just type ant.

+

When nothing is specified, Ant looks for a build.xml file in the +current directory. When found, it uses that file as a buildfile. To make Ant use +another buildfile, use the commandline option -buildfile <file>, +where <file> is the buildfile you want to use.

+

You can also set properties which override properties specified in the +buildfile. This can be done with the -D<property>=<value> +option, where <property> is the name of the property and <value> +the value.

+

To more options are -quiet which instructs Ant to print less +information on the console when running. The option -verbose on the other +hand makes Ant print more information on the console.

+

It is also possible to specify the target that should be executed. Default +the target that is mentioned in the default attribute of the project is +used. This can be overridden by adding the target name to the end of the +commandline.

+

Commandline option summary:

+
ant [options] [target]
  +Options:
  +-help                  print this message
  +-quiet                 be extra quiet
  +-verbose               be extra verbose
  +-logfile <file>        use given file for log
  +-buildfile <file>      use given buildfile
  +-D<property>=<value>   use value for given property
+

Examples

+
+
ant
+
+

runs Ant using the build.xml file in the current directory, on +the default target.

+
+
ant -buildfile test.xml
+
+

runs Ant using the test.xml file in the current directory, on +the default target.

+
+
ant -buildfile test.xml dist
+
+

runs Ant using the test.xml file in the current directory, on a +target called dist.

+
+
ant -buildfile test.xml -Dbuild=build/classes dist
+
+

runs Ant using the test.xml file in the current directory, on a +target called dist. It also sets the build property to the +value build/classes.

+

Running Ant by hand

+

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
  +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.

+
+

Writing a simple buildfile

+

The buildfile is an written in XML. Each buildfile contains one project.

+

Projects

+

A project has three attributes:

+ + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
namethe name of the project.Yes
defaultthe default target to use when no target is supplied.Yes
basedirthe base directory from which all path calculations are + done. This attribute might be overridden by setting the "basedir" + property on forehand. When this is done, it might be ommitted in the + project tag.Yes
+

Each project defines one or more targets. A target is a set of tasks you want +to be executed. When starting Ant, you can select which target you want to have +executed. When no target is given, the project's default is used.

+

Targets

+

A target can depend on other targets. You might have a target for compiling, +for instance, and a target for creating a distributable. You can only build a +distributable when you have compiled first, so the distribute target depends on +the compile target. Ant resolves all these dependencies.

+

Ant tries to execute the targets in the depends attribute in the order +they appear (from left to right). Keep in mind that it is possible that a target +can get executed earlier when an earlier target depends on it:

+
<target name="A"/>
  +<target name="B" depends="A"/>
  +<target name="C" depends="B"/>
  +<target name="D" depends="C,B,A"/>
+

Suppose we want to execute target D. From its depends attribute, you +might think that first target C, then B and then A is executed. Wrong! C depends +on B, and B depends on A, so first A is executed, then B, then C, and finally D.

+

In situations without such dependencies, you can rely on the order of the +targets in the depends attributes.

+

A target gets executed only once. Even when more targets depend on it (see +the previous example).

+

A target has the following attributes:

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
namethe name of the project.Yes
dependsa comma separated list of names of targets on which this + target depends.No
+

Tasks

+

A task is a piece of code that can be executed.

+

A task can have multiple attributes (or arguments if you prefer). The value +of an attribute might contain references to a property. These references will be +resolved before the task is executed.

+

Tasks have a common structure:

+
+
<name attribute1="value1" attribute2="value2" ... />
+
+

where name is the name of the task, attribute-x the attribute name, and +value-x the value of this attribute.

+

There is a set of built in tasks, but it is also very +easy to write your own.

+

Properties

+

A project can have a set of properties. These might be set in the buildfile +by the property task, or might be set outside Ant. A +property has a name and a value. Properties might be used in in the value of +task attributes. This is done by placing the property name between +"${" and "}" in the attribute value.

+

If there is a property called "builddir" with the value +"build", then this could be used in an attribute like this: "${builddir}/classes". +This is resolved as "build/classes".

+

Examples

+
+
<project name="foo" default="dist" basedir=".">
  +  <target name="init">
  +    <tstamp/>
  +    <property name="build" value="build" />
  +    <property name="dist"  value="dist" />
  +  </target>
  +
  +  <target name="prepare" depends="init">
  +    <mkdir dir="${build}" />
  +  </target>
  +
  +  <target name="compile" depends="prepare">
  +    <javac srcdir="${src}" destdir="${build}" />
  +  </target>
  +
  +  <target name="dist" depends="compile">
  +    <mkdir dir="${dist}/lib" />
  +    <jar jarfile="${dist}/lib/foo${DSTAMP}.jar"
  +     basedir="${build}" items="com"/>
  +  </target>
  +
  +  <target name="clean" depends="init">
  +    <deltree dir="${build}" />
  +    <deltree dir="${dist}" />
  +  </target>
  +</project>
  +
+
+
+

Built in tasks

+ +
+

Ant

+

Description:

+

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).

+

Parameters:

+ + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
antfilethe buildfile to use.No
dirthe directory to use as a basedir for the new Ant project.Yes
targetthe target of the new Ant project that should be executed.No
+

Examples

+
+

<ant antfile="subproject/subbuild.xml" dir="subproject" +target="compile" />

+

<ant dir="subproject" />

+
+
+

Chmod

+

Description

+

Changes the permissions of a file. Right now it has efect only under Unix. +The permissions are also UNIX style, like the argument for the chmod command.

+

Parameters

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcthe file of which the permissions must be changed.Yes
permthe new permissions.Yes
+

Examples

+
+

<chmod src="${dist}/start.sh" perm="ugo+rx" +/>

+
+

makes the "start.sh" file readable and executable for anyone on a +UNIX system.

+
+

Copydir

+

Description

+

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!

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcthe directory to copy.Yes
destthe directory to copy to.Yes
ignorecomma separated list of filenames/directorynames to ignore.No
+

Examples

+
+

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

+
+

Copyfile

+

Description

+

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.

+

Parameters

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcthe filename of the file to copy.Yes
destthe filename of the file where to copy to.Yes
+

Examples

+
+

<copyfile src="test.java" dest="subdir/test.java" +/>

+

<copyfile src="${src}/index.html" dest="${dist}/help/index.html" +/>

+
+
+

Cvs

+

Description

+

Checks out a package/module from a CVS +repository.

+

When doing automated builds, the get task should be +preferred, because of speed.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
cvsRootthe CVSROOT variable.Yes
destthe directory where the checked out files should be placed.Yes
packagethe package/module to check out.Yes
tagthe tag of the package/module to check out.No
+

Examples

+
+

<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}".

+
+

Delete

+

Description

+

Deletes a single file.

+

Parameters

+ + + + + + + + + + + +
AttributeDescriptionRequired
filethe file to delete.Yes
+

Examples

+
+

<delete file="/lib/ant.jar" />

+

<delete file="${ant}" />

+
+
+

Deltree

+

Description

+

Deletes a directory with all its files and subdirectories.

+

Parameters

+ + + + + + + + + + + +
AttributeDescriptionRequired
dirthe directory to delete.Yes
+

Examples

+
+

<deltree dir="dist" />

+

<deltree dir="${dist}" />

+
-

Java is a trademark of Sun Microsystems.

+

Echo

+

Description

+

Echoes a message to System.out.

+

Parameters

+ + + + + + + + + + + +
AttributeDescriptionRequired
messagethe message to echo.Yes
+

Examples

+
+

<echo message="Hello world" />

+
+
+

Exec

+

Description

+

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.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
commandthe command to execute.Yes
dirthe directory in which the command should be executed.Yes
oslist of Operating Systems on which the command may be + executed.No
outputthe file to which the output of the command should be + redirected.Yes
+

Examples

+
+

<exec dir="${src}" command="dir" os="windows" +output="dir.txt" />

+
+
+

Expand

+

Description

+

Unzips a zipfile.

+

Parameters

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srczipfile to expand.Yes
destdirectory where to store the expanded files.Yes
+

Examples

+
+

<expand src="${tomcat_src}/tools-src.zip" dest="${tools.home}" +/>

+
+
+

Get

+

Description

+

Gets a file from an 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 significant slower than loading a compressed +archive with http/ftp.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcthe URL from which to retrieve a file.Yes
destthe file where to store the retrieved file.Yes
verboseshow verbose information ("on"/"off").No
+

Examples

+
+

<get src="http://jakarta.apache.org/" dest="help/index.html" +/>

+
+
+

GZip

+

Description

+

GZips a file.

+

Parameters

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcthe file to gzip.Yes
zipfilethe destination file.Yes
+

Examples

+
+

<gzip src="test.tar" zipfile="test.tar.gz" />

+
+
+

Jar

+

Description

+

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 +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 +ignore. These files will not be jarred. 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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
jarfilethe jar-file to create.Yes
basedirthe directory from which to jar the files.Yes
itemsa comma separated list of the files/directories to jar.Yes
ignorea comma separated list of the filenames/directorynames to + exclude from the jar.No
manifestthe manifest file to use.No
+

Examples

+
+

<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

+

Description

+

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.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
classthe Java class to execute.Yes
argsthe arguments for the class that is executed.No
forkif enabled triggers the class execution in another VM + (disabled by default)No
jvmargsthe arguments to pass to the forked VM (ignored if fork is + disabled)No
+

Examples

+
+

<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" +/>

+
+
+

Javac

+

Description

+

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.

+

Files in the source tree, that are no java files, are copied to the +destination directory, allowing support files to be located properly in the +classpath.

+

The directory structure of the source tree should follow the package +hierarchy.

+

It is possible to use different compilers. This can be selected with the +"build.compiler" property. There are three choices:

+ +

For JDK 1.1/1.2 is classic the default. For JDK 1.3 is modern the default.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcdirlocation of the java files.Yes
destdirlocation where to store the class files.Yes
classpaththe classpath to use.No
bootclasspathlocation of bootstrap class files.No
extdirslocation of installed extensions.No
debugindicates whether there should be compiled with debug + information ("on").No
optimizeindicates whether there should be compiled with + optimization ("on").No
deprecationindicates whether there should be compiled with deprecation + information ("on").No
+

Examples

+
+

<javac srcdir="${src}" destdir="${build}" -classpath="xyz.jar" +-debug="on" />

+
+
+

Javadoc/Javadoc2

+

Description

+

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.

+

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(), we cannot run javadoc inside the +same VM without breaking functionality. For this reason, this task always forks +the VM. But this is not a performance penalty since javadoc is normally a heavy +application and must be called just once.

+

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.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionAvailabilityRequired
sourcepathSpecify where to find source filesallyes
destdirDestination directory for output filesallyes
sourcefilesSpace separated list of source filesallat least one of the two
packagenamesSpace separated list of package files (with terminating + wildcard)all
ClasspathSpecify where to find user class filesallno
BootclasspathOverride location of class files loaded by the bootstrap class loader1.2no
ExtdirsOverride location of installed extensions1.2no
OverviewRead overview documentation from HTML file1.2no
PublicShow only public classes and membersallno
ProtectedShow protected/public classes and members (default)allno
PackageShow package/protected/public classes and membersallno
PrivateShow all classes and membersallno
OldGenerate output using JDK 1.1 emulating doclet1.2no
VerboseOutput messages about what Javadoc is doing1.2no
LocaleLocale to be used, e.g. en_US or en_US_WIN1.2no
EncodingSource file encoding nameallno
VersionInclude @version paragraphsallno
UseCreate class and package usage pages1.2no
AuthorInclude @author paragraphsallno
Splitindex Split index into one file per letter1.2no
WindowtitleBrowser window title for the documenation (text)1.2no
Doctitle Include title for the package index(first) page + (html-code)1.2no
Header Include header text for each page (html-code)1.2no
Footer Include footer text for each page (html-code)1.2no
bottom Include bottom text for each page (html-code)1.2no
link Create links to javadoc output at the given + URL1.2no
linkoffline Link to docs at <url> using package list at <url2>1.2no
group Group specified packages together in overview page1.2no
nodeprecated Do not include @deprecated informationallno
nodeprecatedlist Do not generate deprecated list1.2no
notree Do not generate class hierarchyallno
noindex Do not generate indexallno
nohelp Do not generate help link1.2no
nonavbar Do not generate navigation bar1.2no
serialwarn Generate warning about @serial tag1.2no
helpfileSpecifies the HTML help file to use1.2no
stylesheetfileSpecifies the CSS stylesheet to use1.2no
charset Charset for cross-platform viewing of generated documentation1.2no
docencodingOutput file encoding name1.1no
+

Examples

+
+
<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 &#169; 2000 Dummy Corp. All Rights Reserved.</i>"
  +/>
+
+
+

KeySubst

+

Description

+

Performs keyword substitution in the source file, and writes the result to +the destination file.

+

Keys in the source file are of the form ${keyname}. The keys attribute +contains key/value pairs. When a key is found in the keys attribute, then +"${keyname}" is replaced by the corresponding value.

+

The keys attribute is of the form +"name1=value1*name2=value2*name3=value3". The '*' is called the +separator, which might we changed with the sep attribute.

+

Note: the source file and destination file may not be the same.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcthe source file.Yes
destthe destination file.Yes
septhe separator for the name/value pairs.No
keysname/value pairs for replacement.Yes
+

Examples

+
+

<keysubst src="abc.txt" dest="def.txt" +keys="VERSION=1.0.3*DATE=2000-01-10" />

+
+
+

Mkdir

+

Description

+

Creates a directory. Also non-existent parent directories are created, when +necessary.

+

Parameters

+ + + + + + + + + + + +
AttributeDescriptionRequired
dirthe directory to create.Yes
+

Examples

+
+

<mkdir dir="${dist}" />

+

<mkdir dir="${dist}/lib" />

+
+
+

Property

+

Description

+

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 three 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.

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
namethe name of the property to set.No
valuethe value of the property.No
resourcethe resource name of the property file.No
filethe filename of the property file .No
+

Examples

+
+

<property name="foo.dist" value="dist"/>

+

<property file="foo.properties" />

+

<property resource="foo.properties" />

+
+
+

Replace

+

Description

+

Replaces the occurrence of a given string with another string in a file. When +the value attribute is omitted, it defaults to "".

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
filefile for which the token should be replacedYes
tokenthe token which must be replacedYes
valuethe new value for the tokenNo
+

Examples

+
+

<replace file="${src}/index.html" token="@@@" +value="wombat" />

+
+
+

Rmic

+

Description

+

Runs the rmic compiler for a certain class.

+

Parameters

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
basethe location to store the compiled files.Yes
classthe class for which to run rmic.Yes
+

Examples

+
+

<rmic class="com.xyz.FooBar" +base="${build}/classes" />

+
+
+

Taskdef

+

Description

+

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".

+

Parameters

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
namethe name of the taskYes
classthe full class name implementing the taskYes
+

Examples

+
+

<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".

+

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.

+

Parameters

+ + + + + + +
AttributeDescriptionRequired
+

Examples

+
+

<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 +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!

+

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
zipfilethe zip-file to create.Yes
basedirthe directory from which to zip the files.Yes
itemsa comma separated list of the files/directories to zip.Yes
ignorea comma separated list of the filenames/directorynames to + exclude from the zip.No
+

Examples

+
+

<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" +items="*" />

+
+

zips all files in the htdocs/manual directory in a file called manual.zip +in the ${dist} directory.

+
+

<zip zipfile="${dist}/manual.zip" basedir="htdocs/manual" +items="*" ignore="mydocs, todo.html"/>

+
+

zips all files in the htdocs/manual directory in a file called manual.zip +in the ${dist} directory. Files/directories with the names mydocs +and todo.html are excluded.

+
+

Writing your own task

+

It is very easy to write your own task:

+
    +
  1. Create a Java class that extends org.apache.tools.ant.Task.
    2. +
  2. For each attribute, write a setter method. The setter method must be a public + void method that takes one String as an argument. The + name of the method must begin with "set", followed by the + attribute name, with the first character in uppercase, and the rest in + lowercase.
    3. +
  3. Write a public void execute method, with no arguments, that + throws a BuildException. This method implements the task + itself.
    4. +
+

It is important to know that Ant first calls the setters for the attributes +it encounters for a specific task in the buildfile, before it executes is.

+

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 {
  +  private String msg;
  +
  +  // The method executing the task
  +  public void execute() throws BuildException {
  +    System.out.println(message);
  +  }
  +
  +  // 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:

+
    +
  1. Make sure the class that implements your task is in the classpath when + starting Ant.
    2. +
  2. In the init target, add a taskdef task. This actually adds + your task to the system.
    3. +
  3. Use your task in the rest of the buildfile.
    4. +
+

Example

+
+
<project name="TaskTest" default="test" basedir=".">
  +  <target name="init">
  +    <taskdef name="mytask" class="com.mydomain.MyVeryOwnTask"/>
  +  </target>
  +
  +  <target name="test">
  +    <mytask myattr="wombat" />
  +  </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.

+
+

Feedback

+

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.

+ +