- <html>
-
- <head>
- <meta http-equiv="Content-Language" content="en-us">
- <title>Ant</title>
- </head>
-
- <body>
-
- <h1>Ant User Manual</h1>
- <p>by</p>
- <!-- Names are in alphabetical order, on last name -->
- <ul>
- <li>James Duncan Davison (<a href="mailto:duncan@x180.com">duncan@x180.com</a>)</li>
- <li>Tom Dimock (<a href="mailto:tad1@cornell.edu">tad1@cornell.edu</a>)</li>
- <li>Arnout J. Kuiper (<a href="mailto:ajkuiper@wxs.nl">ajkuiper@wxs.nl</a>)</li>
- <li>Stefano Mazzocchi (<a href="mailto:stefano@apache.org">stefano@apache.org</a>)</li>
- <li>Sam Ruby (<a href="mailto:rubys@us.ibm.com">rubys@us.ibm.com</a>)</li>
- </ul>
-
- <p>Version 1.0.8.1 - 2000/06/13</p>
-
- <hr>
- <h2>Table of Contents</h2>
- <ul>
- <li><a href="#introduction">Introduction</a></li>
- <li><a href="#getting">Getting Ant</a></li>
- <li><a href="#buildingant">Building Ant</a></li>
- <li><a href="#installing">Installing Ant</a></li>
- <li><a href="#running">Running Ant</a></li>
- <li><a href="#buildfile">Writing a simple buildfile</a>
- <li><a href="#directorybasedtasks">Directory based tasks</a></li>
- <li><a href="#tasks">Built in Tasks</a>
- <li><a href="#optionaltasks">Optional Tasks</a>
- <li><a href="#writingowntask">Writing your own task</a></li>
- <li><a href="#license">License</a></li>
- <li><a href="#feedback">Feedback</a></li>
- </ul>
- <hr>
- <h2><a name="introduction">Introduction</a></h2>
- <p>Ant is a Java based build tool. In theory it is kind of like make without
- make's wrinkles.</p>
- <h3>Why?</h3>
- <p>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.</p>
- <p>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.</p>
- <p>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.</p>
- <p>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.</p>
- <hr>
- <h2><a name="getting">Getting Ant</a></h2>
- <h3>Binary edition</h3>
- <p>The latest stable version of Ant can be downloaded from <a
- href="http://jakarta.apache.org/builds/tomcat/release/v3.0/ant.zip">http://jakarta.apache.org/builds/tomcat/release/v3.0/ant.zip</a>.
- If you like living on the edge, you can download the latest version from <a
- href="http://jakarta.apache.org/builds/tomcat/nightly/ant.zip">http://jakarta.apache.org/builds/tomcat/nightly/ant.zip</a>.</p>
- <h3>Source edition</h3>
- <p>If you prefer the source edition, you can download Ant from <a
- href="http://jakarta.apache.org/builds/tomcat/release/v3.0/src/jakarta-tools.src.zip">http://jakarta.apache.org/builds/tomcat/release/v3.0/src/jakarta-tools.src.zip</a>
- (latest stable) or from <a
- href="http://jakarta.apache.org/from-cvs/jakarta-tools/">http://jakarta.apache.org/from-cvs/jakarta-ant/</a>
- (current). See the section <a href="#buildingant">Building Ant</a> on how to
- build Ant from the source code.</p>
- <hr>
- <h2><a name="buildingant">Building Ant</a></h2>
- <p>
- Download and install the Java API for XML Parsing kit from
- <a href="http://java.sun.com/xml">http://java.sun.com/xml</a>.
- Make sure the "jaxp.jar" and "parser.jar" files are in your class
- path.
- </p>
- <p>Go to the directory <code>jakarta-ant</code>.</p>
- <p>Make sure the JDK is in you path.</p>
- <p>Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
- to build a bootstrap version of Ant.</p>
- <p>When finished, use</p>
- <blockquote>
- <p><code>build.bat -Dant.dist.dir=<directory to install Ant> dist</code></p>
- </blockquote>
- <p>for Windows, and</p>
- <blockquote>
- <p><code>build.sh -Dant.dist.dir=<directory to install Ant> dist</code></p>
- </blockquote>
- <p>for UNIX, to create a binary distribution of Ant. This distribution can be
- found in the directory you specified.</p>
- <hr>
- <h2><a name="installing">Installing Ant</a></h2>
- <p>The binary distribution of Ant consists of three directories: <code>bin</code>,
- <code>docs</code> and <code>lib</code>. Only the <code>bin</code> and <code>lib</code>
- directory are crucial for running Ant. To run Ant, the following must be done:</p>
- <ul>
- <li>Add the <code>bin</code> directory to your path.</li>
- <li>Set the ANT_HOME environment variable. This should be set to the directory
- which contains the <code>bin</code> and <code>lib</code> directory.</li>
- <li>Set the JAVA_HOME environment variable. This should be set to the
- directory where the JDK is installed.</li>
- </ul>
- <h3>Windows</h3>
- <p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the
- environment:</p>
- <pre>set ANT_HOME=c:\ant
- set JAVA_HOME=c:\jdk1.2.2
- set PATH=%PATH%;%ANT_HOME%\bin</pre>
- <h3>Unix (bash)</h3>
- <p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up
- the environment:</p>
- <pre>export ANT_HOME=/usr/local/ant
- export JAVA_HOME=/usr/local/jdk-1.2.2
- export PATH=${PATH}:${ANT_HOME}/bin</pre>
- <h3>Advanced</h3>
- <p>There are lots of variants that can be used to run Ant. What you need is at
- least the following:</p>
- <p>The classpath for Ant must contain <code>ant.jar</code> and <code>xml.jar</code>.</p>
- <p>When you need JDK functionality (like a <a href="#javac">javac</a> task, or a
- <a href="#rmic">rmic</a> task), then for JDK 1.1, the <code>classes.zip</code>
- file of the JDK must be added to the classpath; for JDK 1.2, <code>tools.jar</code>
- must be added.</p>
- <p>When you are executing platform specific applications (like the <a
- href="#exec">exec</a> task, or the <a href="#cvs">cvs</a> task), the property <code>ant.home</code>
- must be set to the directory containing a bin directory, which contains the <code>antRun</code> shell script necessary to run execs on Unix.</p>
- <hr>
- <h2><a name="running">Running Ant</a></h2>
- <p>Running Ant is simple, when you installed it as described in the previous
- section. Just type <code>ant</code>.</p>
- <p>When nothing is specified, Ant looks for a <code>build.xml</code> file in the
- current directory. When found, it uses that file as a buildfile. To make Ant use
- another buildfile, use the commandline option <i>-buildfile <file></i>,
- where <i><file></i> is the buildfile you want to use.</p>
- <p>You can also set properties which override properties specified in the
- buildfile. This can be done with the <i>-D<property>=<value></i>
- option, where <i><property></i> is the name of the property and <i><value></i>
- the value.</p>
- <p>To more options are <i>-quiet</i> which instructs Ant to print less
- information on the console when running. The option <i>-verbose</i> on the other
- hand makes Ant print more information on the console.</p>
- <p>It is also possible to specify the target that should be executed. Default
- the target that is mentioned in the <i>default</i> attribute of the project is
- used. This can be overridden by adding the target name to the end of the
- commandline.</p>
- <p>Commandline option summary:</p>
- <pre>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</pre>
- <h3>Examples</h3>
- <blockquote>
- <pre>ant</pre>
- </blockquote>
- <p>runs Ant using the <code>build.xml</code> file in the current directory, on
- the default target.</p>
- <blockquote>
- <pre>ant -buildfile test.xml</pre>
- </blockquote>
- <p>runs Ant using the <code>test.xml</code> file in the current directory, on
- the default target.</p>
- <blockquote>
- <pre>ant -buildfile test.xml dist</pre>
- </blockquote>
- <p>runs Ant using the <code>test.xml</code> file in the current directory, on a
- target called <code>dist</code>.</p>
- <blockquote>
- <pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre>
- </blockquote>
- <p>runs Ant using the <code>test.xml</code> file in the current directory, on a
- target called <code>dist</code>. It also sets the <i>build</i> property to the
- value <i>build/classes</i>.</p>
- <h3>Running Ant by hand</h3>
- <p>When you have installed Ant in the do-it-yourself way, Ant can be started
- with:</p>
- <blockquote>
- <pre>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]</pre>
- </blockquote>
- <p>These instructions actually do exactly the same as the <code>ant</code>
- command. The options and target are the same as when running Ant with the <code>ant</code>
- command.</p>
- <hr>
- <h2><a name="buildfile">Writing a simple buildfile</a></h2>
- <p>The buildfile is written in XML. Each buildfile contains one project.</p>
- <h3>Projects</h3>
- <p>A project has three attributes:</p>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">name</td>
- <td valign="top">the name of the project.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">default</td>
- <td valign="top">the default target to use when no target is supplied.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">basedir</td>
- <td valign="top">the base directory from which all path calculations are
- done. This attribute might be overridden by setting the "basedir"
- property on forehand. When this is done, it might be ommitted in the
- project tag.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <p>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.</p>
- <h3>Targets</h3>
- <p>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.</p>
- <p>Ant tries to execute the targets in the <i>depends</i> 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:</p>
- <blockquote>
- <pre><target name="A"/>
- <target name="B" depends="A"/>
- <target name="C" depends="B"/>
- <target name="D" depends="C,B,A"/></pre>
- </blockquote>
- <p>Suppose we want to execute target D. From its <i>depends</i> 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.</p>
- <p>A target gets executed only once. Even when more targets depend on it (see
- the previous example).</p>
- <p>A target has also the ability to perform its execution if a property has been
- set. This allows, for example, better control on the building process depending
- on the state of the system (java version, OS, command line properties, etc...).
- To make target <i>sense</i> this property you should add the <i>if</i> attribute
- with the name of the property that the target should react to, for example</p>
- <blockquote>
- <pre><target name="build-module-A" if="module-A-present"/></pre>
- </blockquote>
- <p>If no <i>if</i> attribute is present, the target will always be executed.</p>
- <p>It is a good practice to place your <a href="#property">property</a> and <a
- href="#tstamp">tstamp</a> tasks in a so called initialization target, on which
- all other targets depend. Make sure that 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".</p>
- <p>A target has the following attributes:</p>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">name</td>
- <td valign="top">the name of the project.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">depends</td>
- <td valign="top">a comma separated list of names of targets on which this
- target depends.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">if</td>
- <td valign="top">the name of the property that must be set in order for this
- target to execute.</td>
- <td align="center" valign="top">No</td>
- </tr>
- </table>
- <h3>Tasks</h3>
- <p>A task is a piece of code that can be executed.</p>
- <p>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.</p>
- <p>Tasks have a common structure:</p>
- <blockquote>
- <pre><name attribute1="value1" attribute2="value2" ... /></pre>
- </blockquote>
- <p>where name is the name of the task, attribute-x the attribute name, and
- value-x the value of this attribute.</p>
- <p>There is a set of <a href="#tasks">built in tasks</a>, but it is also very
- easy to <a href="#writingowntask">write your own</a>.</p>
- <h3>Properties</h3>
- <p>A project can have a set of properties. These might be set in the buildfile
- by the <a href="#property">property task</a>, 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.</p>
- <p>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".</p>
- <h3>Token Filters</h3>
- <p>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 <a href="#filter">filter task</a>. </p>
- <p>Since this can be a very harmful behavior, the tokens in the files <b>must</b>
- be of the form<i> @token@</i> where <i>token</i> is the token name that is set
- in the filter task. This token syntax matches the syntax of other build systems
- that perform such filtering and remains sufficiently orthogonal to most
- programming and scripting languages, as well with documentation systems.</p>
- <p>Note: in case a token with the format @token@ if found in a file but no
- filter is associated with that token, no changes take place. So, no escaping
- method is present, but as long as you choose appropriate names for your tokens,
- this should not cause problems.</p>
- <h3>Examples</h3>
- <blockquote>
- <pre><project name="foo" default="dist" basedir=".">
- <target name="init">
- <tstamp/>
- <property name="build" value="build" />
- <property name="dist" value="dist" />
- <filter token="version" value="1.0.3" />
- <filter token="year" value="2000" />
- </target>
-
- <target name="prepare" depends="init">
- <mkdir dir="${build}" />
- </target>
-
- <target name="compile" depends="prepare">
- <javac srcdir="${src}" destdir="${build}" filtering="on"/>
- </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>
- </pre>
- </blockquote>
- <hr>
- <h2><a name="directorybasedtasks">Directory based tasks</a></h2>
- <p>Some tasks use directory trees for the task they perform. For instance, the <a
- href="#javac">Javac task</a> 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.</p>
- <p>Ant gives you two ways to create a subset, which both can be used at the same
- time:</p>
- <ul>
- <li>Only include files/directories that match at least one pattern of a set of
- patterns</li>
- <li>Exclude files/directories that match at least one pattern a set of
- patterns</li>
- </ul>
- <p>When both inclusion and exclusion are used, only files/directories that match
- the include patterns, and don't match the exclude patterns are used.</p>
- <h3>Patterns</h3>
- <p>As described earlier, patterns are used for the inclusion and exclusion.
- These patterns look very much like the patterns used in DOS and UNIX:</p>
- <p>'*' matches zero or more characters, '?' matches one character.</p>
- <p>Examples:</p>
- <p>'*.java' matches '.java', 'x.java' and 'FooBar.java', but not 'FooBar.xml'
- (does not end with '.java').</p>
- <p>'?.java' matches 'x.java', 'A.java', but not '.java' or 'xyz.java' (both
- don't have one character before '.java').</p>
- <p>Combinations of '*'s and '?'s are allowed.</p>
- <p>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.</p>
- <p>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'.</p>
- <p>There is one "shorthand", if a pattern ends with '/' or '\', then '**'
- is appended. E.g. "mypackage/test/" is interpreted as were it "mypackage/test/**".</p>
- <p>Examples:</p>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top">**/CVS/*</td>
- <td valign="top">Matches all files in CVS directories, that can be located
- anywhere in the directory tree.
- <p>Matches:</p>
- <p>CVS/Repository<br>
- org/apache/CVS/Entries<br>
- org/apache/jakarta/tools/ant/CVS/Entries</p>
- <p>But not:</p>
- <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>
- </tr>
- <tr>
- <td valign="top">org/apache/jakarta/**</td>
- <td valign="top">Matches all files in the org/apache/jakarta directory tree.
- <p>Matches:</p>
- <p>org/apache/jakarta/tools/ant/docs/index.html<br>
- org/apache/jakarta/test.xml</p>
- <p>But not:</p>
- <p>org/apache/xyz.java ('jakarta'/' part is missing)</td>
- </tr>
- <tr>
- <td valign="top">org/apache/**/CVS/*</td>
- <td valign="top">Matches all files in CVS directories, that are located
- anywhere in the directory tree under org/apache.
- <p>Matches:</p>
- <p>org/apache/CVS/Entries<br>
- org/apache/jakarta/tools/ant/CVS/Entries</p>
- <p>But not:</p>
- <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>
- </tr>
- <tr>
- <td valign="top">**/test/**</td>
- <td valign="top">Matches all files which have a directory 'test' in their
- path, including 'test' as a filename.</td>
- </tr>
- </table>
- <p>When these patterns are used in inclusion and exclusion, you have a powerful
- way to select just the files you want.</p>
- <h3>Examples</h3>
- <pre> <copydir src="${src}"
- dest="${dist}"
- includes="**/images/*"
- excludes="**/*.gif" /></pre>
- <p>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.</p>
- <h3>Default Excludes</h3>
- <p>There are a set of definitions which are excluded by default from all directory based tasks.
- They are:
- <pre> "**/*~",
- "**/#*#",
- "**/%*%",
- "**/CVS",
- "**/CVS/*",
- "**/.cvsignore"
- </pre>
- If you do not want these default excludes applied, you may disable them with the
- <code>defaultexcludes="no"</code> attribute.</p>
- <hr>
- <h2><a name="tasks">Built in tasks</a></h2>
- <ul>
- <li><a href="#ant">Ant</a></li>
- <li><a href="#available">Available</a></li>
- <li><a href="#chmod">Chmod</a></li>
- <li><a href="#copydir">Copydir</a></li>
- <li><a href="#copyfile">Copyfile</a></li>
- <li><a href="#cvs">Cvs</a></li>
- <li><a href="#delete">Delete</a></li>
- <li><a href="#deltree">Deltree</a></li>
- <li><a href="#echo">Echo</a></li>
- <li><a href="#exec">Exec</a></li>
- <li><a href="#expand">Expand</a></li>
- <li><a href="#filter">Filter</a></li>
- <li><a href="#get">Get</a></li>
- <li><a href="#gunzip">GUnzip</a></li>
- <li><a href="#gzip">GZip</a></li>
- <li><a href="#fixcrlf">FixCRLF</a></li>
- <li><a href="#jar">Jar</a></li>
- <li><a href="#java">Java</a></li>
- <li><a href="#javac">Javac</a></li>
- <li><a href="#javadoc">Javadoc/Javadoc2</a></li>
- <li><a href="#keysubst">KeySubst</a></li>
- <li><a href="#mkdir">Mkdir</a></li>
- <li><a href="#property">Property</a></li>
- <li><a href="#rename">Rename</a></li>
- <li><a href="#replace">Replace</a></li>
- <li><a href="#rmic">Rmic</a></li>
- <li><a href="#tar">Tar</a></li>
- <li><a href="#taskdef">Taskdef</a></li>
- <li><a href="#tstamp">Tstamp</a></li>
- <li><a href="#untar">Untar</a></li>
- <li><a href="#zip">Zip</a></li>
- </ul>
- <hr>
- <h2><a name="ant">Ant</a></h2>
- <h3><b>Description:</b></h3>
- <p>Runs Ant on a supplied buildfile. This can be used to build subprojects.</p>
- <p>When the <i>antfile</i> attribute is omitted, the file "build.xml"
- in the supplied directory (<i>dir</i> attribute) is used.</p>
- <p>If no target attribute is supplied, the default target of the new project is
- used.</p>
- <p>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 <a href="#property">properties task</a>).</p>
- <h3>Parameters:</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">antfile</td>
- <td valign="top">the buildfile to use.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">dir</td>
- <td valign="top">the directory to use as a basedir for the new Ant project.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">target</td>
- <td valign="top">the target of the new Ant project that should be executed.</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><ant antfile="subproject/subbuild.xml" dir="subproject"
- target="compile" /></code></p>
- <p><code><ant dir="subproject" /></code></p>
- </blockquote>
- <hr>
- <h2><a name="available">Available</a></h2>
- <h3>Description</h3>
- <p>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.</p>
- <p>The value part of the properties being set is <i>true</i> if the resource is
- present, otherwise, the property is not set.</p>
- <p>Normally, this task is used to set properties that are useful to avoid target
- execution depending on system parameters.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">property</td>
- <td valign="top">the name of the property to set.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">classname</td>
- <td valign="top">the class to look for in classpath.</td>
- <td valign="middle" align="center" rowspan="3">Yes</td>
- </tr>
- <tr>
- <td valign="top">resource</td>
- <td valign="top">the resource to look for in the JVM</td>
- </tr>
- <tr>
- <td valign="top">file</td>
- <td valign="top">the file to look for.</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <available classname="org.whatever.Myclass" property="Myclass.present" /></pre>
- <p>sets the property <code><i>Myclass.present</i></code> to the value "true"
- if the <i>org.whatever.Myclass</i> is found in Ant's classpath.</p>
- <hr>
- <h2><a name="chmod">Chmod</a></h2>
- <h3>Description</h3>
- <p>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.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">the file of which the permissions must be changed.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">perm</td>
- <td valign="top">the new permissions.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><chmod src="${dist}/start.sh" perm="ugo+rx"
- /></code></p>
- </blockquote>
- <p>makes the "start.sh" file readable and executable for anyone on a
- UNIX system.</p>
- <hr>
- <h2><a name="copydir">Copydir</a></h2>
- <h3>Description</h3>
- <p>Copies a directory tree from the source to the destination.</p>
- <p>It is possible to refine the set of files that are being copied. This can be
- done with the <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i>
- attributes. With the <i>includes</i> attribute you specify the files you want to
- have included by using patterns. The <i>exclude</i> attribute is used to specify
- the files you want to have excluded. This is also done with patterns. And
- finally with the <i>defaultexcludes</i> attribute, you can specify whether you
- want to use default exclusions or not. See the section on <a
- href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The patterns are
- relative to the <i>src</i> directory.</p>
- <p>The <i>ignore</i> attribute contains the names of the files/directories that
- must be excluded from the copy. The names specified in the <i>ignore</i>
- attribute are just names, they do not contain any path information! Note that
- this attribute has been replaced by the <i>excludes</i> attribute.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">the directory to copy.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">the directory to copy to.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">ignore</td>
- <td valign="top">comma separated list of filenames/directorynames to ignore.
- No files (except default excludes) are excluded when omitted. (<b>deprecated</b>,
- use <i>excludes</i> instead).</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">filtering</td>
- <td valign="top">indicates whether token filtering should take place during
- the copy</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <copydir src="${src}/resources"
- dest="${dist}"
- /></pre>
- <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>.</p>
- <pre> <copydir src="${src}/resources"
- dest="${dist}"
- includes="**/*.java"
- excludes="**/Test.java"
- /></pre>
- <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>
- recursively. All java files are copied, except for files with the name <code>Test.java</code>.</p>
- <pre> <copydir src="${src}/resources"
- dest="${dist}"
- includes="**/*.java"
- excludes="mypackage/test/**" /></pre>
- <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>
- recursively. All java files are copied, except for the files under the <code>mypackage/test</code>
- directory.</p>
- <hr>
- <h2><a name="copyfile">Copyfile</a></h2>
- <h3>Description</h3>
- <p>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.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">the filename of the file to copy.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">the filename of the file where to copy to.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">filtering</td>
- <td valign="top">indicates whether token filtering should take place during
- the copy</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><copyfile src="test.java" dest="subdir/test.java"
- /></code></p>
- <p><code><copyfile src="${src}/index.html" dest="${dist}/help/index.html"
- /></code></p>
- </blockquote>
- <hr>
- <h2><a name="cvs">Cvs</a></h2>
- <h3>Description</h3>
- <p>Handles packages/modules retrieved from a
- <a href="http://www.cyclic.com/">CVS</a> repository.</p>
- <p>When doing automated builds, the <a href="#get">get task</a> should be
- preferred over the <i>checkout</i> command, because of speed.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">command</td>
- <td valign="top">the CVS command to execute.</td>
- <td align="center" valign="top">No, default "checkout"</td>
- </tr>
- <tr>
- <td valign="top">cvsRoot</td>
- <td valign="top">the CVSROOT variable.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">the directory where the checked out files should be placed.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">package</td>
- <td valign="top">the package/module to check out.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">tag</td>
- <td valign="top">the tag of the package/module to check out.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">quiet</td>
- <td valign="top">supress informational messages.</td>
- <td align="center" valign="top">No, default "false"</td>
- </tr>
- <tr>
- <td valign="top">noexec</td>
- <td valign="top">report only, don't change any files.</td>
- <td align="center" valign="top">No, default "false"</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <cvs cvsRoot=":pserver:anoncvs@jakarta.apache.org:/home/cvspublic"
- package="jakarta-tools"
- dest="${ws.dir}"
- /></pre>
- <p>checks out the package/module "jakarta-tools" from the CVS
- repository pointed to by the cvsRoot attribute, and stores the files in "${ws.dir}".</p>
- <pre> <cvs dest="${ws.dir}" command="update" /></pre>
- <p>updates the package/module that has previously been checked out into
- "${ws.dir}".</p>
- <hr>
- <h2><a name="delete">Delete</a></h2>
- <h3>Description</h3>
- <p>Deletes either a single file or
- all files in a specified directory and its sub-directories.</p>
- <p>It is possible to refine the set of files that are being deleted. This can be
- done with the <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i>
- attributes. With the <i>includes</i> attribute you specify the files you want to
- have included in the deletion process by using patterns. The <i>exclude</i> attribute is used to specify
- the files you want to have excluded from the deletion process. This is also done with patterns. And
- finally with the <i>defaultexcludes</i> attribute, you can specify whether you
- want to use default exclusions or not. See the section on <a
- href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The patterns are
- relative to the <i>dir</i> directory.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">file</td>
- <td valign="top">The file to delete.</td>
- <td align="center" valign="middle" rowspan="2">at least one of the two</td>
- </tr>
- <tr>
- <td valign="top">dir</td>
- <td valign="top">The directory to delete files from.</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">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.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">Comma separated list of patterns of files that must be
- excluded from the deletion list. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">Indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">verbose</td>
- <td valign="top">Show name of each deleted file ("true"/"false"). Default is "false" when omitted.</td>
- <td align="center" valign="top">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <delete file="/lib/ant.jar" /></pre>
- <p>deletes the file <code>/lib/ant.jar</code>.</p>
- <pre> <delete dir="lib" /></pre>
- <p>deletes all files in the <code>/lib</code> directory.</p>
- <pre> <delete dir="."
- include="**/*.bak"
- />
- </pre>
- <p>deletes all files with the extension "<code>.bak</code>" from the current directory
- and any sub-directories.</p>
- <h2><a name="deltree">Deltree</a></h2>
- <h3>Description</h3>
- <p>Deletes a directory with all its files and subdirectories.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">dir</td>
- <td valign="top">the directory to delete.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <deltree dir="dist" /></pre>
- <p>deletes the directory <code>dist</code>, including its files and
- subdirectories.</p>
- <pre> <deltree dir="${dist}" /></pre>
- <p>deletes the directory <code>${dist}</code>, including its files and
- subdirectories.</p>
- <hr>
- <h2><a name="echo">Echo</a></h2>
- <h3>Description</h3>
- <p>Echoes a message to System.out.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">message</td>
- <td valign="top">the message to echo.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <echo message="Hello world" /></pre>
- <hr>
- <h2><a name="exec">Exec</a></h2>
- <h3>Description</h3>
- <p>Executes a system command. When the <i>os</i> attribute is specified, then
- the command is only executed when Ant is run on one of the specified operating
- systems.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">command</td>
- <td valign="top">the command to execute.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">dir</td>
- <td valign="top">the directory in which the command should be executed.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">os</td>
- <td valign="top">list of Operating Systems on which the command may be
- executed.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">output</td>
- <td valign="top">the file to which the output of the command should be
- redirected.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><exec dir="${src}" command="dir" os="windows"
- output="dir.txt" /></code></p>
- </blockquote>
- <hr>
- <h2><a name="expand">Expand</a></h2>
- <h3>Description</h3>
- <p>Unzips a zipfile.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">zipfile to expand.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">directory where to store the expanded files.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><expand src="${tomcat_src}/tools-src.zip" dest="${tools.home}"
- /></code></p>
- </blockquote>
- <hr>
- <h2><a name="filter">Filter</a></h2>
- <h3>Description</h3>
- <p>Sets a token filter for this project. Token filters are used by all tasks
- that perform file copying operations through the Project commodity methods.</p>
- <p>Note: the token string must not contain the separators chars (@).</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">token</td>
- <td valign="top">the token string without @</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">value</td>
- <td valign="top">the string that should be put to replace the token when the
- file is copied</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <filter token="year" value="2000" />
- <copydir src="${src.dir}" dest="${dest.dir}"/></pre>
- <p>will copy recursively all the files from the <i>src.dir</i> directory into
- the <i>dest.dir</i> directory replacing all the occurencies of the string <i>@year@</i>
- with <i>2000.</i></p>
- <hr>
- <h2><a name="get">Get</a></h2>
- <h3>Description</h3>
- <p>Gets a file from an URL. When the verbose option is "on", this task
- displays a '.' for every 100 Kb retrieved.</p>
- <p>This task should be preferred above the <a href="#cvs">CVS task</a> when
- doing automated builds. CVS is significant slower than loading a compressed
- archive with http/ftp.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">the URL from which to retrieve a file.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">the file where to store the retrieved file.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">verbose</td>
- <td valign="top">show verbose information ("on"/"off").</td>
- <td align="center" valign="top">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <get src="http://jakarta.apache.org/" dest="help/index.html" /></pre>
- <p>gets the index page of http://jakarta.apache.org/, and stores it in the file <code>help/index.html</code>.</p>
- <hr>
- <h2><a name="gunzip">GUnzip</a></h2>
- <h3>Description</h3>
- <p>Expands a GZip file.</p>
-
- <p>If <i>dest</i> is a directory the name of the destination file is
- the same as <i>src</i> (with the ".gz" extension removed if
- present). If <i>dest</i> is ommited, the parent dir of <i>src</i> 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.</p>
-
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">the file to expand.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">the destination file or directory.</td>
- <td align="center" valign="top">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><gunzip src="test.tar.gz"/></code></p>
- </blockquote>
- <p>expands <i>test.tar.gz</i> to <i>test.tar</i></p>
- <blockquote>
- <p><code><gunzip src="test.tar.gz" dest="test2.tar"/></code></p>
- </blockquote>
- <p>expands <i>test.tar.gz</i> to <i>test2.tar</i></p>
- <blockquote>
- <p><code><gunzip src="test.tar.gz" dest="subdir"/></code></p>
- </blockquote>
- <p>expands <i>test.tar.gz</i> to <i>subdir/test.tar</i> (assuming
- subdir is a directory).</p>
-
- <hr>
- <h2><a name="gzip">GZip</a></h2>
- <h3>Description</h3>
- <p>GZips a file.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">the file to gzip.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">zipfile</td>
- <td valign="top">the destination file.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><gzip src="test.tar" zipfile="test.tar.gz"
- /></code></p>
- </blockquote>
- <hr>
- <h2><a name="fixcrlf">FixCRLF</a></h2>
- <h3>Description</h3>
- <p>Adjusts a text file to local.</p>
- <p>The <i>basedir</i> attribute is the reference directory from where to jar.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">srcDir</td>
- <td valign="top">Where to find the files to be fixed up.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">destDir</td>
- <td valign="top">Where to place the corrected files. Defaults to
- srcDir (replacing the original file)</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">cr</td>
- <td valign="top">Specifies how carriage return (CR) characters are to
- be handled. Valid values for this property are:
- <ul>
- <li>add: ensure that there is a CR before every LF
- <li>asis: leave CR characters alone
- <li>remove: remove all CR characters
- </ul>
- Default is based on the platform on which you are running this task.
- For Unix platforms, the default is remove. For DOS based systems
- (including Windows), the default is add.
- <p>
- Note: Unless this property is specified as "asis", extra CR characters
- which do not preceed a LF will be removed.
- </td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">tab</td>
- <td valign="top">Specifies how tab characters are to be handled. Valid
- values for this property are:
- <ul>
- <li>add: convert sequences of spaces which span a tab stop to tabs
- <li>asis: leave tab and space characters alone
- <li>remove: convert tabs to spaces
- </ul>
- Default for this parameter is "asis".
- <p>
- Note: Unless this property is specified as "asis", extra spaces and
- tabs after the last non-whitespace character on the line will be removed.
- </td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">eof</td>
- <td valign="top">Specifies how DOS end of file (control-Z) characters are
- to be handled. Valid values for this property are:
- <ul>
- <li>add: ensure that there is an EOF character at the end of the file
- <li>asis: leave EOF characters alone
- <li>remove: remove any EOF character found at the end
- </ul>
- Default is based on the platform on which you are running this task.
- For Unix platforms, the default is remove. For DOS based systems
- (including Windows), the default is asis.
- </td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <fixcrlf srcdir="${src}"
- cr="remove" eof="remove"
- includes="**/*.sh"
- /></pre>
- <p>Removes carriage return and eof characters from the shell scripts. Tabs and
- spaces are left as is.
- <pre> <fixcrlf srcdir="${src}"
- cr="add"
- includes="**/*.bat"
- /></pre>
- <p>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.</p>
- <pre> <fixcrlf srcdir="${src}"
- tabs="add"
- includes="**/Makefile"
- /></pre>
- <p>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.</p>
- <pre> <fixcrlf srcdir="${src}"
- tabs="remove"
- includes="**/README*"
- /></pre>
- <p>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.</p>
- <hr>
- <h2><a name="jar">Jar</a></h2>
- <h3>Description</h3>
- <p>Jars a set of files.</p>
- <p>The <i>basedir</i> attribute is the reference directory from where to jar.</p>
- <p>It is possible to refine the set of files that are being jarred. This can be
- done with the <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i>
- attributes. With the <i>includes</i> attribute you specify the files you want to
- have included by using patterns. The <i>exclude</i> attribute is used to specify
- the files you want to have excluded. This is also done with patterns. And
- finally with the <i>defaultexcludes</i> attribute, you can specify whether you
- want to use default exclusions or not. See the section on <a
- href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The patterns are
- relative to the <i>basedir</i> directory.</p>
- <p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes
- replace the <i>items</i> and <i>ignore</i> attributes. The following explains
- how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>
- <p>When "*" is used for <i>items</i>, 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.</p>
- <p>With the <i>ignore</i> attribute, you can specify files or directories to
- ignore. These files will not be jarred. The items in the <i>ignore</i> attribute
- override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>
- attribute are just names, they do not contain any path information!</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">jarfile</td>
- <td valign="top">the jar-file to create.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">basedir</td>
- <td valign="top">the directory from which to jar the files.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">compress</td>
- <td valign="top">Not only store data but also compress them, defaults to true</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">items</td>
- <td valign="top">a comma separated list of the files/directories to jar. All
- files are included when omitted. (<b>deprecated</b>, use <i>includes</i>
- instead).</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">ignore</td>
- <td valign="top">comma separated list of filenames/directorynames to exclude
- from the jar. No files (except default excludes) are excluded when
- omitted. (<b>deprecated</b>, use <i>excludes</i> instead).</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">manifest</td>
- <td valign="top">the manifest file to use.</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" /></pre>
- <p>jars all files in the <code>${build}/classes</code> directory in a file
- called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>
- <pre> <jar jarfile="${dist}/lib/app.jar"
- basedir="${build}/classes"
- excludes="**/Test.class"
- /></pre>
- <p>jars all files in the <code>${build}/classes</code> directory in a file
- called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Files
- with the name <code>Test.class</code> are excluded.</p>
- <pre> <jar jarfile="${dist}/lib/app.jar"
- basedir="${build}/classes"
- includes="mypackage/test/**"
- excludes="**/Test.class"
- /></pre>
- <p>jars all files in the <code>${build}/classes</code> directory in a file
- called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Only
- files under the directory <code>mypackage/test</code> are used, and files with
- the name <code>Test.class</code> are excluded.</p>
- <h3>Deprecated examples</h3>
- <pre> <jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" items="*" /></pre>
- <p>jars all files in the <code>${build}/classes</code> directory in a file
- called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>
- <pre> <jar jarfile="${dist}/lib/app.jar" basedir="${build}/classes" items="*" ignore="Test.class" /></pre>
- <p>jars all files in the <code>${build}/classes</code> directory in a file
- called <code>app.jar</code> in the <code>${dist}/lib</code> directory.
- Files/directories with the name <code>Test.class</code> are excluded.</p>
- <hr>
- <h2><a name="java">Java</a></h2>
- <h3>Description</h3>
- <p>Executes a Java class within the running (Ant) VM or forks another VM if
- specified.</p>
- <p>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.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">classname</td>
- <td valign="top">the Java class to execute.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">args</td>
- <td valign="top">the arguments for the class that is executed.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">fork</td>
- <td valign="top">if enabled triggers the class execution in another VM
- (disabled by default)</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">jvmargs</td>
- <td valign="top">the arguments to pass to the forked VM (ignored if fork is
- disabled)</td>
- <td align="center" valign="top">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <java classname="test.Main" /></pre>
- <pre> <java classname="test.Main" args="-h" /></pre>
- <pre> <java classname="test.Main"
- args="-h"
- fork="yes"
- jvmargs="-Xrunhprof:cpu=samples,file=log.txt,depth=3"
- /></pre>
- <hr>
- <h2><a name="javac">Javac</a></h2>
- <h3>Description</h3>
- <p>Compiles a source tree within the running (Ant) VM.</p>
- <p>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.</p>
- <p>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.</p>
- <p>The directory structure of the source tree should follow the package
- hierarchy.</p>
- <p>It is possible to refine the set of files that are being compiled/copied.
- This can be done with the <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i>
- attributes. With the <i>includes</i> attribute you specify the files you want to
- have included by using patterns. The <i>exclude</i> attribute is used to specify
- the files you want to have excluded. This is also done with patterns. And
- finally with the <i>defaultexcludes</i> attribute, you can specify whether you
- want to use default exclusions or not. See the section on <a
- href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The patterns are
- relative to the <i>srcdir</i> directory.</p>
- <p>It is possible to use different compilers. This can be selected with the
- "build.compiler" property. There are three choices:</p>
- <ul>
- <li>classic (the standard compiler of JDK 1.1/1.2)</li>
- <li>modern (the new compiler of JDK 1.3)</li>
- <li>jikes (the <a
- href="http://oss.software.ibm.com/developerworks/opensource/jikes/project">Jikes</a>
- compiler)</li>
- </ul>
- <p>For JDK 1.1/1.2 is classic the default. For JDK 1.3 is modern the default.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">srcdir</td>
- <td valign="top">location of the java files.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">destdir</td>
- <td valign="top">location where to store the class files.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">classpath</td>
- <td valign="top">the classpath to use.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">bootclasspath</td>
- <td valign="top">location of bootstrap class files.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">extdirs</td>
- <td valign="top">location of installed extensions.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">debug</td>
- <td valign="top">indicates whether there should be compiled with debug
- information ("on").</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">optimize</td>
- <td valign="top">indicates whether there should be compiled with
- optimization ("on").</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">deprecation</td>
- <td valign="top">indicates whether there should be compiled with deprecation
- information ("on").</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">filtering</td>
- <td valign="top">indicates whether token filtering should take place</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <javac srcdir="${src}"
- destdir="${build}"
- classpath="xyz.jar"
- debug="on"
- /></pre>
- <p>compiles all .java files under the directory <code>${src}</code>, and stores
- the .class files in the directory <code>${build}</code>. It also copies the non-java
- files from the tree under <code>${src}</code> to the tree under <code>${build}</code>.
- The classpath used contains <code>xyz.jar</code>, and debug information is on.</p>
- <pre> <javac srcdir="${src}"
- destdir="${build}"
- includes="mypackage/p1/**,mypackage/p2/**"
- excludes="mypackage/p1/testpackage/**"
- classpath="xyz.jar"
- debug="on"
- /></pre>
- <p>compiles .java files under the directory <code>${src}</code>, and stores the
- .class files in the directory <code>${build}</code>. It also copies the non-java
- files from the tree under <code>${src}</code> to the tree under <code>${build}</code>.
- The classpath used contains <code>xyz.jar</code>, and debug information is on.
- Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are
- used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded
- form compilation and copy.</p>
- <hr>
- <h2><a name="javadoc">Javadoc/Javadoc2</a></h2>
- <h3>Description</h3>
- <p>Generates code documentation using the javadoc tool.</p>
- <p>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 <a href="#javac">javac</a> task, but it's
- not used so frequently.</p>
- <p>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.</p>
- <p>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.</p>
- <p>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 <a href="#javadoc">javadoc</a>
- instead.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Availability</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">sourcepath</td>
- <td valign="top">Specify where to find source files</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">destdir</td>
- <td valign="top">Destination directory for output files</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">sourcefiles</td>
- <td valign="top">Space separated list of source files</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="middle" rowspan="2">at least one of the two</td>
- </tr>
- <tr>
- <td valign="top">packagenames</td>
- <td valign="top">Space separated list of package files (with terminating
- wildcard)</td>
- <td align="center" valign="top">all</td>
- </tr>
- <tr>
- <td valign="top">Classpath</td>
- <td valign="top">Specify where to find user class files</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Bootclasspath</td>
- <td valign="top">Override location of class files loaded by the bootstrap
- class loader</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Extdirs</td>
- <td valign="top">Override location of installed extensions</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Overview</td>
- <td valign="top">Read overview documentation from HTML file</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Public</td>
- <td valign="top">Show only public classes and members</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Protected</td>
- <td valign="top">Show protected/public classes and members (default)</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Package</td>
- <td valign="top">Show package/protected/public classes and members</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Private</td>
- <td valign="top">Show all classes and members</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Old</td>
- <td valign="top">Generate output using JDK 1.1 emulating doclet</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Verbose</td>
- <td valign="top">Output messages about what Javadoc is doing</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Locale</td>
- <td valign="top">Locale to be used, e.g. en_US or en_US_WIN</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Encoding</td>
- <td valign="top">Source file encoding name</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Version</td>
- <td valign="top">Include @version paragraphs</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Use</td>
- <td valign="top">Create class and package usage pages</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Author</td>
- <td valign="top">Include @author paragraphs</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Splitindex</td>
- <td valign="top">Split index into one file per letter</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Windowtitle</td>
- <td valign="top">Browser window title for the documenation (text)</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Doctitle</td>
- <td valign="top">Include title for the package index(first) page (html-code)</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Header</td>
- <td valign="top">Include header text for each page (html-code)</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">Footer</td>
- <td valign="top">Include footer text for each page (html-code)</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">bottom</td>
- <td valign="top">Include bottom text for each page (html-code)</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">link</td>
- <td valign="top">Create links to javadoc output at the given URL</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">linkoffline</td>
- <td valign="top">Link to docs at <url> using package list at
- <url2></td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">group</td>
- <td valign="top">Group specified packages together in overview page</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">nodeprecated</td>
- <td valign="top">Do not include @deprecated information</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">nodeprecatedlist</td>
- <td valign="top">Do not generate deprecated list</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">notree</td>
- <td valign="top">Do not generate class hierarchy</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">noindex</td>
- <td valign="top">Do not generate index</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">nohelp</td>
- <td valign="top">Do not generate help link</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">nonavbar</td>
- <td valign="top">Do not generate navigation bar</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">serialwarn</td>
- <td valign="top">Generate warning about @serial tag</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">helpfile</td>
- <td valign="top">Specifies the HTML help file to use</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">stylesheetfile</td>
- <td valign="top">Specifies the CSS stylesheet to use</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">charset</td>
- <td valign="top">Charset for cross-platform viewing of generated
- documentation</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">docencoding</td>
- <td valign="top">Output file encoding name</td>
- <td align="center" valign="top">1.1</td>
- <td align="center" valign="top">No</td>
- </tr>
- </table>
- <h3>Example</h3>
- <pre> <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>"
- /></pre>
- <hr>
- <h2><a name="keysubst">KeySubst</a></h2>
- <h3>Description</h3>
- <p>Performs keyword substitution in the source file, and writes the result to
- the destination file.</p>
- <p>Keys in the source file are of the form ${keyname}. The <i>keys</i> attribute
- contains key/value pairs. When a key is found in the <i>keys</i> attribute, then
- "${keyname}" is replaced by the corresponding value.</p>
- <p>The <i>keys</i> attribute is of the form
- "name1=value1*name2=value2*name3=value3". The '*' is called the
- separator, which might we changed with the <i>sep</i> attribute.</p>
- <p>Note: the source file and destination file may not be the same.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">the source file.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">the destination file.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">sep</td>
- <td valign="top">the separator for the name/value pairs.</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">keys</td>
- <td valign="top">name/value pairs for replacement.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <keysubst src="abc.txt" dest="def.txt" keys="VERSION=1.0.3*DATE=2000-01-10" /></pre>
- <hr>
- <h2><a name="mkdir">Mkdir</a></h2>
- <h3>Description</h3>
- <p>Creates a directory. Also non-existent parent directories are created, when
- necessary.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">dir</td>
- <td valign="top">the directory to create.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre><mkdir dir="${dist}" /></pre>
- <p>creates a directory <code>${dist}</code>.</p>
- <pre><mkdir dir="${dist}/lib" /></pre>
- <p>creates a directory <code>${dist}/lib</code>.</p>
- <hr>
- <h2><a name="property">Property</a></h2>
- <h3>Description</h3>
- <p>Sets a property (by name and value), or set of properties (from file or
- resource) in the project.</p>
- <p>When a property was set by the user, or was a property in a parent project
- (that started this project with the <a href="#ant">ant task</a>), 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.</p>
- <p>There are three ways to set properties:</p>
- <ul>
- <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li>
- <li>By setting the <i>file</i> attribute with the filename of the property
- file to load. This property file has the format as defined by the file used
- in the class java.util.Properties.</li>
- <li>By setting the <i>resource</i> attribute with the resource name of the
- property file to load. This property file has the format as defined by the
- file used in the class java.util.Properties.</li>
- </ul>
- <p>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.</p>
- <p>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.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">name</td>
- <td valign="top">the name of the property to set.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">value</td>
- <td valign="top">the value of the property.</td>
- <td valign="middle" align="center" rowspan="3">Yes</td>
- </tr>
- <tr>
- <td valign="top">resource</td>
- <td valign="top">the resource name of the property file.</td>
- </tr>
- <tr>
- <td valign="top">file</td>
- <td valign="top">the filename of the property file .</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <property name="foo.dist" value="dist" /></pre>
- <p>sets the property <code>foo.dist</code> to the value "dist".</p>
- <pre> <property file="foo.properties" /></pre>
- <p>reads a set of properties from a file called "foo.properties".</p>
- <pre> <property resource="foo.properties" /></pre>
- <p>reads a set of properties from a resource called "foo.properties".</p>
- <hr>
- <h2><a name="rename">Rename</a></h2>
- <h3>Description</h3>
- <p>Renames a given file.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">file to rename.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">new name of the file.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">replace</td>
- <td valign="top">Enable replacing of existing file (default: on).</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <rename src="foo.jar" dest="${name}-${version}.jar" /></pre>
- <p>Renames the file <code>foo.jar</code> to <code>${name}-${version}.jar</code> (assuming <code>name</code>
- and <code>version</code> being predefined properties). If a file named <code>${name}-${version}.jar</code>
- already exists, it will be removed prior to renameing <code>foo.jar</code>.</p>
- <hr>
- <h2><a name="replace">Replace</a></h2>
- <h3>Description</h3>
- <p>Replaces the occurrence of a given string with another string in a file.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">file</td>
- <td valign="top">file for which the token should be replaced.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">token</td>
- <td valign="top">the token which must be replaced.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">value</td>
- <td valign="top">the new value for the token. When omitted, an empty string
- ("") is used.</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <replace file="${src}/index.html" token="@@@" value="wombat" /></pre>
- <p>replaces occurrences of the string "@@@" with the string
- "wombat", in the file <code>${src}/index.html</code>.</p>
- <hr>
- <h2><a name="rmic">Rmic</a></h2>
- <h3>Description</h3>
- <p>Runs the rmic compiler for a certain class.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">base</td>
- <td valign="top">the location to store the compiled files.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">classname</td>
- <td valign="top">the class for which to run <code>rmic</code>.</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">filtering</td>
- <td valign="top">indicates whether token filtering should take place</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <rmic classname="com.xyz.FooBar" base="${build}/classes" /></pre>
- <p>runs the rmic compiler for the class <code>com.xyz.FooBar</code>. The
- compiled files will be stored in the directory <code>${build}/classes</code>.</p>
- <hr>
- <h2><a name="tar">Tar</a></h2>
- <h3>Description</h3>
- <p>Creates a tar archive.</p>
- <p>The <i>basedir</i> attribute is the reference directory from where to tar.</p>
- <p>It is possible to refine the set of files that are being tarred. This can be
- done with the <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i>
- attributes. With the <i>includes</i> attribute you specify the files you want to
- have included by using patterns. The <i>exclude</i> attribute is used to specify
- the files you want to have excluded. This is also done with patterns. And
- finally with the <i>defaultexcludes</i> attribute, you can specify whether you
- want to use default exclusions or not. See the section on <a
- href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The patterns are
- relative to the <i>basedir</i> directory.</p>
- <p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes
- replace the <i>items</i> and <i>ignore</i> attributes. The following explains
- how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>
- <p>When "*" is used for <i>items</i>, all files in the basedir, and
- its subdirectories, will be tarred. Otherwise all the files and directories
- mentioned in the items list will tarred. When a directory is specified, then all
- files within it are also tarred.</p>
- <p>With the <i>ignore</i> attribute, you can specify files or directories to
- ignore. These files will not be tarred. The items in the <i>ignore</i> attribute
- override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>
- attribute are just names, they do not contain any path information!</p>
- <p>Note that this task does not perform compression. You might want to use the <a href="#gzip">GZip</a>
- task to come up with a .tar.gz package.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td valign="top" align="center"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">tarfile</td>
- <td valign="top">the tar-file to create.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">basedir</td>
- <td valign="top">the directory from which to zip the files.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <tar tarfile="${dist}/manual.tar" basedir="htdocs/manual" />
- <gzip zipfile="${dist}/manual.tar.gz" src="${dist}/manual.tar" /></pre>
- <p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>
- in the <code>${dist}</code> directory, then applies the gzip task to compress
- it.</p>
- <pre> <tar tarfile="${dist}/manual.tar"
- basedir="htdocs/manual"
- excludes="mydocs/**, **/todo.html"
- /></pre>
- <p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>
- in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
- or files with the name <code>todo.html</code> are excluded.</p>
- <hr>
- <h2><a name="taskdef">Taskdef</a></h2>
- <h3>Description</h3>
- <p>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.</p>
- <p>Taskdef should be used to add your own tasks to the system. See also "<a
- href="#writingowntask">Writing your own task</a>".</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">name</td>
- <td valign="top">the name of the task</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">classname</td>
- <td valign="top">the full class name implementing the task</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <taskdef name="myjavadoc" classname="com.mydomain.JavadocTask" /></pre>
- <p>makes a task called <code>myjavadoc</code> available to Ant. The class <code>com.mydomain.JavadocTask</code>
- implements the task.</p>
- <hr>
- <h2><a name="tstamp">Tstamp</a></h2>
- <h3>Description</h3>
- <p>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".</p>
- <p>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.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <tstamp/></pre>
- <hr>
- <h2><a name="untar">Untar</a></h2>
- <h3>Description</h3>
- <p>Untars a tarfile.</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">tarfile to expand.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">dest</td>
- <td valign="top">directory where to store the expanded files.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code>
- <gunzip src="tools.tar.gz"/><br>
- <untar src="tools.tar" dest="${tools.home}"/>
- </code></p>
- </blockquote>
- <hr>
- <h2><a name="zip">Zip</a></h2>
- <h3>Description</h3>
- <p>Creates a zipfile.</p>
- <p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>
- <p>It is possible to refine the set of files that are being zipped. This can be
- done with the <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i>
- attributes. With the <i>includes</i> attribute you specify the files you want to
- have included by using patterns. The <i>exclude</i> attribute is used to specify
- the files you want to have excluded. This is also done with patterns. And
- finally with the <i>defaultexcludes</i> attribute, you can specify whether you
- want to use default exclusions or not. See the section on <a
- href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The patterns are
- relative to the <i>basedir</i> directory.</p>
- <p>The <i>includes</i>, <i>excludes</i> and <i>defaultexcludes</i> attributes
- replace the <i>items</i> and <i>ignore</i> attributes. The following explains
- how the deprecated <i>items</i> and <i>ignore</i> attribute behave.</p>
- <p>When "*" is used for <i>items</i>, 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.</p>
- <p>With the <i>ignore</i> attribute, you can specify files or directories to
- ignore. These files will not be zipped. The items in the <i>ignore</i> attribute
- override the items in the <i>items</i> attribute. The names specified in the <i>ignore</i>
- attribute are just names, they do not contain any path information!</p>
- <h3>Parameters</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td valign="top" align="center"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">zipfile</td>
- <td valign="top">the zip-file to create.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">basedir</td>
- <td valign="top">the directory from which to zip the files.</td>
- <td align="center" valign="top">Yes</td>
- </tr>
- <tr>
- <td valign="top">compress</td>
- <td valign="top">Not only store data but also compress them, defaults to true</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">items</td>
- <td valign="top">a comma separated list of the files/directories to zip. All
- files are included when omitted. (<b>deprecated</b>, use <i>includes</i>
- instead).</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">ignore</td>
- <td valign="top">comma separated list of filenames/directorynames to exclude
- from the zip. No files (except default excludes) are excluded when
- omitted. (<b>deprecated</b>, use <i>excludes</i> instead).</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <pre> <zip zipfile="${dist}/manual.zip"
- basedir="htdocs/manual"
- /></pre>
- <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
- in the <code>${dist}</code> directory.</p>
- <pre> <zip zipfile="${dist}/manual.zip"
- basedir="htdocs/manual"
- excludes="mydocs/**, **/todo.html"
- /></pre>
- <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
- in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
- or files with the name <code>todo.html</code> are excluded.</p>
- <pre> <zip zipfile="${dist}/manual.zip"
- basedir="htdocs/manual"
- includes="api/**/*.html"
- excludes="**/todo.html"
- /></pre>
- <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
- in the <code>${dist}</code> directory. Only html files under the directory <code>api</code>
- are zipped, and files with the name <code>todo.html</code> are excluded.</p>
- <h3>Deprecated examples</h3>
- <pre> <zip zipfile="${dist}/manual.zip"
- basedir="htdocs/manual"
- items="*"
- /></pre>
- <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
- in the <code>${dist}</code> directory.</p>
- <pre> <zip zipfile="${dist}/manual.zip"
- basedir="htdocs/manual"
- items="*"
- ignore="mydocs, todo.html"
- /></pre>
- <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
- in the <code>${dist}</code> directory. Files/directories with the names <code>mydocs</code>
- and <code>todo.html</code> are excluded.</p>
- <hr>
- <h2><a name="writingowntask">Writing your own task</a></h2>
- <p>It is very easy to write your own task:</p>
- <ol>
- <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code>.</li>
- <li>For each attribute, write a setter method. The setter method must be a <code>public
- void</code> method that takes one <code>String</code> 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.</li>
- <li>Write a <code>public void execute</code> method, with no arguments, that
- throws a <code>BuildException</code>. This method implements the task
- itself.</li>
- </ol>
- <p>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.</p>
- <p>Let's write our own task, that prints a message on the System.out stream. The
- task has one attribute called "message".</p>
- <blockquote>
- <pre>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;
- }
- }</pre>
- </blockquote>
- <p>It's really this simple;-)</p>
- <p>Adding your task to the system is rather simple too:</p>
- <ol>
- <li>Make sure the class that implements your task is in the classpath when
- starting Ant.</li>
- <li>In your initialization target, add a <i>taskdef</i> task. This actually adds
- your task to the system.</li>
- <li>Use your task in the rest of the buildfile.</li>
- </ol>
- <h3>Example</h3>
- <blockquote>
- <pre><?xml version="1.0"?>
-
- <project name="OwnTaskExample" default="main" basedir=".">
- <target name="init">
- <taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/>
- </target>
-
- <target name="main" depends="init">
- <mytask message="Hello World! MyVeryOwnTask works!" />
- </target>
- </project>
- </pre>
- </blockquote>
- <p>Another way to add a task (more permanently), is to add the task name and
- implementing class name to the <code>default.properties</code> file in the <code>org.apache.tools.ant.taskdefs</code>
- package. Then you can use it as if it were a built in task.</p>
- <hr>
- <h2><a name="feedback">Feedback</a></h2>
- <p>To provide feedback on this software, please subscribe to the Ant Development
- Mail List <a href="mailto:(ant-dev-subscribe@jakarta.apache.org">(ant-dev-subscribe@jakarta.apache.org</a>)</p>
- <hr>
- <p align="center">Copyright � 2000 Apache Software Foundation. All rights
- Reserved.</p>
-
- <h2><a name="optionaltasks">Optional tasks</a></h2>
- <ul>
- <li><a href="#netrexxc">NetRexxC</a></li>
- <li><a href="#renameexts">RenameExtensions</a></li>
- <li><a href="#script">Script</a></li>
- </ul>
- <hr>
- <h2><a name="netrexxc">NetRexxC</a></h2>
- <h3><b>Description:</b></h3>
- <p>Compiles a <a href="http://www2.hursley.ibm.com/netrexx">NetRexx</a>
- source tree within the running (Ant) VM.</p>
- <p>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.</p>
- <p>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</p>
- <p>The directory structure of the source tree should follow the package
- hierarchy.</p>
- <p>It is possible to refine the set of files that are being compiled/copied.
- This can be done with the <i>includes</i>, <i>excludes</i> and
- <i>defaultexcludes</i> attributes. With the <i>includes</i> attribute you
- specify the files you want to have included by using patterns. The
- <i>exclude</i> attribute is used to specify the files you want to have
- excluded. This is also done with patterns. And finally with the
- <i>defaultexcludes</i> attribute, you can specify whether you
- want to use default exclusions or not. See the section on <a
- href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The
- patterns are relative to the <i>srcDir</i> directory.</p>
-
- <h3>Parameters:</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">binary</td>
- <td valign="top">Whether literals are treated as the java binary
- type rather than the NetRexx types</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">classpath</td>
- <td valign="top">The classpath to use during compilation</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">comments</td>
- <td valign="top">Whether comments are passed through to the
- generated java source</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">compact</td>
- <td valign="top">Whether error messages come out in compact or
- verbose format</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">compile</td>
- <td valign="top">Whether the NetRexx compiler should compile the
- generated java code</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">console</td>
- <td valign="top">Whether or not messages should be displayed on the
- 'console'</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">crossref</td>
- <td valign="top">Whether variable cross references are generated</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">decimal</td>
- <td valign="top">Whether decimal arithmetic should be used for the
- NetRexx code</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when
- omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">destDir</td>
- <td valign="top">the destination directory into which the NetRexx
- source files should be copied and then compiled</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">diag</td>
- <td valign="top">Whether diagnostic information about the compile is
- generated</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when
- omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">explicit</td>
- <td valign="top">Whether variables must be declared explicitly
- before use</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">format</td>
- <td valign="top">Whether the generated java code is formatted nicely
- or left to match NetRexx line numbers for call stack debugging</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">java</td>
- <td valign="top">Whether the generated java code is produced</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">keep</td>
- <td valign="top">Sets whether the generated java source file should be kept
- after compilation. The generated files will have an extension of
- .java.keep, <b>not</b> .java</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">logo</td>
- <td valign="top">Whether the compiler text logo is displayed when
- compiling</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">replace</td>
- <td valign="top">Whether the generated .java file should be replaced
- when compiling</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">savelog</td>
- <td valign="top">Whether the compiler messages will be written to
- NetRexxC.log as well as to the console</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">sourcedir</td>
- <td valign="top">Tells the NetRexx compiler to store the class files in the
- same directory as the source files. The alternative is the working
- directory</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">srcDir</td>
- <td valign="top">Set the source dir to find the source Netrexx
- files</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">strictargs</td>
- <td valign="top">Tells the NetRexx compiler that method calls always
- need parentheses, even if no arguments are needed, e.g.
- <code>aStringVar.getBytes</code> vs.
- <code>aStringVar.getBytes()</code></td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">strictassign</td>
- <td valign="top">Tells the NetRexx compile that assignments must
- match exactly on type</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">strictcase</td>
- <td valign="top">Specifies whether the NetRexx compiler should be
- case sensitive or not</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">strictimport</td>
- <td valign="top">Whether classes need to be imported explicitly using an
- <code>import</code> statement. By default the NetRexx compiler will
- import certain packages automatically</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">strictprops</td>
- <td valign="top">Whether local properties need to be qualified
- explicitly using <code>this</code></td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">strictsignal</td>
- <td valign="top">Whether the compiler should force catching of
- exceptions by explicitly named types</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">symbols</td>
- <td valign="top">Whether debug symbols should be generated into the
- class file</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">time</td>
- <td valign="top">Asks the NetRexx compiler to print compilation
- times to the console</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">trace</td>
- <td valign="top">Turns on or off tracing and directs the resultant
- trace output</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">utf8</td>
- <td valign="top">Tells the NetRexx compiler that the source is in UTF8</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">verbose</td>
- <td valign="top">Whether lots of warnings and error messages should
- be generated</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><netrexxc srcDir="/source/project"
- includes="vnr/util/*"
- destDir="/source/project/build"
- classpath="/source/project2/proj.jar"
- comments="true"
- crossref="false" replace="true"
- keep="true" /></code>
- </p>
- </blockquote>
- <hr>
- <h2><a name="renameexts">RenameExtensions</a></h2>
- <h3><b>Description:</b></h3>
- <p>Renames files in the <code>srcDir</code> directory ending with the
- <code>fromExtension</code> string so that they end with the
- <code>toExtension</code> string. Files are only replaced if
- <code>replace</code> is true
- </p>
- <p>See the section on
- <a href="#directorybasedtasks">directory based tasks</a>, on how the
- inclusion/exclusion of files works, and how to write patterns. The
- patterns are relative to the <i>srcDir</i> directory.</p>
- <h3>Parameters:</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used or not
- ("yes"/"no"). Default excludes are used when
- omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">excludes</td>
- <td valign="top">comma separated list of patterns of files that must be
- excluded. No files (except default excludes) are excluded when
- omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">fromExtention</td>
- <td valign="top">The string that files must end in to be renamed</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">includes</td>
- <td valign="top">comma separated list of patterns of files that must be
- included. All files are included when omitted.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">replace</td>
- <td valign="top">Whether the file being renamed to should be
- replaced if it already exists</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">srcDir</td>
- <td valign="top">The starting directory for files to search in</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- <tr>
- <td valign="top">toExtension</td>
- <td valign="top">The string that renamed files will end with on
- completion</td>
- <td valign="top" align="center">Yes</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p><code><renameext srcDir="/source/project1"
- includes="**"
- excludes="**/samples/*"
- fromExtension=".java.keep"
- toExtension=".java"
- replace="true" />
- </code>
- </p>
- </blockquote>
-
- <hr>
- <h2><a name="script">Script</a></h2>
- <h3><b>Description:</b></h3>
- <p>Execute a script in a
- <a href="http://www.alphaworks.ibm.com/tech/bsf">BSF</a> supported language.
- <p>All items (tasks, targets, etc) of the running project are accessible
- from the script.
- <h3>Parameters:</h3>
- <table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">language</td>
- <td valign="top">The programming language the script is written in.
- Must be a supported BSF language</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">src</td>
- <td valign="top">The location of the script as a file, if not inline</td>
- <td valign="top" align="center">No</td>
- </tr>
- </table>
- <h3>Examples</h3>
- <blockquote>
- <p>None yet available</p>
- </blockquote>
-
- </body>
-
- </html>
-
|
