| 1 | <!--
|
|---|
| 2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
|---|
| 3 | contributor license agreements. See the NOTICE file distributed with
|
|---|
| 4 | this work for additional information regarding copyright ownership.
|
|---|
| 5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
|---|
| 6 | (the "License"); you may not use this file except in compliance with
|
|---|
| 7 | the License. You may obtain a copy of the License at
|
|---|
| 8 |
|
|---|
| 9 | http://www.apache.org/licenses/LICENSE-2.0
|
|---|
| 10 |
|
|---|
| 11 | Unless required by applicable law or agreed to in writing, software
|
|---|
| 12 | distributed under the License is distributed on an "AS IS" BASIS,
|
|---|
| 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|---|
| 14 | See the License for the specific language governing permissions and
|
|---|
| 15 | limitations under the License.
|
|---|
| 16 | -->
|
|---|
| 17 | <html>
|
|---|
| 18 |
|
|---|
| 19 | <head>
|
|---|
| 20 | <meta http-equiv="Content-Language" content="en-us">
|
|---|
| 21 | <link rel="stylesheet" type="text/css" href="stylesheets/style.css">
|
|---|
| 22 | <title>Writing a Simple Buildfile</title>
|
|---|
| 23 | </head>
|
|---|
| 24 |
|
|---|
| 25 | <body>
|
|---|
| 26 | <h1>Using Ant</h1>
|
|---|
| 27 | <h2><a name="buildfile">Writing a Simple Buildfile</a></h2>
|
|---|
| 28 | <p>Ant's buildfiles are written in XML. Each buildfile contains one project
|
|---|
| 29 | and at least one (default) target. Targets contain task elements.
|
|---|
| 30 | Each task element of the buildfile can have an <code>id</code> attribute and
|
|---|
| 31 | can later be referred to by the value supplied to this. The value has
|
|---|
| 32 | to be unique. (For additional information, see the
|
|---|
| 33 | <a href="#tasks"> Tasks</a> section below.)</p>
|
|---|
| 34 | <h3><a name="projects">Projects</a></h3>
|
|---|
| 35 | <p>A <i>project</i> has three attributes:</p>
|
|---|
| 36 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 37 | <tr>
|
|---|
| 38 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 39 | <td valign="top"><b>Description</b></td>
|
|---|
| 40 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 41 | </tr>
|
|---|
| 42 | <tr>
|
|---|
| 43 | <td valign="top">name</td>
|
|---|
| 44 | <td valign="top">the name of the project.</td>
|
|---|
| 45 | <td align="center" valign="top">No</td>
|
|---|
| 46 | </tr>
|
|---|
| 47 | <tr>
|
|---|
| 48 | <td valign="top">default</td>
|
|---|
| 49 | <td valign="top">the default target to use when no target is supplied.</td>
|
|---|
| 50 | <td align="center" valign="top">No; however, <b>since Ant 1.6.0</b>,
|
|---|
| 51 | every project includes an implicit target that contains any and
|
|---|
| 52 | all top-level tasks and/or types. This target will always be
|
|---|
| 53 | executed as part of the project's initialization, even when Ant is
|
|---|
| 54 | run with the <a href="running.html#options">-projecthelp</a> option.
|
|---|
| 55 | </td>
|
|---|
| 56 | </tr>
|
|---|
| 57 | <tr>
|
|---|
| 58 | <td valign="top">basedir</td>
|
|---|
| 59 | <td valign="top">the base directory from which all path calculations are
|
|---|
| 60 | done. This attribute might be overridden by setting
|
|---|
| 61 | the "basedir"
|
|---|
| 62 | property beforehand. When this is done, it must be omitted in the
|
|---|
| 63 | project tag. If neither the attribute nor the property have
|
|---|
| 64 | been set, the parent directory of the buildfile will be used.</td>
|
|---|
| 65 | <td align="center" valign="top">No</td>
|
|---|
| 66 | </tr>
|
|---|
| 67 | </table>
|
|---|
| 68 | <p>Optionally, a description for the project can be provided as a
|
|---|
| 69 | top-level <code><description></code> element (see the <a
|
|---|
| 70 | href="CoreTypes/description.html">description</a> type).</p>
|
|---|
| 71 |
|
|---|
| 72 | <p>Each project defines one or more <i>targets</i>.
|
|---|
| 73 | A target is a set of <i>tasks</i> you want
|
|---|
| 74 | to be executed. When starting Ant, you can select which target(s) you
|
|---|
| 75 | want to have executed. When no target is given,
|
|---|
| 76 | the project's default is used.</p>
|
|---|
| 77 |
|
|---|
| 78 | <h3><a name="targets">Targets</a></h3>
|
|---|
| 79 | <p>A target can depend on other targets. You might have a target for compiling,
|
|---|
| 80 | for example, and a target for creating a distributable. You can only build a
|
|---|
| 81 | distributable when you have compiled first, so the distribute target
|
|---|
| 82 | <i>depends on</i> the compile target. Ant resolves these dependencies.</p>
|
|---|
| 83 | <p>It should be noted, however, that Ant's <code>depends</code> attribute
|
|---|
| 84 | only specifies the <i>order</i> in which targets should be executed - it
|
|---|
| 85 | does not affect whether the target that specifies the dependency(s) gets
|
|---|
| 86 | executed if the dependent target(s) did not (need to) run.
|
|---|
| 87 | </p>
|
|---|
| 88 | <p>Ant tries to execute the targets in the <code>depends</code>
|
|---|
| 89 | attribute in the order
|
|---|
| 90 | they appear (from left to right). Keep in mind that it is possible that a target
|
|---|
| 91 | can get executed earlier when an earlier target depends on it:</p>
|
|---|
| 92 | <blockquote>
|
|---|
| 93 | <pre><target name="A"/>
|
|---|
| 94 | <target name="B" depends="A"/>
|
|---|
| 95 | <target name="C" depends="B"/>
|
|---|
| 96 | <target name="D" depends="C,B,A"/></pre>
|
|---|
| 97 | </blockquote>
|
|---|
| 98 | <p>Suppose we want to execute target D. From its
|
|---|
| 99 | <code>depends</code> attribute, you
|
|---|
| 100 | might think that first target C, then B and then A is executed.
|
|---|
| 101 | Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.</p>
|
|---|
| 102 | <p>In a chain of dependencies stretching back from a given target such
|
|---|
| 103 | as D above, each target gets executed only once, even when more than
|
|---|
| 104 | one target depends on it. Thus, executing the D target will first
|
|---|
| 105 | result in C being called, which in turn will first call B, which in
|
|---|
| 106 | turn will first call A. After A, then B, then C have executed,
|
|---|
| 107 | execution returns to the dependency list of D, which will <u>not</u>
|
|---|
| 108 | call B and A, since they were already called in process of dependency
|
|---|
| 109 | resolution for C and B respectively as dependencies of D. Had no such
|
|---|
| 110 | dependencies been discovered in processing C and B, B and A would
|
|---|
| 111 | have been executed after C in processing D's dependency list.</p>
|
|---|
| 112 | <p>A target also has the ability to perform its execution if (or
|
|---|
| 113 | unless) a property has been set. This allows, for example, better
|
|---|
| 114 | control on the building process depending on the state of the system
|
|---|
| 115 | (java version, OS, command-line property defines, etc.). To make a target
|
|---|
| 116 | <i>sense</i> this property, you should add the <code>if</code> (or
|
|---|
| 117 | <code>unless</code>) attribute with the name of the property that the target
|
|---|
| 118 | should react to. <strong>Note:</strong> Ant will only check whether
|
|---|
| 119 | the property has been set, the value doesn't matter. A property set
|
|---|
| 120 | to the empty string is still an existing property. For example:</p>
|
|---|
| 121 | <blockquote>
|
|---|
| 122 | <pre><target name="build-module-A" if="module-A-present"/></pre>
|
|---|
| 123 | <pre><target name="build-own-fake-module-A" unless="module-A-present"/></pre>
|
|---|
| 124 | </blockquote>
|
|---|
| 125 | <p>In the first example, if the <code>module-A-present</code>
|
|---|
| 126 | property is set (to any value, e.g. <i>false</i>), the target will be run. In the second
|
|---|
| 127 | example, if the <code>module-A-present</code> property is set
|
|---|
| 128 | (again, to any value), the target will not be run.
|
|---|
| 129 | </p>
|
|---|
| 130 | <p>Only one propertyname can be specified in the if/unless clause. If you want to check
|
|---|
| 131 | multiple conditions, you can use a dependend target for computing the result for the check:</p>
|
|---|
| 132 | <blockquote><pre>
|
|---|
| 133 | <target name="myTarget" depends="myTarget.check" if="myTarget.run">
|
|---|
| 134 | <echo>Files foo.txt and bar.txt are present.</echo>
|
|---|
| 135 | </target>
|
|---|
| 136 |
|
|---|
| 137 | <target name="myTarget.check">
|
|---|
| 138 | <condition property="myTarget.run">
|
|---|
| 139 | <and>
|
|---|
| 140 | <available file="foo.txt"/>
|
|---|
| 141 | <available file="bar.txt"/>
|
|---|
| 142 | </and>
|
|---|
| 143 | </condition>
|
|---|
| 144 | </target>
|
|---|
| 145 | </pre></blockquote>
|
|---|
| 146 | <p>If no <code>if</code> and no <code>unless</code> attribute is present,
|
|---|
| 147 | the target will always be executed.</p>
|
|---|
| 148 |
|
|---|
| 149 | <p>
|
|---|
| 150 | <b>Important:</b> the <code>if</code> and <code>unless</code> attributes only
|
|---|
| 151 | enable or disable the target to which they are attached. They do not control
|
|---|
| 152 | whether or not targets that a conditional target depends upon get executed.
|
|---|
| 153 | In fact, they do not even get evaluated until the target is about to be executed,
|
|---|
| 154 | and all its predecessors have already run.
|
|---|
| 155 |
|
|---|
| 156 | <p>The optional <code>description</code> attribute can be used to provide a one-line description of this target, which is printed by the
|
|---|
| 157 | <nobr><code>-projecthelp</code></nobr> command-line option. Targets
|
|---|
| 158 | without such a description are deemed internal and will not be listed,
|
|---|
| 159 | unless either the <nobr><code>-verbose</code></nobr> or
|
|---|
| 160 | <nobr><code>-debug</code></nobr> option is used.
|
|---|
| 161 | </p>
|
|---|
| 162 | <p>It is a good practice to place your <a
|
|---|
| 163 | href="CoreTasks/tstamp.html">tstamp</a> tasks in a so-called
|
|---|
| 164 | <i>initialization</i> target, on which
|
|---|
| 165 | all other targets depend. Make sure that target is always the first one in
|
|---|
| 166 | the depends list of the other targets. In this manual, most initialization targets
|
|---|
| 167 | have the name <code>"init"</code>.</p>
|
|---|
| 168 | <p>If the depends attribute and the if/unless attribute are set, the depends attribute is
|
|---|
| 169 | executed first.</p>
|
|---|
| 170 | <p>A target has the following attributes:</p>
|
|---|
| 171 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 172 | <tr>
|
|---|
| 173 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 174 | <td valign="top"><b>Description</b></td>
|
|---|
| 175 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 176 | </tr>
|
|---|
| 177 | <tr>
|
|---|
| 178 | <td valign="top">name</td>
|
|---|
| 179 | <td valign="top">the name of the target.</td>
|
|---|
| 180 | <td align="center" valign="top">Yes</td>
|
|---|
| 181 | </tr>
|
|---|
| 182 | <tr>
|
|---|
| 183 | <td valign="top">depends</td>
|
|---|
| 184 | <td valign="top">a comma-separated list of names of targets on which this
|
|---|
| 185 | target depends.</td>
|
|---|
| 186 | <td align="center" valign="top">No</td>
|
|---|
| 187 | </tr>
|
|---|
| 188 | <tr>
|
|---|
| 189 | <td valign="top">if</td>
|
|---|
| 190 | <td valign="top">the name of the property that must be set in order for this
|
|---|
| 191 | target to execute.</td>
|
|---|
| 192 | <td align="center" valign="top">No</td>
|
|---|
| 193 | </tr>
|
|---|
| 194 | <tr>
|
|---|
| 195 | <td valign="top">unless</td>
|
|---|
| 196 | <td valign="top">the name of the property that must not be set in order
|
|---|
| 197 | for this target to execute.</td>
|
|---|
| 198 | <td align="center" valign="top">No</td>
|
|---|
| 199 | </tr>
|
|---|
| 200 | <tr>
|
|---|
| 201 | <td valign="top">description</td>
|
|---|
| 202 | <td valign="top">a short description of this target's function.</td>
|
|---|
| 203 | <td align="center" valign="top">No</td>
|
|---|
| 204 | </tr>
|
|---|
| 205 | </table>
|
|---|
| 206 | </p>
|
|---|
| 207 |
|
|---|
| 208 | <p>A target name can be any alphanumeric string valid in the encoding of the XML
|
|---|
| 209 | file. The empty string "" is in this set, as is
|
|---|
| 210 | comma "," and space " ".
|
|---|
| 211 | Please avoid using these, as they will not be supported in future Ant versions
|
|---|
| 212 | because of all the confusion they cause. IDE support of unusual target names,
|
|---|
| 213 | or any target name containing spaces, varies with the IDE.</p>
|
|---|
| 214 |
|
|---|
| 215 | <p>Targets beginning with a hyphen such as <code>"-restart"</code>
|
|---|
| 216 | are valid, and can be used
|
|---|
| 217 | to name targets that should not be called directly from the command line.</p>
|
|---|
| 218 |
|
|---|
| 219 | <h3><a name="tasks">Tasks</a></h3>
|
|---|
| 220 | <p>A task is a piece of code that can be executed.</p>
|
|---|
| 221 | <p>A task can have multiple attributes (or arguments, if you prefer). The value
|
|---|
| 222 | of an attribute might contain references to a property. These references will be
|
|---|
| 223 | resolved before the task is executed.</p>
|
|---|
| 224 | <p>Tasks have a common structure:</p>
|
|---|
| 225 | <blockquote>
|
|---|
| 226 | <pre><<i>name</i> <i>attribute1</i>="<i>value1</i>" <i>attribute2</i>="<i>value2</i>" ... /></pre>
|
|---|
| 227 | </blockquote>
|
|---|
| 228 | <p>where <i>name</i> is the name of the task,
|
|---|
| 229 | <i>attributeN</i> is the attribute name, and
|
|---|
| 230 | <i>valueN</i> is the value for this attribute.</p>
|
|---|
| 231 | <p>There is a set of <a href="coretasklist.html" target="navFrame">built-in tasks</a>, along with a
|
|---|
| 232 | number of
|
|---|
| 233 | <a href="optionaltasklist.html" target="navFrame"> optional tasks</a>, but it is also very
|
|---|
| 234 | easy to <a href="develop.html#writingowntask">write your own</a>.</p>
|
|---|
| 235 | <p>All tasks share a task name attribute. The value of
|
|---|
| 236 | this attribute will be used in the logging messages generated by
|
|---|
| 237 | Ant.</p>
|
|---|
| 238 | Tasks can be assigned an <code>id</code> attribute:
|
|---|
| 239 | <blockquote>
|
|---|
| 240 | <pre><<i>taskname</i> id="<i>taskID</i>" ... /></pre>
|
|---|
| 241 | </blockquote>
|
|---|
| 242 | where <i>taskname</i> is the name of the task, and <i>taskID</i> is
|
|---|
| 243 | a unique identifier for this task.
|
|---|
| 244 | You can refer to the
|
|---|
| 245 | corresponding task object in scripts or other tasks via this name.
|
|---|
| 246 | For example, in scripts you could do:
|
|---|
| 247 | <blockquote>
|
|---|
| 248 | <pre>
|
|---|
| 249 | <script ... >
|
|---|
| 250 | task1.setFoo("bar");
|
|---|
| 251 | </script>
|
|---|
| 252 | </pre>
|
|---|
| 253 | </blockquote>
|
|---|
| 254 | to set the <code>foo</code> attribute of this particular task instance.
|
|---|
| 255 | In another task (written in Java), you can access the instance via
|
|---|
| 256 | <code>project.getReference("task1")</code>.
|
|---|
| 257 | <p>
|
|---|
| 258 | Note<sup>1</sup>: If "task1" has not been run yet, then
|
|---|
| 259 | it has not been configured (ie., no attributes have been set), and if it is
|
|---|
| 260 | going to be configured later, anything you've done to the instance may
|
|---|
| 261 | be overwritten.
|
|---|
| 262 | </p>
|
|---|
| 263 | <p>
|
|---|
| 264 | Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i>
|
|---|
| 265 | be backward-compatible with this behaviour, since there will likely be no
|
|---|
| 266 | task instances at all, only proxies.
|
|---|
| 267 | </p>
|
|---|
| 268 |
|
|---|
| 269 | <h3><a name="properties">Properties</a></h3>
|
|---|
| 270 | <p>A project can have a set of properties. These might be set in the buildfile
|
|---|
| 271 | by the <a href="CoreTasks/property.html">property</a> task, or might be set outside Ant. A
|
|---|
| 272 | property has a name and a value; the name is case-sensitive. Properties may be used in the value of
|
|---|
| 273 | task attributes. This is done by placing the property name between
|
|---|
| 274 | "<code>${</code>" and "<code>}</code>" in the
|
|---|
| 275 | attribute value. For example,
|
|---|
| 276 | if there is a "builddir" property with the value
|
|---|
| 277 | "build", then this could be used in an attribute like this:
|
|---|
| 278 | <code>${builddir}/classes</code>.
|
|---|
| 279 | This is resolved at run-time as <code>build/classes</code>.</p>
|
|---|
| 280 | <p>In the event you should need to include this construct literally
|
|---|
| 281 | (i.e. without property substitutions), simply "escape" the '$' character
|
|---|
| 282 | by doubling it. To continue the previous example:
|
|---|
| 283 | <pre> <echo>$${builddir}=${builddir}</echo></pre>
|
|---|
| 284 | will echo this message:
|
|---|
| 285 | <pre> ${builddir}=build/classes</pre></p>
|
|---|
| 286 | <p>In order to maintain backward compatibility with older Ant releases,
|
|---|
| 287 | a single '$' character encountered apart from a property-like construct
|
|---|
| 288 | (including a matched pair of french braces) will be interpreted literally;
|
|---|
| 289 | that is, as '$'. The "correct" way to specify this literal character,
|
|---|
| 290 | however, is by using the escaping mechanism unconditionally, so that "$$"
|
|---|
| 291 | is obtained by specifying "$$$$". Mixing the two approaches yields
|
|---|
| 292 | unpredictable results, as "$$$" results in "$$".</p>
|
|---|
| 293 |
|
|---|
| 294 | <h3><a name="built-in-props">Built-in Properties</a></h3>
|
|---|
| 295 | <p>Ant provides access to all system properties as if they had been
|
|---|
| 296 | defined using a <code><property></code> task.
|
|---|
| 297 | For example, <code>${os.name}</code> expands to the
|
|---|
| 298 | name of the operating system.</p>
|
|---|
| 299 | <p>For a list of system properties see
|
|---|
| 300 | <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/System.html#getProperties()">the Javadoc of System.getProperties</a>.
|
|---|
| 301 | </p>
|
|---|
| 302 | <p>In addition, Ant has some built-in properties:</p>
|
|---|
| 303 | <pre>
|
|---|
| 304 | basedir the absolute path of the project's basedir (as set
|
|---|
| 305 | with the basedir attribute of <a href="#projects"><project>)</a>.
|
|---|
| 306 | ant.file the absolute path of the buildfile.
|
|---|
| 307 | ant.version the version of Ant
|
|---|
| 308 | ant.project.name the name of the project that is currently executing;
|
|---|
| 309 | it is set in the name attribute of <project>.
|
|---|
| 310 | ant.java.version the JVM version Ant detected; currently it can hold
|
|---|
| 311 | the values "1.2", "1.3", "1.4" and "1.5".
|
|---|
| 312 | </pre>
|
|---|
| 313 | <p>There is also another property, but this is set by the launcher script and therefore
|
|---|
| 314 | maybe not set inside IDEs:</p>
|
|---|
| 315 | <pre>
|
|---|
| 316 | ant.home home directory of Ant
|
|---|
| 317 | </pre>
|
|---|
| 318 |
|
|---|
| 319 | <a name="example"><h3>Example Buildfile</h3></a>
|
|---|
| 320 | <pre>
|
|---|
| 321 | <project name="MyProject" default="dist" basedir=".">
|
|---|
| 322 | <description>
|
|---|
| 323 | simple example build file
|
|---|
| 324 | </description>
|
|---|
| 325 | <!-- set global properties for this build -->
|
|---|
| 326 | <property name="src" location="src"/>
|
|---|
| 327 | <property name="build" location="build"/>
|
|---|
| 328 | <property name="dist" location="dist"/>
|
|---|
| 329 |
|
|---|
| 330 | <target name="init">
|
|---|
| 331 | <!-- Create the time stamp -->
|
|---|
| 332 | <tstamp/>
|
|---|
| 333 | <!-- Create the build directory structure used by compile -->
|
|---|
| 334 | <mkdir dir="${build}"/>
|
|---|
| 335 | </target>
|
|---|
| 336 |
|
|---|
| 337 | <target name="compile" depends="init"
|
|---|
| 338 | description="compile the source " >
|
|---|
| 339 | <!-- Compile the java code from ${src} into ${build} -->
|
|---|
| 340 | <javac srcdir="${src}" destdir="${build}"/>
|
|---|
| 341 | </target>
|
|---|
| 342 |
|
|---|
| 343 | <target name="dist" depends="compile"
|
|---|
| 344 | description="generate the distribution" >
|
|---|
| 345 | <!-- Create the distribution directory -->
|
|---|
| 346 | <mkdir dir="${dist}/lib"/>
|
|---|
| 347 |
|
|---|
| 348 | <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
|
|---|
| 349 | <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
|
|---|
| 350 | </target>
|
|---|
| 351 |
|
|---|
| 352 | <target name="clean"
|
|---|
| 353 | description="clean up" >
|
|---|
| 354 | <!-- Delete the ${build} and ${dist} directory trees -->
|
|---|
| 355 | <delete dir="${build}"/>
|
|---|
| 356 | <delete dir="${dist}"/>
|
|---|
| 357 | </target>
|
|---|
| 358 | </project>
|
|---|
| 359 | </pre>
|
|---|
| 360 |
|
|---|
| 361 | <p>Notice that we are declaring properties outside any target. As of
|
|---|
| 362 | Ant 1.6 all tasks can be declared outside targets (earlier version
|
|---|
| 363 | only allowed <tt><property></tt>,<tt><typedef></tt> and
|
|---|
| 364 | <tt><taskdef></tt>). When you do this they are evaluated before
|
|---|
| 365 | any targets are executed. Some tasks will generate build failures if
|
|---|
| 366 | they are used outside of targets as they may cause infinite loops
|
|---|
| 367 | otherwise (<code><antcall></code> for example).</p>
|
|---|
| 368 |
|
|---|
| 369 | <p>
|
|---|
| 370 | We have given some targets descriptions; this causes the <tt>projecthelp</tt>
|
|---|
| 371 | invocation option to list them as public targets with the descriptions; the
|
|---|
| 372 | other target is internal and not listed.
|
|---|
| 373 | <p>
|
|---|
| 374 | Finally, for this target to work the source in the <tt>src</tt> subdirectory
|
|---|
| 375 | should be stored in a directory tree which matches the package names. Check the
|
|---|
| 376 | <tt><javac></tt> task for details.
|
|---|
| 377 |
|
|---|
| 378 | <a name="filters"><h3>Token Filters</h3></a>
|
|---|
| 379 | <p>A project can have a set of tokens that might be automatically expanded if
|
|---|
| 380 | found when a file is copied, when the filtering-copy behavior is selected in the
|
|---|
| 381 | tasks that support this. These might be set in the buildfile
|
|---|
| 382 | by the <a href="CoreTasks/filter.html">filter</a> task.</p>
|
|---|
| 383 | <p>Since this can potentially be a very harmful behavior,
|
|---|
| 384 | the tokens in the files <b>must</b>
|
|---|
| 385 | be of the form <code>@</code><i>token</i><code>@</code>, where
|
|---|
| 386 | <i>token</i> is the token name that is set
|
|---|
| 387 | in the <code><filter></code> task. This token syntax matches the syntax of other build systems
|
|---|
| 388 | that perform such filtering and remains sufficiently orthogonal to most
|
|---|
| 389 | programming and scripting languages, as well as with documentation systems.</p>
|
|---|
| 390 | <p>Note: If a token with the format <code>@</code><i>token</i><code>@</code>
|
|---|
| 391 | is found in a file, but no
|
|---|
| 392 | filter is associated with that token, no changes take place;
|
|---|
| 393 | therefore, no escaping
|
|---|
| 394 | method is available - but as long as you choose appropriate names for your
|
|---|
| 395 | tokens, this should not cause problems.</p>
|
|---|
| 396 | <p><b>Warning:</b> If you copy binary files with filtering turned on, you can corrupt the
|
|---|
| 397 | files. This feature should be used with text files <em>only</em>.</p>
|
|---|
| 398 |
|
|---|
| 399 | <h3><a name="path">Path-like Structures</a></h3>
|
|---|
| 400 | <p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type
|
|---|
| 401 | references using both
|
|---|
| 402 | "<code>:</code>" and "<code>;</code>" as separator
|
|---|
| 403 | characters. Ant will
|
|---|
| 404 | convert the separator to the correct character of the current operating
|
|---|
| 405 | system.</p>
|
|---|
| 406 | <p>Wherever path-like values need to be specified, a nested element can
|
|---|
| 407 | be used. This takes the general form of:</p>
|
|---|
| 408 | <pre>
|
|---|
| 409 | <classpath>
|
|---|
| 410 | <pathelement path="${classpath}"/>
|
|---|
| 411 | <pathelement location="lib/helper.jar"/>
|
|---|
| 412 | </classpath>
|
|---|
| 413 | </pre>
|
|---|
| 414 | <p>The <code>location</code> attribute specifies a single file or
|
|---|
| 415 | directory relative to the project's base directory (or an absolute
|
|---|
| 416 | filename), while the <code>path</code> attribute accepts colon-
|
|---|
| 417 | or semicolon-separated lists of locations. The <code>path</code>
|
|---|
| 418 | attribute is intended to be used with predefined paths - in any other
|
|---|
| 419 | case, multiple elements with <code>location</code> attributes should be
|
|---|
| 420 | preferred.</p>
|
|---|
| 421 | <p>As a shortcut, the <code><classpath></code> tag
|
|---|
| 422 | supports <code>path</code> and
|
|---|
| 423 | <code>location</code> attributes of its own, so:</p>
|
|---|
| 424 | <pre>
|
|---|
| 425 | <classpath>
|
|---|
| 426 | <pathelement path="${classpath}"/>
|
|---|
| 427 | </classpath>
|
|---|
| 428 | </pre>
|
|---|
| 429 | <p>can be abbreviated to:</p>
|
|---|
| 430 | <pre>
|
|---|
| 431 | <classpath path="${classpath}"/>
|
|---|
| 432 | </pre>
|
|---|
| 433 | <p>In addition, one or more
|
|---|
| 434 | <a href="CoreTypes/resources.html#collection">Resource Collection</a>s
|
|---|
| 435 | can be specified as nested elements (these must consist of
|
|---|
| 436 | <a href="CoreTypes/resources.html#file">file</a>-type resources only).
|
|---|
| 437 | Additionally, it should be noted that although resource collections are
|
|---|
| 438 | processed in the order encountered, certain resource collection types
|
|---|
| 439 | such as <a href="CoreTypes/fileset.html">fileset</a>,
|
|---|
| 440 | <a href="CoreTypes/dirset.html">dirset</a> and
|
|---|
| 441 | <a href="CoreTypes/resources.html#files">files</a>
|
|---|
| 442 | are undefined in terms of order.</p>
|
|---|
| 443 | <pre>
|
|---|
| 444 | <classpath>
|
|---|
| 445 | <pathelement path="${classpath}"/>
|
|---|
| 446 | <fileset dir="lib">
|
|---|
| 447 | <include name="**/*.jar"/>
|
|---|
| 448 | </fileset>
|
|---|
| 449 | <pathelement location="classes"/>
|
|---|
| 450 | <dirset dir="${build.dir}">
|
|---|
| 451 | <include name="apps/**/classes"/>
|
|---|
| 452 | <exclude name="apps/**/*Test*"/>
|
|---|
| 453 | </dirset>
|
|---|
| 454 | <filelist refid="third-party_jars"/>
|
|---|
| 455 | </classpath>
|
|---|
| 456 | </pre>
|
|---|
| 457 | <p>This builds a path that holds the value of <code>${classpath}</code>,
|
|---|
| 458 | followed by all jar files in the <code>lib</code> directory,
|
|---|
| 459 | the <code>classes</code> directory, all directories named
|
|---|
| 460 | <code>classes</code> under the <code>apps</code> subdirectory of
|
|---|
| 461 | <code>${build.dir}</code>, except those
|
|---|
| 462 | that have the text <code>Test</code> in their name, and
|
|---|
| 463 | the files specified in the referenced FileList.</p>
|
|---|
| 464 | <p>If you want to use the same path-like structure for several tasks,
|
|---|
| 465 | you can define them with a <code><path></code> element at the
|
|---|
| 466 | same level as <i>target</i>s, and reference them via their
|
|---|
| 467 | <i>id</i> attribute--see <a href="#references">References</a> for an
|
|---|
| 468 | example.</p>
|
|---|
| 469 | <p>A path-like structure can include a reference to another path-like
|
|---|
| 470 | structure (a path being itself a resource collection)
|
|---|
| 471 | via nested <code><path></code> elements:</p>
|
|---|
| 472 | <pre>
|
|---|
| 473 | <path id="base.path">
|
|---|
| 474 | <pathelement path="${classpath}"/>
|
|---|
| 475 | <fileset dir="lib">
|
|---|
| 476 | <include name="**/*.jar"/>
|
|---|
| 477 | </fileset>
|
|---|
| 478 | <pathelement location="classes"/>
|
|---|
| 479 | </path>
|
|---|
| 480 |
|
|---|
| 481 | <path id="tests.path">
|
|---|
| 482 | <path refid="base.path"/>
|
|---|
| 483 | <pathelement location="testclasses"/>
|
|---|
| 484 | </path>
|
|---|
| 485 | </pre>
|
|---|
| 486 | The shortcuts previously mentioned for <code><classpath></code> are also valid for <code><path></code>.For example:
|
|---|
| 487 | <pre>
|
|---|
| 488 | <path id="base.path">
|
|---|
| 489 | <pathelement path="${classpath}"/>
|
|---|
| 490 | </path>
|
|---|
| 491 | </pre>
|
|---|
| 492 | can be written as:
|
|---|
| 493 | <pre>
|
|---|
| 494 | <path id="base.path" path="${classpath}"/>
|
|---|
| 495 | </pre>
|
|---|
| 496 |
|
|---|
| 497 | <h3><a name="arg">Command-line Arguments</a></h3>
|
|---|
| 498 | <p>Several tasks take arguments that will be passed to another
|
|---|
| 499 | process on the command line. To make it easier to specify arguments
|
|---|
| 500 | that contain space characters, nested <code>arg</code> elements can be used.</p>
|
|---|
| 501 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 502 | <tr>
|
|---|
| 503 | <td width="12%" valign="top"><b>Attribute</b></td>
|
|---|
| 504 | <td width="78%" valign="top"><b>Description</b></td>
|
|---|
| 505 | <td width="10%" valign="top"><b>Required</b></td>
|
|---|
| 506 | </tr>
|
|---|
| 507 | <tr>
|
|---|
| 508 | <td valign="top">value</td>
|
|---|
| 509 | <td valign="top">a single command-line argument; can contain space
|
|---|
| 510 | characters.</td>
|
|---|
| 511 | <td align="center" rowspan="5">Exactly one of these.</td>
|
|---|
| 512 | </tr>
|
|---|
| 513 | <tr>
|
|---|
| 514 | <td valign="top">file</td>
|
|---|
| 515 | <td valign="top">The name of a file as a single command-line
|
|---|
| 516 | argument; will be replaced with the absolute filename of the file.</td>
|
|---|
| 517 | </tr>
|
|---|
| 518 | <tr>
|
|---|
| 519 | <td valign="top">path</td>
|
|---|
| 520 | <td valign="top">A string that will be treated as a path-like
|
|---|
| 521 | string as a single command-line argument; you can use <code>;</code>
|
|---|
| 522 | or <code>:</code> as
|
|---|
| 523 | path separators and Ant will convert it to the platform's local
|
|---|
| 524 | conventions.</td>
|
|---|
| 525 | </tr>
|
|---|
| 526 | <tr>
|
|---|
| 527 | <td valign="top">pathref</td>
|
|---|
| 528 | <td valign="top"><a href="#references">Reference</a> to a path
|
|---|
| 529 | defined elsewhere. Ant will convert it to the platform's local
|
|---|
| 530 | conventions.</td>
|
|---|
| 531 | </tr>
|
|---|
| 532 | <tr>
|
|---|
| 533 | <td valign="top">line</td>
|
|---|
| 534 | <td valign="top">a space-delimited list of command-line arguments.</td>
|
|---|
| 535 | </tr>
|
|---|
| 536 | </table>
|
|---|
| 537 |
|
|---|
| 538 | <p>It is highly recommended to avoid the <code>line</code> version
|
|---|
| 539 | when possible. Ant will try to split the command line in a way
|
|---|
| 540 | similar to what a (Unix) shell would do, but may create something that
|
|---|
| 541 | is very different from what you expect under some circumstances.</p>
|
|---|
| 542 |
|
|---|
| 543 | <h4>Examples</h4>
|
|---|
| 544 | <blockquote><pre>
|
|---|
| 545 | <arg value="-l -a"/>
|
|---|
| 546 | </pre></blockquote>
|
|---|
| 547 | <p>is a single command-line argument containing a space character,
|
|---|
| 548 | <i>not</i> separate commands "-l" and "-a".</p>
|
|---|
| 549 | <blockquote><pre>
|
|---|
| 550 | <arg line="-l -a"/>
|
|---|
| 551 | </pre></blockquote>
|
|---|
| 552 | <p>This is a command line with two separate arguments, "-l" and "-a".</p>
|
|---|
| 553 | <blockquote><pre>
|
|---|
| 554 | <arg path="/dir;/dir2:\dir3"/>
|
|---|
| 555 | </pre></blockquote>
|
|---|
| 556 | <p>is a single command-line argument with the value
|
|---|
| 557 | <code>\dir;\dir2;\dir3</code> on DOS-based systems and
|
|---|
| 558 | <code>/dir:/dir2:/dir3</code> on Unix-like systems.</p>
|
|---|
| 559 |
|
|---|
| 560 | <h3><a name="references">References</a></h3>
|
|---|
| 561 |
|
|---|
| 562 | <p>Any project element can be assigned an identifier using its
|
|---|
| 563 | <code>id</code> attribute. In most cases the element can subsequently
|
|---|
| 564 | be referenced by specifying the <code>refid</code> attribute on an
|
|---|
| 565 | element of the same type. This can be useful if you are going to
|
|---|
| 566 | replicate the same snippet of XML over and over again--using a
|
|---|
| 567 | <code><classpath></code> structure more than once, for example.</p>
|
|---|
| 568 | <p>The following example:</p>
|
|---|
| 569 | <blockquote><pre>
|
|---|
| 570 | <project ... >
|
|---|
| 571 | <target ... >
|
|---|
| 572 | <rmic ...>
|
|---|
| 573 | <classpath>
|
|---|
| 574 | <pathelement location="lib/"/>
|
|---|
| 575 | <pathelement path="${java.class.path}/"/>
|
|---|
| 576 | <pathelement path="${additional.path}"/>
|
|---|
| 577 | </classpath>
|
|---|
| 578 | </rmic>
|
|---|
| 579 | </target>
|
|---|
| 580 |
|
|---|
| 581 | <target ... >
|
|---|
| 582 | <javac ...>
|
|---|
| 583 | <classpath>
|
|---|
| 584 | <pathelement location="lib/"/>
|
|---|
| 585 | <pathelement path="${java.class.path}/"/>
|
|---|
| 586 | <pathelement path="${additional.path}"/>
|
|---|
| 587 | </classpath>
|
|---|
| 588 | </javac>
|
|---|
| 589 | </target>
|
|---|
| 590 | </project>
|
|---|
| 591 | </pre></blockquote>
|
|---|
| 592 | <p>could be rewritten as:</p>
|
|---|
| 593 | <blockquote><pre>
|
|---|
| 594 | <project ... >
|
|---|
| 595 | <path id="project.class.path">
|
|---|
| 596 | <pathelement location="lib/"/>
|
|---|
| 597 | <pathelement path="${java.class.path}/"/>
|
|---|
| 598 | <pathelement path="${additional.path}"/>
|
|---|
| 599 | </path>
|
|---|
| 600 |
|
|---|
| 601 | <target ... >
|
|---|
| 602 | <rmic ...>
|
|---|
| 603 | <classpath refid="project.class.path"/>
|
|---|
| 604 | </rmic>
|
|---|
| 605 | </target>
|
|---|
| 606 |
|
|---|
| 607 | <target ... >
|
|---|
| 608 | <javac ...>
|
|---|
| 609 | <classpath refid="project.class.path"/>
|
|---|
| 610 | </javac>
|
|---|
| 611 | </target>
|
|---|
| 612 | </project>
|
|---|
| 613 | </pre></blockquote>
|
|---|
| 614 | <p>All tasks that use nested elements for
|
|---|
| 615 | <a href="CoreTypes/patternset.html">PatternSet</a>s,
|
|---|
| 616 | <a href="CoreTypes/fileset.html">FileSet</a>s,
|
|---|
| 617 | <a href="CoreTypes/zipfileset.html">ZipFileSet</a>s or
|
|---|
| 618 | <a href="#path">path-like structures</a> accept references to these structures
|
|---|
| 619 | as shown in the examples. Using <code>refid</code> on a task will ordinarily
|
|---|
| 620 | have the same effect (referencing a task already declared), but the user
|
|---|
| 621 | should be aware that the interpretation of this attribute is dependent on the
|
|---|
| 622 | implementation of the element upon which it is specified. Some tasks (the
|
|---|
| 623 | <a href="CoreTasks/property.html">property</a> task is a handy example)
|
|---|
| 624 | deliberately assign a different meaning to <code>refid</code>.</p>
|
|---|
| 625 |
|
|---|
| 626 |
|
|---|
| 627 | <h3><a name="external-tasks">Use of external tasks</a></h3>
|
|---|
| 628 | Ant supports a plugin mechanism for using third party tasks. For using them you
|
|---|
| 629 | have to do two steps:
|
|---|
| 630 | <ol>
|
|---|
| 631 | <li>place their implementation somewhere where Ant can find them</li>
|
|---|
| 632 | <li>declare them.</li>
|
|---|
| 633 | </ol>
|
|---|
| 634 | Don't add anything to the CLASSPATH environment variable - this is often the
|
|---|
| 635 | reason for very obscure errors. Use Ant's own <a href="install.html#optionalTasks">mechanisms</a>
|
|---|
| 636 | for adding libraries:
|
|---|
| 637 | <ul>
|
|---|
| 638 | <li>via command line argument <code>-lib</code></li>
|
|---|
| 639 | <li>adding to <code>${user.home}/.ant/lib</code></li>
|
|---|
| 640 | <li>adding to <code>${ant.home}/lib</code></li>
|
|---|
| 641 | </ul>
|
|---|
| 642 | For the declaration there are several ways:
|
|---|
| 643 | <ul>
|
|---|
| 644 | <li>declare a single task per using instruction using
|
|---|
| 645 | <code><<a href="CoreTasks/taskdef.html">taskdef</a> name="taskname"
|
|---|
| 646 | classname="ImplementationClass"/></code>
|
|---|
| 647 | <br>
|
|---|
| 648 | <code><taskdef name="for" classname="net.sf.antcontrib.logic.For" />
|
|---|
| 649 | <for ... /></code>
|
|---|
| 650 | </li>
|
|---|
| 651 | <li>declare a bundle of tasks using a properties-file holding these
|
|---|
| 652 | taskname-ImplementationClass-pairs and <code><taskdef></code>
|
|---|
| 653 | <br>
|
|---|
| 654 | <code><taskdef resource="net/sf/antcontrib/antcontrib.properties" />
|
|---|
| 655 | <for ... /></code>
|
|---|
| 656 | </li>
|
|---|
| 657 | <li>declare a bundle of tasks using a <a href="CoreTypes/antlib.html">xml-file</a> holding these
|
|---|
| 658 | taskname-ImplementationClass-pairs and <code><taskdef></code>
|
|---|
| 659 | <br>
|
|---|
| 660 | <code><taskdef resource="net/sf/antcontrib/antlib.xml" />
|
|---|
| 661 | <for ... /></code>
|
|---|
| 662 | </li>
|
|---|
| 663 | <li>declare a bundle of tasks using a xml-file named antlib.xml, XML-namespace and
|
|---|
| 664 | <a href="CoreTypes/antlib.html#antlibnamespace"><code>antlib:</code> protocoll handler</a>
|
|---|
| 665 | <br>
|
|---|
| 666 | <code><project xmlns:ac="antlib:net.sf.antconrib"/>
|
|---|
| 667 | <ac:for ... /></code>
|
|---|
| 668 | </li>
|
|---|
| 669 | </ul>
|
|---|
| 670 |
|
|---|
| 671 | If you need a special function, you should
|
|---|
| 672 | <ol>
|
|---|
| 673 | <li>have a look at this manual, because Ant provides lot of tasks</li>
|
|---|
| 674 | <li>have a look at the external task page in the <a href="../external.html">manual</a>
|
|---|
| 675 | (or better <a href="http://ant.apache.org/external.html">online</a>)</li>
|
|---|
| 676 | <li>have a look at the external task <a href="http://wiki.apache.org/ant/AntExternalTaskdefs">wiki
|
|---|
| 677 | page</a></li>
|
|---|
| 678 | <li>ask on the <a href="http://ant.apache.org/mail.html#User%20List">Ant user</a> list</li>
|
|---|
| 679 | <li><a href="tutorial-writing-tasks.html">implement </a>(and share) your own</li>
|
|---|
| 680 | </ol>
|
|---|
| 681 |
|
|---|
| 682 | </body>
|
|---|
| 683 | </html>
|
|---|
