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