docs/manual/using.html - ant - Git at Google

 <html>

 <head>
 <meta http-equiv="Content-Language" content="en-us">
 <title>Ant User Manual</title>
 </head>

 <body>
 <h1>Using Ant</h1>
 <h2><a name="buildfile">Writing a Simple Buildfile</a></h2>
 <p>Ant's buildfiles are written in XML. Each buildfile contains one project.</p>
 <p>Each task element of the buildfile can have an <code>id</code> attribute and
 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>
 <h3>Projects</h3>
 <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 &quot;basedir&quot;
       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>
 <p>Optionally, a description for the project can be provided as a
 top-level &lt;description&gt; element (see the <a
 href="CoreTypes/description.html">description</a> type).</p>

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

 <h3>Targets</h3>
 <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
 only specifies the <i>order</i> in which targets should be executed - it
 does not affect whether the target that specifies the dependency(s) gets
 executed if the dependent target(s) did not (need to) run.
 </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>&lt;target name=&quot;A&quot;/&gt;
 &lt;target name=&quot;B&quot; depends=&quot;A&quot;/&gt;
 &lt;target name=&quot;C&quot; depends=&quot;B&quot;/&gt;
 &lt;target name=&quot;D&quot; depends=&quot;C,B,A&quot;/&gt;</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>&lt;target name=&quot;build-module-A&quot; if=&quot;module-A-present&quot;/&gt;</pre>
   <pre>&lt;target name=&quot;build-own-fake-module-A&quot; unless=&quot;module-A-present&quot;/&gt;</pre>
 </blockquote>
 <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
 <nobr><code>-projecthelp</code></nobr> command-line option.</p>
 <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
 have the name &quot;init&quot;.</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 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>
     <td valign="top">the name of the property that must not be set in order
       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>

 <a name="tasks">
 <h3>Tasks</h3>
 </a>
 <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>&lt;<i>name</i> <i>attribute1</i>=&quot;<i>value1</i>&quot; <i>attribute2</i>=&quot;<i>value2</i>&quot; ... /&gt;</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>
 <p>There is a set of <a href="coretasklist.html" target="navFrame">built-in tasks</a>, along with a
 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>&lt;<i>taskname</i> id="<i>taskID</i>" ... /&gt;</pre>
 </blockquote>
 where <i>taskname</i> is the name of the task, and <i>taskID</i> is
 a unique name for this task.
 You can refer to the
 corresponding task object in scripts or other tasks via this name.
 For example, in scripts you could do:
 <blockquote>
 <pre>
 &lt;script ... &gt;
   task1.setFoo("bar");
 &lt;/script&gt;
 </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>
 Note<sup>1</sup>: If "task1" has not been run yet, then
 it has not been configured (ie., no attributes have been set), and if it is
 going to be configured later, anything you've done to the instance may
 be overwritten.
 </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>

 <h3>Properties</h3>
 <p>A project can have a set of properties. These might be set in the buildfile
 by the <a href="CoreTasks/property.html">property task</a>, or might be set outside Ant. A
 property has a name and a value. Properties may be used in the value of
 task attributes. This is done by placing the property name between
 &quot;<code>${</code>&quot; and &quot;<code>}</code>&quot; in the
 attribute value. For example,
 if there is a &quot;builddir&quot; property with the value
 &quot;build&quot;, then this could be used in an attribute like this:
 <code>${builddir}/classes</code>.
 This is resolved as <code>build/classes</code>.</p>

 <h3><a name="built-in-props">Built-in Properties</a></h3>
 <p>Ant provides access to all system properties as if they had been
 defined using a <code>&lt;property&gt;</code> task.
 For example, <code>${os.name}</code> expands to the
 name of the operating system.</p>
 <p>For a list of system properties see
 <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
 <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 &lt;project&gt;).
 ant.file            the absolute path of the buildfile.
 ant.version         the version of Ant
 ant.project.name    the name of the project that is currently executing;
                     it is set in the name attribute of &lt;project&gt;.
 ant.java.version    the JVM version Ant detected; currently it can hold
                     the values &quot;1.1&quot;, &quot;1.2&quot;, &quot;1.3&quot; and &quot;1.4&quot;.
 </pre>

 <h3>Example</h3>
 <pre>
 &lt;project name=&quot;MyProject&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;

   &lt;!-- set global properties for this build --&gt;
   &lt;property name=&quot;src&quot; value=&quot;.&quot;/&gt;
   &lt;property name=&quot;build&quot; value=&quot;build&quot;/&gt;
   &lt;property name=&quot;dist&quot;  value=&quot;dist&quot;/&gt;

   &lt;target name=&quot;init&quot;&gt;
     &lt;!-- Create the time stamp --&gt;
     &lt;tstamp/&gt;
     &lt;!-- Create the build directory structure used by compile --&gt;
     &lt;mkdir dir=&quot;${build}&quot;/&gt;
   &lt;/target&gt;

   &lt;target name=&quot;compile&quot; depends=&quot;init&quot;&gt;
     &lt;!-- Compile the java code from ${src} into ${build} --&gt;
     &lt;javac srcdir=&quot;${src}&quot; destdir=&quot;${build}&quot;/&gt;
   &lt;/target&gt;

   &lt;target name=&quot;dist&quot; depends=&quot;compile&quot;&gt;
     &lt;!-- Create the distribution directory --&gt;
     &lt;mkdir dir=&quot;${dist}/lib&quot;/&gt;

     &lt;!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --&gt;
     &lt;jar jarfile=&quot;${dist}/lib/MyProject-${DSTAMP}.jar&quot; basedir=&quot;${build}&quot;/&gt;
   &lt;/target&gt;

   &lt;target name=&quot;clean&quot;&gt;
     &lt;!-- Delete the ${build} and ${dist} directory trees --&gt;
     &lt;delete dir=&quot;${build}&quot;/&gt;
     &lt;delete dir=&quot;${dist}&quot;/&gt;
   &lt;/target&gt;
 &lt;/project&gt;
 </pre>

 <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="CoreTasks/filter.html">filter task</a>.&nbsp;</p>
 <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
 in the filter task. This token syntax matches the syntax of other build systems
 that perform such filtering and remains sufficiently orthogonal to most
 programming and scripting languages, as well as with documentation systems.</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
 method is available - but as long as you choose appropriate names for your
 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
 &quot;<code>:</code>&quot; and &quot;<code>;</code>&quot; 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>
     &lt;classpath&gt;
       &lt;pathelement path=&quot;${classpath}&quot;/&gt;
       &lt;pathelement location=&quot;lib/helper.jar&quot;/&gt;
     &lt;/classpath&gt;
 </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>
 attribute is intended to be used with predefined paths - in any other
 case, multiple elements with <code>location</code> attributes should be
 preferred.</p>
 <p>As a shortcut, the <code>&lt;classpath&gt;</code> tag
 supports <code>path</code> and
 <code>location</code> attributes of its own, so:</p>
 <pre>
     &lt;classpath&gt;
       &lt;pathelement path=&quot;${classpath}&quot;/&gt;
     &lt;/classpath&gt;
 </pre>
 <p>can be abbreviated to:</p>
 <pre>
     &lt;classpath path=&quot;${classpath}&quot;/&gt;
 </pre>
 <p>In addition, <a href="CoreTypes/fileset.html">FileSet</a>s can be specified via
 nested <code>&lt;fileset&gt;</code> elements. The order in which the files
 building up a fileset are added to the path-like structure is not
 defined.</p>
 <pre>
     &lt;classpath&gt;
       &lt;pathelement path=&quot;${classpath}&quot;/&gt;
       &lt;fileset dir=&quot;lib&quot;&gt;
         &lt;include name=&quot;**/*.jar&quot;/&gt;
       &lt;/fileset&gt;
       &lt;pathelement location=&quot;classes&quot;/&gt;
     &lt;/classpath&gt;
 </pre>
 <p>This builds a path that holds the value of <code>${classpath}</code>,
 followed by all jar files in the <code>lib</code> directory, followed
 by the <code>classes</code> directory.</p>
 <p>If you want to use the same path-like structure for several tasks,
 you can define them with a <code>&lt;path&gt;</code> element at the
 same level as <i>target</i>s, and reference them via their
 <i>id</i> attribute - see <a href="#references">References</a> for an
 example.</p>
 <p>A path-like structure can include a reference to another path-like
 structure via nested <code>&lt;path&gt;</code> elements:</p>
 <pre>
     &lt;path id=&quot;base.path&quot;&gt;
       &lt;pathelement path=&quot;${classpath}&quot;/&gt;
       &lt;fileset dir=&quot;lib&quot;&gt;
         &lt;include name=&quot;**/*.jar&quot;/&gt;
       &lt;/fileset&gt;
       &lt;pathelement location=&quot;classes&quot;/&gt;
     &lt;/path&gt;

     &lt;path id=&quot;tests.path&quot;&gt;
       &lt;path refid=&quot;base.path&quot;/&gt;
       &lt;pathelement location=&quot;testclasses&quot;/&gt;
     &lt;/path&gt;
 </pre>
  The shortcuts previously mentioned for <code>&lt;classpath&gt;</code> are also valid for <code>&lt;path&gt;</code>.For example:
 <pre>
     &lt;path id=&quot;base.path&quot;&gt;
       &lt;pathelement path=&quot;${classpath}&quot;/&gt;
     &lt;/path&gt;
 </pre>
 can be written as:
 <pre>
     &lt;path id=&quot;base.path&quot; path=&quot;${classpath}&quot;/&gt;
 </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>
     <td valign="top">value</td>
     <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>
     <td valign="top">line</td>
     <td valign="top">a space-delimited list of command-line arguments.</td>
   </tr>
   <tr>
     <td valign="top">file</td>
     <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>
     <td valign="top">path</td>
     <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>
   &lt;arg value=&quot;-l -a&quot;/&gt;
 </pre></blockquote>
 <p>is a single command-line argument containing a space character.</p>
 <blockquote><pre>
   &lt;arg line=&quot;-l -a&quot;/&gt;
 </pre></blockquote>
 <p>represents two separate command-line arguments.</p>
 <blockquote><pre>
   &lt;arg path=&quot;/dir;/dir2:\dir3&quot;/&gt;
 </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
 used to refer to them. This can useful if you are going to replicate
 the same snippet of XML over and over again - using a
 <code>&lt;classpath&gt;</code> structure more than once for
 example.</p>
 <p>The following example:</p>
 <blockquote><pre>
 &lt;project ... &gt;
   &lt;target ... &gt;
     &lt;rmic ...&gt;
       &lt;classpath&gt;
         &lt;pathelement location=&quot;lib/&quot;/&gt;
         &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;
         &lt;pathelement path=&quot;${additional.path}&quot;/&gt;
       &lt;/classpath&gt;
     &lt;/rmic&gt;
   &lt;/target&gt;

   &lt;target ... &gt;
     &lt;javac ...&gt;
       &lt;classpath&gt;
         &lt;pathelement location=&quot;lib/&quot;/&gt;
         &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;
         &lt;pathelement path=&quot;${additional.path}&quot;/&gt;
       &lt;/classpath&gt;
     &lt;/javac&gt;
   &lt;/target&gt;
 &lt;/project&gt;
 </pre></blockquote>
 <p>could be rewritten as:</p>
 <blockquote><pre>
 &lt;project ... &gt;
   &lt;path id=&quot;project.class.path&quot;&gt;
     &lt;pathelement location=&quot;lib/&quot;/&gt;
     &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;
     &lt;pathelement path=&quot;${additional.path}&quot;/&gt;
   &lt;/path&gt;

   &lt;target ... &gt;
     &lt;rmic ...&gt;
       &lt;classpath refid=&quot;project.class.path&quot;/&gt;
     &lt;/rmic&gt;
   &lt;/target&gt;

   &lt;target ... &gt;
     &lt;javac ...&gt;
       &lt;classpath refid=&quot;project.class.path&quot;/&gt;
     &lt;/javac&gt;
   &lt;/target&gt;
 &lt;/project&gt;
 </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>
 <p align="center">Copyright &copy; 2000,2001 Apache Software Foundation. All rights
 Reserved.</p>

 </body>
 </html>
	<html>

	<head>
	<meta http-equiv="Content-Language" content="en-us">
	<title>Ant User Manual</title>
	</head>

	<body>
	<h1>Using Ant</h1>
	<h2><a name="buildfile">Writing a Simple Buildfile</a></h2>
	<p>Ant's buildfiles are written in XML. Each buildfile contains one project.</p>
	<p>Each task element of the buildfile can have an <code>id</code> attribute and
	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>
	<h3>Projects</h3>
	<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>
	<p>Optionally, a description for the project can be provided as a
	top-level <description> element (see the <a
	href="CoreTypes/description.html">description</a> type).</p>

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

	<h3>Targets</h3>
	<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
	only specifies the <i>order</i> in which targets should be executed - it
	does not affect whether the target that specifies the dependency(s) gets
	executed if the dependent target(s) did not (need to) run.
	</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>
	<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
	<nobr><code>-projecthelp</code></nobr> command-line option.</p>
	<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
	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 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>
	<td valign="top">the name of the property that must not be set in order
	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>

	<a name="tasks">
	<h3>Tasks</h3>
	</a>
	<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>
	<p>There is a set of <a href="coretasklist.html" target="navFrame">built-in tasks</a>, along with a
	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
	a unique name for this task.
	You can refer to the
	corresponding task object in scripts or other tasks via this name.
	For example, in scripts you could do:
	<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>
	Note<sup>1</sup>: If "task1" has not been run yet, then
	it has not been configured (ie., no attributes have been set), and if it is
	going to be configured later, anything you've done to the instance may
	be overwritten.
	</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>

	<h3>Properties</h3>
	<p>A project can have a set of properties. These might be set in the buildfile
	by the <a href="CoreTasks/property.html">property task</a>, or might be set outside Ant. A
	property has a name and a value. Properties may be used in the value of
	task attributes. This is done by placing the property name between
	"<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>.
	This is resolved as <code>build/classes</code>.</p>

	<h3><a name="built-in-props">Built-in Properties</a></h3>
	<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>
	<p>For a list of system properties see
	<a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
	<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.
	ant.version the version of Ant
	ant.project.name the name of the project that is currently executing;
	it is set in the name attribute of <project>.
	ant.java.version the JVM version Ant detected; currently it can hold
	the values "1.1", "1.2", "1.3" and "1.4".
	</pre>

	<h3>Example</h3>
	<pre>
	<project name="MyProject" default="dist" basedir=".">

	<!-- set global properties for this build -->
	<property name="src" value="."/>
	<property name="build" value="build"/>
	<property name="dist" value="dist"/>

	<target name="init">
	<!-- Create the time stamp -->
	<tstamp/>
	<!-- Create the build directory structure used by compile -->
	<mkdir dir="${build}"/>
	</target>

	<target name="compile" depends="init">
	<!-- Compile the java code from ${src} into ${build} -->
	<javac srcdir="${src}" destdir="${build}"/>
	</target>

	<target name="dist" depends="compile">
	<!-- Create the distribution directory -->
	<mkdir dir="${dist}/lib"/>

	<!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
	<jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
	</target>

	<target name="clean">
	<!-- Delete the ${build} and ${dist} directory trees -->
	<delete dir="${build}"/>
	<delete dir="${dist}"/>
	</target>
	</project>
	</pre>

	<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="CoreTasks/filter.html">filter task</a>. </p>
	<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
	in the filter task. This token syntax matches the syntax of other build systems
	that perform such filtering and remains sufficiently orthogonal to most
	programming and scripting languages, as well as with documentation systems.</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
	method is available - but as long as you choose appropriate names for your
	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>
	attribute is intended to be used with predefined paths - in any other
	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>
	<p>can be abbreviated to:</p>
	<pre>
	<classpath path="${classpath}"/>
	</pre>
	<p>In addition, <a href="CoreTypes/fileset.html">FileSet</a>s can be specified via
	nested <code><fileset></code> elements. The order in which the files
	building up a fileset are added to the path-like structure is not
	defined.</p>
	<pre>
	<classpath>
	<pathelement path="${classpath}"/>
	<fileset dir="lib">
	<include name="*/.jar"/>
	</fileset>
	<pathelement location="classes"/>
	</classpath>
	</pre>
	<p>This builds a path that holds the value of <code>${classpath}</code>,
	followed by all jar files in the <code>lib</code> directory, followed
	by the <code>classes</code> directory.</p>
	<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
	<i>id</i> attribute - see <a href="#references">References</a> for an
	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>
	<td valign="top">value</td>
	<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>
	<td valign="top">line</td>
	<td valign="top">a space-delimited list of command-line arguments.</td>
	</tr>
	<tr>
	<td valign="top">file</td>
	<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>
	<td valign="top">path</td>
	<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
	used to refer to them. This can useful if you are going to replicate
	the same snippet of XML over and over again - using a
	<code><classpath></code> structure more than once for
	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>
	<p align="center">Copyright © 2000,2001 Apache Software Foundation. All rights
	Reserved.</p>

	</body>
	</html>