2001-02-13 12:32:01 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2002-02-04 20:57:49 +00:00
|
|
|
<title>Writing a Simple Buildfile</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<h1>Using Ant</h1>
|
|
|
|
|
<h2><a name="buildfile">Writing a Simple Buildfile</a></h2>
|
2001-12-13 17:16:26 +00:00
|
|
|
<p>Ant's buildfiles are written in XML. Each buildfile contains one project
|
|
|
|
|
and at least one (default) target. Targets contain task elements.
|
|
|
|
|
Each task element of the buildfile can have an <code>id</code> attribute and
|
2001-02-13 12:32:01 +00:00
|
|
|
can later be referred to by the value supplied to this. The value has
|
|
|
|
|
to be unique. (For additional information, see the
|
|
|
|
|
<a href="#tasks"> Tasks</a> section below.)</p>
|
2001-12-13 17:16:26 +00:00
|
|
|
<h3><a name="projects">Projects</a></h3>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>A <i>project</i> 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">No</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 beforehand. When this is done, it must be omitted in the
|
|
|
|
|
project tag. If neither the attribute nor the property have
|
|
|
|
|
been set, the parent directory of the buildfile will be used.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2001-08-08 19:34:20 +00:00
|
|
|
<p>Optionally, a description for the project can be provided as a
|
2001-12-13 17:16:26 +00:00
|
|
|
top-level <code><description></code> element (see the <a
|
2001-08-08 19:34:20 +00:00
|
|
|
href="CoreTypes/description.html">description</a> type).</p>
|
|
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>Each project defines one or more <i>targets</i>.
|
|
|
|
|
A target is a set of <i>tasks</i> you want
|
|
|
|
|
to be executed. When starting Ant, you can select which target(s) you
|
|
|
|
|
want to have executed. When no target is given,
|
|
|
|
|
the project's default is used.</p>
|
|
|
|
|
|
2001-12-13 17:16:26 +00:00
|
|
|
<h3><a name="targets">Targets</a></h3>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>A target can depend on other targets. You might have a target for compiling,
|
|
|
|
|
for example, and a target for creating a distributable. You can only build a
|
|
|
|
|
distributable when you have compiled first, so the distribute target
|
|
|
|
|
<i>depends on</i> the compile target. Ant resolves these dependencies.</p>
|
|
|
|
|
<p>It should be noted, however, that Ant's <code>depends</code> attribute
|
2001-03-09 08:54:35 +00:00
|
|
|
only specifies the <i>order</i> in which targets should be executed - it
|
2001-02-13 12:32:01 +00:00
|
|
|
does not affect whether the target that specifies the dependency(s) gets
|
|
|
|
|
executed if the dependent target(s) did not (need to) run.
|
|
|
|
|
</p>
|
|
|
|
|
<p>Ant tries to execute the targets in the <code>depends</code>
|
|
|
|
|
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
|
|
|
|
|
<code>depends</code> 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 than one target
|
|
|
|
|
depends on it (see the previous example).</p>
|
|
|
|
|
<p>A target also has the ability to perform its execution if (or
|
|
|
|
|
unless) a property has been set. This allows, for example, better
|
|
|
|
|
control on the building process depending on the state of the system
|
|
|
|
|
(java version, OS, command-line property defines, etc.). To make a target
|
|
|
|
|
<i>sense</i> this property, you should add the <code>if</code> (or
|
|
|
|
|
<code>unless</code>) 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>
|
|
|
|
|
<pre><target name="build-own-fake-module-A" unless="module-A-present"/></pre>
|
|
|
|
|
</blockquote>
|
2002-03-25 19:39:41 +00:00
|
|
|
<p>In the first example, if the <code>module-A-present</code>
|
|
|
|
|
property is set (to any value), the target will be run. In the second
|
|
|
|
|
example, if the <code>module-A-present</code> property is set
|
|
|
|
|
(again, to any value), the target will not be run.
|
|
|
|
|
</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>If no <code>if</code> and no <code>unless</code> attribute is present,
|
|
|
|
|
the target will always be executed.</p>
|
|
|
|
|
<p>The optional <code>description</code> attribute can be used to provide a one-line description of this target, which is printed by the
|
2002-03-23 19:53:05 +00:00
|
|
|
<nobr><code>-projecthelp</code></nobr> command-line option. Targets
|
2002-03-25 19:39:41 +00:00
|
|
|
without such a description are deemed internal and will not be listed,
|
|
|
|
|
unless either the <nobr><code>-verbose</code></nobr> or
|
|
|
|
|
<nobr><code>-debug</code></nobr> option is used.
|
2002-03-23 19:53:05 +00:00
|
|
|
</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>It is a good practice to place your <a
|
|
|
|
|
href="CoreTasks/tstamp.html">tstamp</a> tasks in a so-called
|
|
|
|
|
<i>initialization</i> target, on which
|
|
|
|
|
all other targets depend. Make sure that target is always the first one in
|
|
|
|
|
the depends list of the other targets. In this manual, most initialization targets
|
2002-03-25 19:39:41 +00:00
|
|
|
have the name <code>"init"</code>.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<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 target.</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>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">unless</td>
|
2002-02-04 20:57:49 +00:00
|
|
|
<td valign="top">the name of the property that must not be set in order
|
2001-02-13 12:32:01 +00:00
|
|
|
for this target to execute.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">description</td>
|
|
|
|
|
<td valign="top">a short description of this target's function.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2002-03-25 19:39:41 +00:00
|
|
|
</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2002-03-23 19:53:05 +00:00
|
|
|
A target name can be any alphanumeric string valid in the encoding of the XML
|
2002-03-25 19:39:41 +00:00
|
|
|
file. The empty string "" is in this set, as is
|
|
|
|
|
comma "," and space " ".
|
|
|
|
|
Please avoid using these, as they will not be supported in future Ant versions
|
|
|
|
|
because of all the confusion they cause. IDE support of unusual target names,
|
|
|
|
|
or any target name containing spaces, varies with the IDE.
|
2002-03-23 19:53:05 +00:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
2002-03-25 19:39:41 +00:00
|
|
|
Targets beginning with a hyphen such as <code>"-restart"</code>
|
|
|
|
|
are valid, and can be used
|
|
|
|
|
to name targets that should not be called directly from the command line.
|
2001-09-08 01:05:18 +00:00
|
|
|
|
|
|
|
|
<h3><a name="tasks">Tasks</a></h3>
|
2001-02-13 12:32:01 +00:00
|
|
|
<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><<i>name</i> <i>attribute1</i>="<i>value1</i>" <i>attribute2</i>="<i>value2</i>" ... /></pre>
|
|
|
|
|
</blockquote>
|
|
|
|
|
<p>where <i>name</i> is the name of the task,
|
|
|
|
|
<i>attributeN</i> is the attribute name, and
|
|
|
|
|
<i>valueN</i> is the value for this attribute.</p>
|
2002-02-04 20:57:49 +00:00
|
|
|
<p>There is a set of <a href="coretasklist.html" target="navFrame">built-in tasks</a>, along with a
|
2001-02-13 12:32:01 +00:00
|
|
|
number of
|
|
|
|
|
<a href="optionaltasklist.html" target="navFrame"> optional tasks</a>, but it is also very
|
|
|
|
|
easy to <a href="develop.html#writingowntask">write your own</a>.</p>
|
|
|
|
|
<p>All tasks share a task name attribute. The value of
|
|
|
|
|
this attribute will be used in the logging messages generated by
|
|
|
|
|
Ant.</p>
|
|
|
|
|
Tasks can be assigned an <code>id</code> attribute:
|
|
|
|
|
<blockquote>
|
|
|
|
|
<pre><<i>taskname</i> id="<i>taskID</i>" ... /></pre>
|
|
|
|
|
</blockquote>
|
|
|
|
|
where <i>taskname</i> is the name of the task, and <i>taskID</i> is
|
2001-12-13 17:16:26 +00:00
|
|
|
a unique identifier for this task.
|
2001-02-13 12:32:01 +00:00
|
|
|
You can refer to the
|
|
|
|
|
corresponding task object in scripts or other tasks via this name.
|
|
|
|
|
For example, in scripts you could do:
|
|
|
|
|
<blockquote>
|
|
|
|
|
<pre>
|
|
|
|
|
<script ... >
|
|
|
|
|
task1.setFoo("bar");
|
|
|
|
|
</script>
|
|
|
|
|
</pre>
|
|
|
|
|
</blockquote>
|
|
|
|
|
to set the <code>foo</code> attribute of this particular task instance.
|
|
|
|
|
In another task (written in Java), you can access the instance via
|
|
|
|
|
<code>project.getReference("task1")</code>.
|
|
|
|
|
<p>
|
2002-03-25 19:39:41 +00:00
|
|
|
Note<sup>1</sup>: If "task1" has not been run yet, then
|
2001-02-13 12:32:01 +00:00
|
|
|
it has not been configured (ie., no attributes have been set), and if it is
|
|
|
|
|
going to be configured later, anything you've done to the instance may
|
|
|
|
|
be overwritten.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i>
|
|
|
|
|
be backward-compatible with this behaviour, since there will likely be no
|
|
|
|
|
task instances at all, only proxies.
|
|
|
|
|
</p>
|
|
|
|
|
|
2001-12-13 17:16:26 +00:00
|
|
|
<h3><a name="properties">Properties</a></h3>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>A project can have a set of properties. These might be set in the buildfile
|
2001-12-13 17:16:26 +00:00
|
|
|
by the <a href="CoreTasks/property.html">property</a> task, or might be set outside Ant. A
|
|
|
|
|
property has a name and a value; the name is case-sensitive. Properties may be used in the value of
|
2001-02-13 12:32:01 +00:00
|
|
|
task attributes. This is done by placing the property name between
|
|
|
|
|
"<code>${</code>" and "<code>}</code>" in the
|
|
|
|
|
attribute value. For example,
|
|
|
|
|
if there is a "builddir" property with the value
|
|
|
|
|
"build", then this could be used in an attribute like this:
|
|
|
|
|
<code>${builddir}/classes</code>.
|
2001-12-13 17:16:26 +00:00
|
|
|
This is resolved at run-time as <code>build/classes</code>.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
2001-08-30 13:23:14 +00:00
|
|
|
<h3><a name="built-in-props">Built-in Properties</a></h3>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>Ant provides access to all system properties as if they had been
|
|
|
|
|
defined using a <code><property></code> task.
|
|
|
|
|
For example, <code>${os.name}</code> expands to the
|
|
|
|
|
name of the operating system.</p>
|
2002-02-04 20:57:49 +00:00
|
|
|
<p>For a list of system properties see
|
2001-05-22 14:40:02 +00:00
|
|
|
<a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
|
2001-09-08 01:05:18 +00:00
|
|
|
</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>In addition, Ant has some built-in properties:</p>
|
|
|
|
|
<pre>
|
|
|
|
|
basedir the absolute path of the project's basedir (as set
|
|
|
|
|
with the basedir attribute of <project>).
|
|
|
|
|
ant.file the absolute path of the buildfile.
|
2001-06-08 10:31:08 +00:00
|
|
|
ant.version the version of Ant
|
2001-02-13 12:32:01 +00:00
|
|
|
ant.project.name the name of the project that is currently executing;
|
|
|
|
|
it is set in the name attribute of <project>.
|
|
|
|
|
ant.java.version the JVM version Ant detected; currently it can hold
|
2001-08-30 13:23:14 +00:00
|
|
|
the values "1.1", "1.2", "1.3" and "1.4".
|
2001-02-13 12:32:01 +00:00
|
|
|
</pre>
|
|
|
|
|
|
2001-12-13 17:16:26 +00:00
|
|
|
<a name="example"><h3>Example Buildfile</h3></a>
|
2001-02-13 12:32:01 +00:00
|
|
|
<pre>
|
|
|
|
|
<project name="MyProject" default="dist" basedir=".">
|
2002-02-21 06:25:16 +00:00
|
|
|
<description>
|
|
|
|
|
simple example build file
|
|
|
|
|
</description>
|
2001-02-13 12:32:01 +00:00
|
|
|
<!-- set global properties for this build -->
|
2002-02-21 06:39:30 +00:00
|
|
|
<property name="src" location="src"/>
|
|
|
|
|
<property name="build" location="build"/>
|
|
|
|
|
<property name="dist" location="dist"/>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
<target name="init">
|
|
|
|
|
<!-- Create the time stamp -->
|
|
|
|
|
<tstamp/>
|
|
|
|
|
<!-- Create the build directory structure used by compile -->
|
|
|
|
|
<mkdir dir="${build}"/>
|
|
|
|
|
</target>
|
|
|
|
|
|
2002-02-21 06:25:16 +00:00
|
|
|
<target name="compile" depends="init"
|
|
|
|
|
description="compile the source " >
|
2001-02-13 12:32:01 +00:00
|
|
|
<!-- Compile the java code from ${src} into ${build} -->
|
|
|
|
|
<javac srcdir="${src}" destdir="${build}"/>
|
|
|
|
|
</target>
|
|
|
|
|
|
2002-02-21 06:25:16 +00:00
|
|
|
<target name="dist" depends="compile"
|
|
|
|
|
description="generate the distribution" >
|
2001-02-13 12:32:01 +00:00
|
|
|
<!-- Create the distribution directory -->
|
|
|
|
|
<mkdir dir="${dist}/lib"/>
|
|
|
|
|
|
|
|
|
|
<!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
|
|
|
|
|
<jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
|
|
|
|
|
</target>
|
|
|
|
|
|
2002-02-21 06:25:16 +00:00
|
|
|
<target name="clean"
|
|
|
|
|
description="clean up" >
|
2001-02-13 12:32:01 +00:00
|
|
|
<!-- Delete the ${build} and ${dist} directory trees -->
|
|
|
|
|
<delete dir="${build}"/>
|
|
|
|
|
<delete dir="${dist}"/>
|
|
|
|
|
</target>
|
|
|
|
|
</project>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2002-02-21 06:25:16 +00:00
|
|
|
Notice that we are declaring properties outside any target. The
|
2002-02-21 10:00:17 +00:00
|
|
|
<tt><property></tt>,<tt><typedef></tt> and <tt><taskdef></tt>
|
2002-02-21 06:25:16 +00:00
|
|
|
tasks are special in that they can be declared outside any target. When you
|
|
|
|
|
do this they are evaluated before any targets are executed. No other tasks
|
|
|
|
|
can be declared outside targets.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
We have given some targets descriptions; this causes the <tt>projecthelp</tt>
|
|
|
|
|
invocation option to list them as public targets with the descriptions; the
|
|
|
|
|
other target is internal and not listed.
|
|
|
|
|
<p>
|
|
|
|
|
Finally, for this target to work the source in the <tt>src</tt> subdirectory
|
|
|
|
|
should be stored in a directory tree which matches the package names. Check the
|
|
|
|
|
<tt><javac></tt> task for details.
|
|
|
|
|
|
2001-12-13 17:16:26 +00:00
|
|
|
<a name="filters"><h3>Token Filters</h3></a>
|
2001-02-13 12:32:01 +00:00
|
|
|
<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
|
2001-12-13 17:16:26 +00:00
|
|
|
by the <a href="CoreTasks/filter.html">filter</a> task.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>Since this can potentially be a very harmful behavior,
|
|
|
|
|
the tokens in the files <b>must</b>
|
|
|
|
|
be of the form <code>@</code><i>token</i><code>@</code>, where
|
|
|
|
|
<i>token</i> is the token name that is set
|
2001-12-13 17:16:26 +00:00
|
|
|
in the <code><filter></code> task. This token syntax matches the syntax of other build systems
|
2001-02-13 12:32:01 +00:00
|
|
|
that perform such filtering and remains sufficiently orthogonal to most
|
|
|
|
|
programming and scripting languages, as well as with documentation systems.</p>
|
|
|
|
|
<p>Note: If a token with the format <code>@</code><i>token</i><code>@</code>
|
|
|
|
|
is found in a file, but no
|
|
|
|
|
filter is associated with that token, no changes take place;
|
|
|
|
|
therefore, no escaping
|
2001-03-09 08:54:35 +00:00
|
|
|
method is available - but as long as you choose appropriate names for your
|
2001-02-13 12:32:01 +00:00
|
|
|
tokens, this should not cause problems.</p>
|
|
|
|
|
<p><b>Warning:</b> If you copy binary files with filtering turned on, you can corrupt the
|
|
|
|
|
files. This feature should be used with text files <em>only</em>.</p>
|
|
|
|
|
|
|
|
|
|
<h3><a name="path">Path-like Structures</a></h3>
|
|
|
|
|
<p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type
|
|
|
|
|
references using both
|
|
|
|
|
"<code>:</code>" and "<code>;</code>" as separator
|
|
|
|
|
characters. Ant will
|
|
|
|
|
convert the separator to the correct character of the current operating
|
|
|
|
|
system.</p>
|
|
|
|
|
<p>Wherever path-like values need to be specified, a nested element can
|
|
|
|
|
be used. This takes the general form of:</p>
|
|
|
|
|
<pre>
|
|
|
|
|
<classpath>
|
|
|
|
|
<pathelement path="${classpath}"/>
|
|
|
|
|
<pathelement location="lib/helper.jar"/>
|
|
|
|
|
</classpath>
|
|
|
|
|
</pre>
|
|
|
|
|
<p>The <code>location</code> attribute specifies a single file or
|
|
|
|
|
directory relative to the project's base directory (or an absolute
|
|
|
|
|
filename), while the <code>path</code> attribute accepts colon-
|
|
|
|
|
or semicolon-separated lists of locations. The <code>path</code>
|
2001-03-09 08:54:35 +00:00
|
|
|
attribute is intended to be used with predefined paths - in any other
|
2001-02-13 12:32:01 +00:00
|
|
|
case, multiple elements with <code>location</code> attributes should be
|
|
|
|
|
preferred.</p>
|
|
|
|
|
<p>As a shortcut, the <code><classpath></code> tag
|
|
|
|
|
supports <code>path</code> and
|
|
|
|
|
<code>location</code> attributes of its own, so:</p>
|
|
|
|
|
<pre>
|
|
|
|
|
<classpath>
|
|
|
|
|
<pathelement path="${classpath}"/>
|
|
|
|
|
</classpath>
|
|
|
|
|
</pre>
|
2001-08-30 13:23:14 +00:00
|
|
|
<p>can be abbreviated to:</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<pre>
|
|
|
|
|
<classpath path="${classpath}"/>
|
|
|
|
|
</pre>
|
2002-03-30 21:37:41 +00:00
|
|
|
<p>In addition, <a href="CoreTypes/dirset.html">DirSet</a>s,
|
|
|
|
|
<a href="CoreTypes/fileset.html">FileSet</a>s, and
|
|
|
|
|
<a href="CoreTypes/filelist.html">FileList</a>s
|
|
|
|
|
can be specified via nested <code><dirset></code>,
|
|
|
|
|
<code><fileset></code>, and <code><filelist></code>
|
|
|
|
|
elements, respectively. <em>Note</em>: The order in which the files
|
|
|
|
|
building up a FileSet are added to the path-like structure is not
|
2001-02-13 12:32:01 +00:00
|
|
|
defined.</p>
|
|
|
|
|
<pre>
|
|
|
|
|
<classpath>
|
|
|
|
|
<pathelement path="${classpath}"/>
|
|
|
|
|
<fileset dir="lib">
|
|
|
|
|
<include name="**/*.jar"/>
|
|
|
|
|
</fileset>
|
|
|
|
|
<pathelement location="classes"/>
|
2002-03-30 21:37:41 +00:00
|
|
|
<dirset dir="${build.dir}">
|
|
|
|
|
<include name="apps/**/classes"/>
|
|
|
|
|
<exclude name="apps/**/*Test*"/>
|
|
|
|
|
</dirset>
|
|
|
|
|
<filelist refid="third-party_jars">
|
2001-02-13 12:32:01 +00:00
|
|
|
</classpath>
|
|
|
|
|
</pre>
|
2001-05-03 13:01:34 +00:00
|
|
|
<p>This builds a path that holds the value of <code>${classpath}</code>,
|
2002-03-30 21:37:41 +00:00
|
|
|
followed by all jar files in the <code>lib</code> directory,
|
|
|
|
|
the <code>classes</code> directory, all directories named
|
|
|
|
|
<code>classes</code> under the <code>apps</code> subdirectory of
|
|
|
|
|
<code>${build.dir}</code>, except those
|
|
|
|
|
that have the text <code>Test</code> in their name, and
|
|
|
|
|
the files specified in the referenced FileList.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>If you want to use the same path-like structure for several tasks,
|
|
|
|
|
you can define them with a <code><path></code> element at the
|
|
|
|
|
same level as <i>target</i>s, and reference them via their
|
2001-03-09 08:54:35 +00:00
|
|
|
<i>id</i> attribute - see <a href="#references">References</a> for an
|
2001-02-13 12:32:01 +00:00
|
|
|
example.</p>
|
|
|
|
|
<p>A path-like structure can include a reference to another path-like
|
|
|
|
|
structure via nested <code><path></code> elements:</p>
|
|
|
|
|
<pre>
|
|
|
|
|
<path id="base.path">
|
|
|
|
|
<pathelement path="${classpath}"/>
|
|
|
|
|
<fileset dir="lib">
|
|
|
|
|
<include name="**/*.jar"/>
|
|
|
|
|
</fileset>
|
|
|
|
|
<pathelement location="classes"/>
|
|
|
|
|
</path>
|
|
|
|
|
|
|
|
|
|
<path id="tests.path">
|
|
|
|
|
<path refid="base.path"/>
|
|
|
|
|
<pathelement location="testclasses"/>
|
|
|
|
|
</path>
|
|
|
|
|
</pre>
|
|
|
|
|
The shortcuts previously mentioned for <code><classpath></code> are also valid for <code><path></code>.For example:
|
|
|
|
|
<pre>
|
|
|
|
|
<path id="base.path">
|
|
|
|
|
<pathelement path="${classpath}"/>
|
|
|
|
|
</path>
|
|
|
|
|
</pre>
|
|
|
|
|
can be written as:
|
|
|
|
|
<pre>
|
|
|
|
|
<path id="base.path" path="${classpath}"/>
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<h3><a name="arg">Command-line Arguments</a></h3>
|
|
|
|
|
<p>Several tasks take arguments that will be passed to another
|
|
|
|
|
process on the command line. To make it easier to specify arguments
|
|
|
|
|
that contain space characters, nested <code>arg</code> elements can be used.</p>
|
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="12%" valign="top"><b>Attribute</b></td>
|
|
|
|
|
<td width="78%" valign="top"><b>Description</b></td>
|
|
|
|
|
<td width="10%" valign="top"><b>Required</b></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2002-02-04 20:57:49 +00:00
|
|
|
<td valign="top">value</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
<td valign="top">a single command-line argument; can contain space
|
|
|
|
|
characters.</td>
|
|
|
|
|
<td align="center" rowspan="4">Exactly one of these.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2002-02-04 20:57:49 +00:00
|
|
|
<td valign="top">line</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
<td valign="top">a space-delimited list of command-line arguments.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2002-02-04 20:57:49 +00:00
|
|
|
<td valign="top">file</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
<td valign="top">The name of a file as a single command-line
|
|
|
|
|
argument; will be replaced with the absolute filename of the file.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2002-02-04 20:57:49 +00:00
|
|
|
<td valign="top">path</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
<td valign="top">A string that will be treated as a path-like
|
|
|
|
|
string as a single command-line argument; you can use <code>;</code>
|
|
|
|
|
or <code>:</code> as
|
|
|
|
|
path separators and Ant will convert it to the platform's local
|
|
|
|
|
conventions.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
<h4>Examples</h4>
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<arg value="-l -a"/>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
<p>is a single command-line argument containing a space character.</p>
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<arg line="-l -a"/>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
<p>represents two separate command-line arguments.</p>
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<arg path="/dir;/dir2:\dir3"/>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
<p>is a single command-line argument with the value
|
|
|
|
|
<code>\dir;\dir2;\dir3</code> on DOS-based systems and
|
|
|
|
|
<code>/dir:/dir2:/dir3</code> on Unix-like systems.</p>
|
|
|
|
|
|
|
|
|
|
<h3><a name="references">References</a></h3>
|
|
|
|
|
<p>The <code>id</code> attribute of the buildfile's elements can be
|
2001-12-13 17:16:26 +00:00
|
|
|
used to refer to them. This can be useful if you are going to replicate
|
2001-03-09 08:54:35 +00:00
|
|
|
the same snippet of XML over and over again - using a
|
2001-12-13 17:16:26 +00:00
|
|
|
<code><classpath></code> structure more than once, for
|
2001-02-13 12:32:01 +00:00
|
|
|
example.</p>
|
|
|
|
|
<p>The following example:</p>
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<project ... >
|
|
|
|
|
<target ... >
|
|
|
|
|
<rmic ...>
|
|
|
|
|
<classpath>
|
|
|
|
|
<pathelement location="lib/"/>
|
|
|
|
|
<pathelement path="${java.class.path}/"/>
|
|
|
|
|
<pathelement path="${additional.path}"/>
|
|
|
|
|
</classpath>
|
|
|
|
|
</rmic>
|
|
|
|
|
</target>
|
|
|
|
|
|
|
|
|
|
<target ... >
|
|
|
|
|
<javac ...>
|
|
|
|
|
<classpath>
|
|
|
|
|
<pathelement location="lib/"/>
|
|
|
|
|
<pathelement path="${java.class.path}/"/>
|
|
|
|
|
<pathelement path="${additional.path}"/>
|
|
|
|
|
</classpath>
|
|
|
|
|
</javac>
|
|
|
|
|
</target>
|
|
|
|
|
</project>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
<p>could be rewritten as:</p>
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<project ... >
|
|
|
|
|
<path id="project.class.path">
|
|
|
|
|
<pathelement location="lib/"/>
|
|
|
|
|
<pathelement path="${java.class.path}/"/>
|
|
|
|
|
<pathelement path="${additional.path}"/>
|
|
|
|
|
</path>
|
|
|
|
|
|
|
|
|
|
<target ... >
|
|
|
|
|
<rmic ...>
|
|
|
|
|
<classpath refid="project.class.path"/>
|
|
|
|
|
</rmic>
|
|
|
|
|
</target>
|
|
|
|
|
|
|
|
|
|
<target ... >
|
|
|
|
|
<javac ...>
|
|
|
|
|
<classpath refid="project.class.path"/>
|
|
|
|
|
</javac>
|
|
|
|
|
</target>
|
|
|
|
|
</project>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
<p>All tasks that use nested elements for <a
|
|
|
|
|
href="CoreTypes/patternset.html">PatternSet</a>s, <a href="CoreTypes/fileset.html">FileSet</a>s or
|
|
|
|
|
<a href="#path">path-like structures</a> accept references to these
|
|
|
|
|
structures as well.</p>
|
|
|
|
|
|
|
|
|
|
<hr>
|
2002-02-04 20:57:49 +00:00
|
|
|
<p align="center">Copyright © 2001-2002 Apache Software Foundation. All rights
|
2001-02-13 12:32:01 +00:00
|
|
|
Reserved.</p>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
|
