You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

using.html 24 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579
  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. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html>
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="stylesheets/style.css">
  19. <title>Writing a Simple Buildfile</title>
  20. </head>
  21. <body>
  22. <h1>Using Apache Ant</h1>
  23. <h2><a name="buildfile">Writing a Simple Buildfile</a></h2>
  24. <p>Apache Ant's buildfiles are written in XML. Each buildfile contains one project
  25. and at least one (default) target. Targets contain task elements.
  26. Each task element of the buildfile can have an <code>id</code> attribute and
  27. can later be referred to by the value supplied to this. The value has
  28. to be unique. (For additional information, see the
  29. <a href="#tasks"> Tasks</a> section below.)</p>
  30. <h3><a name="projects">Projects</a></h3>
  31. <p>A <i>project</i> has three attributes:</p>
  32. <table border="1" cellpadding="2" cellspacing="0">
  33. <tr>
  34. <td valign="top"><b>Attribute</b></td>
  35. <td valign="top"><b>Description</b></td>
  36. <td align="center" valign="top"><b>Required</b></td>
  37. </tr>
  38. <tr>
  39. <td valign="top">name</td>
  40. <td valign="top">the name of the project.</td>
  41. <td align="center" valign="top">No</td>
  42. </tr>
  43. <tr>
  44. <td valign="top">default</td>
  45. <td valign="top">the default target to use when no target is supplied.</td>
  46. <td align="center" valign="top">No; however, <b>since Ant 1.6.0</b>,
  47. every project includes an implicit target that contains any and
  48. all top-level tasks and/or types. This target will always be
  49. executed as part of the project's initialization, even when Ant is
  50. run with the <a href="running.html#options">-projecthelp</a> option.
  51. </td>
  52. </tr>
  53. <tr>
  54. <td valign="top">basedir</td>
  55. <td valign="top">the base directory from which all path calculations are
  56. done. This attribute might be overridden by setting
  57. the &quot;basedir&quot;
  58. property beforehand. When this is done, it must be omitted in the
  59. project tag. If neither the attribute nor the property have
  60. been set, the parent directory of the buildfile will be used.<br/>
  61. A relative path is resolved relative to the directory containing
  62. the build file.
  63. </td>
  64. <td align="center" valign="top">No</td>
  65. </tr>
  66. </table>
  67. <p>Optionally, a description for the project can be provided as a
  68. top-level <code>&lt;description&gt;</code> element (see the <a
  69. href="Types/description.html">description</a> type).</p>
  70. <p>Each project defines one or more <i>targets</i>.
  71. A target is a set of <i>tasks</i> you want
  72. to be executed. When starting Ant, you can select which target(s) you
  73. want to have executed. When no target is given,
  74. the project's default is used.</p>
  75. <h3><a name="targets">Targets</a></h3>
  76. <p>A target can depend on other targets. You might have a target for compiling,
  77. for example, and a target for creating a distributable. You can only build a
  78. distributable when you have compiled first, so the distribute target
  79. <i>depends on</i> the compile target. Ant resolves these dependencies.</p>
  80. <p>It should be noted, however, that Ant's <code>depends</code> attribute
  81. only specifies the <i>order</i> in which targets should be executed - it
  82. does not affect whether the target that specifies the dependency(s) gets
  83. executed if the dependent target(s) did not (need to) run.
  84. </p>
  85. <p>More information can be found in the
  86. dedicated <a href="targets.html">manual page</a>.</p>
  87. <h3><a name="tasks">Tasks</a></h3>
  88. <p>A task is a piece of code that can be executed.</p>
  89. <p>A task can have multiple attributes (or arguments, if you prefer). The value
  90. of an attribute might contain references to a property. These references will be
  91. resolved before the task is executed.</p>
  92. <p>Tasks have a common structure:</p>
  93. <blockquote>
  94. <pre>&lt;<i>name</i> <i>attribute1</i>=&quot;<i>value1</i>&quot; <i>attribute2</i>=&quot;<i>value2</i>&quot; ... /&gt;</pre>
  95. </blockquote>
  96. <p>where <i>name</i> is the name of the task,
  97. <i>attributeN</i> is the attribute name, and
  98. <i>valueN</i> is the value for this attribute.</p>
  99. <p>There is a set of <a href="tasklist.html" target="navFrame">built-in tasks</a>, but it is also very
  100. easy to <a href="develop.html#writingowntask">write your own</a>.</p>
  101. <p>All tasks share a task name attribute. The value of
  102. this attribute will be used in the logging messages generated by
  103. Ant.</p>
  104. Tasks can be assigned an <code>id</code> attribute:
  105. <blockquote>
  106. <pre>&lt;<i>taskname</i> id="<i>taskID</i>" ... /&gt;</pre>
  107. </blockquote>
  108. where <i>taskname</i> is the name of the task, and <i>taskID</i> is
  109. a unique identifier for this task.
  110. You can refer to the
  111. corresponding task object in scripts or other tasks via this name.
  112. For example, in scripts you could do:
  113. <blockquote>
  114. <pre>
  115. &lt;script ... &gt;
  116. task1.setFoo("bar");
  117. &lt;/script&gt;
  118. </pre>
  119. </blockquote>
  120. to set the <code>foo</code> attribute of this particular task instance.
  121. In another task (written in Java), you can access the instance via
  122. <code>project.getReference("task1")</code>.
  123. <p>
  124. Note<sup>1</sup>: If &quot;task1&quot; has not been run yet, then
  125. it has not been configured (ie., no attributes have been set), and if it is
  126. going to be configured later, anything you've done to the instance may
  127. be overwritten.
  128. </p>
  129. <p>
  130. Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i>
  131. be backward-compatible with this behaviour, since there will likely be no
  132. task instances at all, only proxies.
  133. </p>
  134. <h3><a name="properties">Properties</a></h3>
  135. <p>Properties are an important way to customize a build process or
  136. to just provide shortcuts for strings that are used repeatedly
  137. inside a build file.</p>
  138. <p>In its most simple form properties are defined in the build file
  139. (for example by the <a href="Tasks/property.html">property</a>
  140. task) or might be set outside Ant. A property has a name and a
  141. value; the name is case-sensitive. Properties may be used in the
  142. value of task attributes or in the nested text of tasks that support
  143. them. This is done by placing the property name between
  144. &quot;<code>${</code>&quot; and &quot;<code>}</code>&quot; in the
  145. attribute value. For example, if there is a &quot;builddir&quot;
  146. property with the value &quot;build&quot;, then this could be used
  147. in an attribute like this: <code>${builddir}/classes</code>. This
  148. is resolved at run-time as <code>build/classes</code>.</p>
  149. <p>With Ant 1.8.0 property expansion has become much more powerful
  150. than simple key value pairs, more details can be
  151. found <a href="properties.html">in the concepts section</a> of this
  152. manual.</p>
  153. <h3><a name="example">Example Buildfile</a></h3>
  154. <pre>
  155. &lt;project name=&quot;MyProject&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;
  156. &lt;description&gt;
  157. simple example build file
  158. &lt;/description&gt;
  159. &lt;!-- set global properties for this build --&gt;
  160. &lt;property name=&quot;src&quot; location=&quot;src&quot;/&gt;
  161. &lt;property name=&quot;build&quot; location=&quot;build&quot;/&gt;
  162. &lt;property name=&quot;dist&quot; location=&quot;dist&quot;/&gt;
  163. &lt;target name=&quot;init&quot;&gt;
  164. &lt;!-- Create the time stamp --&gt;
  165. &lt;tstamp/&gt;
  166. &lt;!-- Create the build directory structure used by compile --&gt;
  167. &lt;mkdir dir=&quot;${build}&quot;/&gt;
  168. &lt;/target&gt;
  169. &lt;target name=&quot;compile&quot; depends=&quot;init&quot;
  170. description=&quot;compile the source&quot;&gt;
  171. &lt;!-- Compile the java code from ${src} into ${build} --&gt;
  172. &lt;javac srcdir=&quot;${src}&quot; destdir=&quot;${build}&quot;/&gt;
  173. &lt;/target&gt;
  174. &lt;target name=&quot;dist&quot; depends=&quot;compile&quot;
  175. description=&quot;generate the distribution&quot;&gt;
  176. &lt;!-- Create the distribution directory --&gt;
  177. &lt;mkdir dir=&quot;${dist}/lib&quot;/&gt;
  178. &lt;!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --&gt;
  179. &lt;jar jarfile=&quot;${dist}/lib/MyProject-${DSTAMP}.jar&quot; basedir=&quot;${build}&quot;/&gt;
  180. &lt;/target&gt;
  181. &lt;target name=&quot;clean&quot;
  182. description=&quot;clean up&quot;&gt;
  183. &lt;!-- Delete the ${build} and ${dist} directory trees --&gt;
  184. &lt;delete dir=&quot;${build}&quot;/&gt;
  185. &lt;delete dir=&quot;${dist}&quot;/&gt;
  186. &lt;/target&gt;
  187. &lt;/project&gt;
  188. </pre>
  189. <p>Notice that we are declaring properties outside any target. As of
  190. Ant 1.6 all tasks can be declared outside targets (earlier version
  191. only allowed <tt>&lt;property&gt;</tt>,<tt>&lt;typedef&gt;</tt> and
  192. <tt>&lt;taskdef&gt;</tt>). When you do this they are evaluated before
  193. any targets are executed. Some tasks will generate build failures if
  194. they are used outside of targets as they may cause infinite loops
  195. otherwise (<code>&lt;antcall&gt;</code> for example).</p>
  196. <p>
  197. We have given some targets descriptions; this causes the <tt>projecthelp</tt>
  198. invocation option to list them as public targets with the descriptions; the
  199. other target is internal and not listed.
  200. <p>
  201. Finally, for this target to work the source in the <tt>src</tt> subdirectory
  202. should be stored in a directory tree which matches the package names. Check the
  203. <tt>&lt;javac&gt;</tt> task for details.
  204. <h3><a name="filters">Token Filters</a></h3>
  205. <p>A project can have a set of tokens that might be automatically expanded if
  206. found when a file is copied, when the filtering-copy behavior is selected in the
  207. tasks that support this. These might be set in the buildfile
  208. by the <a href="Tasks/filter.html">filter</a> task.</p>
  209. <p>Since this can potentially be a very harmful behavior,
  210. the tokens in the files <b>must</b>
  211. be of the form <code>@</code><i>token</i><code>@</code>, where
  212. <i>token</i> is the token name that is set
  213. in the <code>&lt;filter&gt;</code> task. This token syntax matches the syntax of other build systems
  214. that perform such filtering and remains sufficiently orthogonal to most
  215. programming and scripting languages, as well as with documentation systems.</p>
  216. <p>Note: If a token with the format <code>@</code><i>token</i><code>@</code>
  217. is found in a file, but no
  218. filter is associated with that token, no changes take place;
  219. therefore, no escaping
  220. method is available - but as long as you choose appropriate names for your
  221. tokens, this should not cause problems.</p>
  222. <p><b>Warning:</b> If you copy binary files with filtering turned on, you can corrupt the
  223. files. This feature should be used with text files <em>only</em>.</p>
  224. <h3><a name="path">Path-like Structures</a></h3>
  225. <p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type
  226. references using both
  227. &quot;<code>:</code>&quot; and &quot;<code>;</code>&quot; as separator
  228. characters. Ant will
  229. convert the separator to the correct character of the current operating
  230. system.</p>
  231. <p>Wherever path-like values need to be specified, a nested element can
  232. be used. This takes the general form of:</p>
  233. <pre>
  234. &lt;classpath&gt;
  235. &lt;pathelement path=&quot;${classpath}&quot;/&gt;
  236. &lt;pathelement location=&quot;lib/helper.jar&quot;/&gt;
  237. &lt;/classpath&gt;
  238. </pre>
  239. <p>The <code>location</code> attribute specifies a single file or
  240. directory relative to the project's base directory (or an absolute
  241. filename), while the <code>path</code> attribute accepts colon-
  242. or semicolon-separated lists of locations. The <code>path</code>
  243. attribute is intended to be used with predefined paths - in any other
  244. case, multiple elements with <code>location</code> attributes should be
  245. preferred.</p>
  246. <p><em>Since Ant 1.8.2</em> the location attribute can also contain a
  247. wildcard in its last path component (i.e. it can end in a
  248. &quot;*&quot;) in order to support wildcard CLASSPATHs introduced
  249. with Java6. Ant will not expand or evaluate the wildcards and the
  250. resulting path may not work as anything else but a CLASSPATH - or
  251. even as a CLASSPATH for a Java VM prior to Java6.</p>
  252. <p>As a shortcut, the <code>&lt;classpath&gt;</code> tag
  253. supports <code>path</code> and
  254. <code>location</code> attributes of its own, so:</p>
  255. <pre>
  256. &lt;classpath&gt;
  257. &lt;pathelement path=&quot;${classpath}&quot;/&gt;
  258. &lt;/classpath&gt;
  259. </pre>
  260. <p>can be abbreviated to:</p>
  261. <pre>
  262. &lt;classpath path=&quot;${classpath}&quot;/&gt;
  263. </pre>
  264. <p>In addition, one or more
  265. <a href="Types/resources.html#collection">Resource Collection</a>s
  266. can be specified as nested elements (these must consist of
  267. <a href="Types/resources.html#file">file</a>-type resources only).
  268. Additionally, it should be noted that although resource collections are
  269. processed in the order encountered, certain resource collection types
  270. such as <a href="Types/fileset.html">fileset</a>,
  271. <a href="Types/dirset.html">dirset</a> and
  272. <a href="Types/resources.html#files">files</a>
  273. are undefined in terms of order.</p>
  274. <pre>
  275. &lt;classpath&gt;
  276. &lt;pathelement path=&quot;${classpath}&quot;/&gt;
  277. &lt;fileset dir=&quot;lib&quot;&gt;
  278. &lt;include name=&quot;**/*.jar&quot;/&gt;
  279. &lt;/fileset&gt;
  280. &lt;pathelement location=&quot;classes&quot;/&gt;
  281. &lt;dirset dir=&quot;${build.dir}&quot;&gt;
  282. &lt;include name=&quot;apps/**/classes&quot;/&gt;
  283. &lt;exclude name=&quot;apps/**/*Test*&quot;/&gt;
  284. &lt;/dirset&gt;
  285. &lt;filelist refid=&quot;third-party_jars&quot;/&gt;
  286. &lt;/classpath&gt;
  287. </pre>
  288. <p>This builds a path that holds the value of <code>${classpath}</code>,
  289. followed by all jar files in the <code>lib</code> directory,
  290. the <code>classes</code> directory, all directories named
  291. <code>classes</code> under the <code>apps</code> subdirectory of
  292. <code>${build.dir}</code>, except those
  293. that have the text <code>Test</code> in their name, and
  294. the files specified in the referenced FileList.</p>
  295. <p>If you want to use the same path-like structure for several tasks,
  296. you can define them with a <code>&lt;path&gt;</code> element at the
  297. same level as <i>target</i>s, and reference them via their
  298. <i>id</i> attribute--see <a href="#references">References</a> for an
  299. example.</p>
  300. <p>By default a path like structure will re-evaluate all nested
  301. resource collections whenever it is used, which may lead to
  302. unnecessary re-scanning of the filesystem. Since Ant 1.8.0 path has
  303. an optional <i>cache</i> attribute, if it is set to true, the path
  304. instance will only scan its nested resource collections once and
  305. assume it doesn't change during the build anymore (the default
  306. for <i>cache</i> still is <i>false</i>). Even if you are using the
  307. path only in a single task it may improve overall performance to set
  308. <i>cache</i> to <i>true</i> if you are using complex nested
  309. constructs.</p>
  310. <p>A path-like structure can include a reference to another path-like
  311. structure (a path being itself a resource collection)
  312. via nested <code>&lt;path&gt;</code> elements:</p>
  313. <pre>
  314. &lt;path id=&quot;base.path&quot;&gt;
  315. &lt;pathelement path=&quot;${classpath}&quot;/&gt;
  316. &lt;fileset dir=&quot;lib&quot;&gt;
  317. &lt;include name=&quot;**/*.jar&quot;/&gt;
  318. &lt;/fileset&gt;
  319. &lt;pathelement location=&quot;classes&quot;/&gt;
  320. &lt;/path&gt;
  321. &lt;path id=&quot;tests.path&quot; cache=&quot;true&quot;&gt;
  322. &lt;path refid=&quot;base.path&quot;/&gt;
  323. &lt;pathelement location=&quot;testclasses&quot;/&gt;
  324. &lt;/path&gt;
  325. </pre>
  326. The shortcuts previously mentioned for <code>&lt;classpath&gt;</code> are also valid for <code>&lt;path&gt;</code>.For example:
  327. <pre>
  328. &lt;path id=&quot;base.path&quot;&gt;
  329. &lt;pathelement path=&quot;${classpath}&quot;/&gt;
  330. &lt;/path&gt;
  331. </pre>
  332. can be written as:
  333. <pre>
  334. &lt;path id=&quot;base.path&quot; path=&quot;${classpath}&quot;/&gt;
  335. </pre>
  336. <h4><a name="pathshortcut">Path Shortcut</a></h4>
  337. <p>
  338. In Ant 1.6 a shortcut for converting paths to OS specific strings
  339. in properties has been added. One can use the expression
  340. ${toString:<em>pathreference</em>} to convert a path element
  341. reference to a string that can be used for a path argument.
  342. For example:
  343. </p>
  344. <pre>
  345. &lt;path id="lib.path.ref"&gt;
  346. &lt;fileset dir="lib" includes="*.jar"/&gt;
  347. &lt;/path&gt;
  348. &lt;javac srcdir="src" destdir="classes"&gt;
  349. &lt;compilerarg arg="-Xbootclasspath/p:${toString:lib.path.ref}"/&gt;
  350. &lt;/javac&gt;
  351. </pre>
  352. <h3><a name="arg">Command-line Arguments</a></h3>
  353. <p>Several tasks take arguments that will be passed to another
  354. process on the command line. To make it easier to specify arguments
  355. that contain space characters, nested <code>arg</code> elements can be used.</p>
  356. <table border="1" cellpadding="2" cellspacing="0">
  357. <tr>
  358. <td width="12%" valign="top"><b>Attribute</b></td>
  359. <td width="78%" valign="top"><b>Description</b></td>
  360. <td width="10%" valign="top"><b>Required</b></td>
  361. </tr>
  362. <tr>
  363. <td valign="top">value</td>
  364. <td valign="top">a single command-line argument; can contain space
  365. characters.</td>
  366. <td align="center" rowspan="5">Exactly one of these.</td>
  367. </tr>
  368. <tr>
  369. <td valign="top">file</td>
  370. <td valign="top">The name of a file as a single command-line
  371. argument; will be replaced with the absolute filename of the file.</td>
  372. </tr>
  373. <tr>
  374. <td valign="top">path</td>
  375. <td valign="top">A string that will be treated as a path-like
  376. string as a single command-line argument; you can use <code>;</code>
  377. or <code>:</code> as
  378. path separators and Ant will convert it to the platform's local
  379. conventions.</td>
  380. </tr>
  381. <tr>
  382. <td valign="top">pathref</td>
  383. <td valign="top"><a href="#references">Reference</a> to a path
  384. defined elsewhere. Ant will convert it to the platform's local
  385. conventions.</td>
  386. </tr>
  387. <tr>
  388. <td valign="top">line</td>
  389. <td valign="top">a space-delimited list of command-line arguments.</td>
  390. </tr>
  391. <tr>
  392. <td valign="top">prefix</td>
  393. <td valign="top">A fixed string to be placed in front of the
  394. argument. In the case of a line broken into parts, it will be
  395. placed in front of every part. <em>Since Ant 1.8.</em></td>
  396. <td valign="top" align="center">No</td>
  397. </tr>
  398. <tr>
  399. <td valign="top">suffix</td>
  400. <td valign="top">A fixed string to be placed immediately after the
  401. argument. In the case of a line broken into parts, it will be
  402. placed after every part. <em>Since Ant 1.8.</em></td>
  403. <td valign="top" align="center">No</td>
  404. </tr>
  405. </table>
  406. <p>It is highly recommended to avoid the <code>line</code> version
  407. when possible. Ant will try to split the command line in a way
  408. similar to what a (Unix) shell would do, but may create something that
  409. is very different from what you expect under some circumstances.</p>
  410. <h4>Examples</h4>
  411. <blockquote><pre>
  412. &lt;arg value=&quot;-l -a&quot;/&gt;
  413. </pre></blockquote>
  414. <p>is a single command-line argument containing a space character,
  415. <i>not</i> separate commands "-l" and "-a".</p>
  416. <blockquote><pre>
  417. &lt;arg line=&quot;-l -a&quot;/&gt;
  418. </pre></blockquote>
  419. <p>This is a command line with two separate arguments, "-l" and "-a".</p>
  420. <blockquote><pre>
  421. &lt;arg path=&quot;/dir;/dir2:\dir3&quot;/&gt;
  422. </pre></blockquote>
  423. <p>is a single command-line argument with the value
  424. <code>\dir;\dir2;\dir3</code> on DOS-based systems and
  425. <code>/dir:/dir2:/dir3</code> on Unix-like systems.</p>
  426. <h3><a name="references">References</a></h3>
  427. <p>Any project element can be assigned an identifier using its
  428. <code>id</code> attribute. In most cases the element can subsequently
  429. be referenced by specifying the <code>refid</code> attribute on an
  430. element of the same type. This can be useful if you are going to
  431. replicate the same snippet of XML over and over again--using a
  432. <code>&lt;classpath&gt;</code> structure more than once, for example.</p>
  433. <p>The following example:</p>
  434. <blockquote><pre>
  435. &lt;project ... &gt;
  436. &lt;target ... &gt;
  437. &lt;rmic ...&gt;
  438. &lt;classpath&gt;
  439. &lt;pathelement location=&quot;lib/&quot;/&gt;
  440. &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;
  441. &lt;pathelement path=&quot;${additional.path}&quot;/&gt;
  442. &lt;/classpath&gt;
  443. &lt;/rmic&gt;
  444. &lt;/target&gt;
  445. &lt;target ... &gt;
  446. &lt;javac ...&gt;
  447. &lt;classpath&gt;
  448. &lt;pathelement location=&quot;lib/&quot;/&gt;
  449. &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;
  450. &lt;pathelement path=&quot;${additional.path}&quot;/&gt;
  451. &lt;/classpath&gt;
  452. &lt;/javac&gt;
  453. &lt;/target&gt;
  454. &lt;/project&gt;
  455. </pre></blockquote>
  456. <p>could be rewritten as:</p>
  457. <blockquote><pre>
  458. &lt;project ... &gt;
  459. &lt;path id=&quot;project.class.path&quot;&gt;
  460. &lt;pathelement location=&quot;lib/&quot;/&gt;
  461. &lt;pathelement path=&quot;${java.class.path}/&quot;/&gt;
  462. &lt;pathelement path=&quot;${additional.path}&quot;/&gt;
  463. &lt;/path&gt;
  464. &lt;target ... &gt;
  465. &lt;rmic ...&gt;
  466. &lt;classpath refid=&quot;project.class.path&quot;/&gt;
  467. &lt;/rmic&gt;
  468. &lt;/target&gt;
  469. &lt;target ... &gt;
  470. &lt;javac ...&gt;
  471. &lt;classpath refid=&quot;project.class.path&quot;/&gt;
  472. &lt;/javac&gt;
  473. &lt;/target&gt;
  474. &lt;/project&gt;
  475. </pre></blockquote>
  476. <p>All tasks that use nested elements for
  477. <a href="Types/patternset.html">PatternSet</a>s,
  478. <a href="Types/fileset.html">FileSet</a>s,
  479. <a href="Types/zipfileset.html">ZipFileSet</a>s or
  480. <a href="#path">path-like structures</a> accept references to these structures
  481. as shown in the examples. Using <code>refid</code> on a task will ordinarily
  482. have the same effect (referencing a task already declared), but the user
  483. should be aware that the interpretation of this attribute is dependent on the
  484. implementation of the element upon which it is specified. Some tasks (the
  485. <a href="Tasks/property.html">property</a> task is a handy example)
  486. deliberately assign a different meaning to <code>refid</code>.</p>
  487. <h3><a name="external-tasks">Use of external tasks</a></h3>
  488. Ant supports a plugin mechanism for using third party tasks. For using them you
  489. have to do two steps:
  490. <ol>
  491. <li>place their implementation somewhere where Ant can find them</li>
  492. <li>declare them.</li>
  493. </ol>
  494. Don't add anything to the CLASSPATH environment variable - this is often the
  495. reason for very obscure errors. Use Ant's own <a href="install.html#optionalTasks">mechanisms</a>
  496. for adding libraries:
  497. <ul>
  498. <li>via command line argument <code>-lib</code></li>
  499. <li>adding to <code>${user.home}/.ant/lib</code></li>
  500. <li>adding to <code>${ant.home}/lib</code></li>
  501. </ul>
  502. For the declaration there are several ways:
  503. <ul>
  504. <li>declare a single task per using instruction using
  505. <code>&lt;<a href="Tasks/taskdef.html">taskdef</a> name=&quot;taskname&quot;
  506. classname=&quot;ImplementationClass&quot;/&gt;</code>
  507. <br>
  508. <code>&lt;taskdef name=&quot;for&quot; classname=&quot;net.sf.antcontrib.logic.For&quot; /&gt;
  509. &lt;for ... /&gt;</code>
  510. </li>
  511. <li>declare a bundle of tasks using a properties-file holding these
  512. taskname-ImplementationClass-pairs and <code>&lt;taskdef&gt;</code>
  513. <br>
  514. <code>&lt;taskdef resource=&quot;net/sf/antcontrib/antcontrib.properties&quot; /&gt;
  515. &lt;for ... /&gt;</code>
  516. </li>
  517. <li>declare a bundle of tasks using a <a href="Types/antlib.html">xml-file</a> holding these
  518. taskname-ImplementationClass-pairs and <code>&lt;taskdef&gt;</code>
  519. <br>
  520. <code>&lt;taskdef resource=&quot;net/sf/antcontrib/antlib.xml&quot; /&gt;
  521. &lt;for ... /&gt;</code>
  522. </li>
  523. <li>declare a bundle of tasks using a xml-file named antlib.xml, XML-namespace and
  524. <a href="Types/antlib.html#antlibnamespace"><code>antlib:</code> protocol handler</a>
  525. <br>
  526. <code>&lt;project xmlns:ac=&quot;antlib:net.sf.antcontrib&quot;/&gt;
  527. &lt;ac:for ... /&gt;</code>
  528. </li>
  529. </ul>
  530. If you need a special function, you should
  531. <ol>
  532. <li>have a look at this manual, because Ant provides lot of tasks</li>
  533. <li>have a look at the external task page <a href="http://ant.apache.org/external.html">online</a></li>
  534. <li>have a look at the external task <a href="http://wiki.apache.org/ant/AntExternalTaskdefs">wiki
  535. page</a></li>
  536. <li>ask on the <a href="http://ant.apache.org/mail.html#User%20List">Ant user</a> list</li>
  537. <li><a href="tutorial-writing-tasks.html">implement </a>(and share) your own</li>
  538. </ol>
  539. </body>
  540. </html>