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.

running.html 25 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627
  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>Running Apache Ant</title>
  20. </head>
  21. <body>
  22. <h1>Running Apache Ant</h1>
  23. <h2><a name="commandline">Command Line</a></h2>
  24. <p> If you've installed Apache Ant as described in the
  25. <a href="install.html"> Installing Ant</a> section,
  26. running Ant from the command-line is simple: just type
  27. <code>ant</code>.</p>
  28. <p>When no arguments are specified, Ant looks for a <code>build.xml</code>
  29. file in the current directory and, if found, uses that file as the
  30. build file and runs the target specified in the <code>default</code>
  31. attribute of the <code>&lt;project&gt;</code> tag.
  32. To make Ant use
  33. a build file other than <code>build.xml</code>, use the command-line
  34. option <nobr><code>-buildfile <i>file</i></code></nobr>,
  35. where <i>file</i> is the name of the build file you want to use
  36. (or a directory containing a <code>build.xml</code> file).</p>
  37. If you use the <nobr><code>-find [<i>file</i>]</code></nobr> option,
  38. Ant will search for a build file first in the current directory, then in
  39. the parent directory, and so on, until either a build file is found or the root
  40. of the filesystem has been reached. By default, it will look for a build file
  41. called <code>build.xml</code>. To have it search for a build file other
  42. than <code>build.xml</code>, specify a file argument.
  43. <strong>Note:</strong> If you include any other flags or arguments
  44. on the command line after
  45. the <nobr><code>-find</code></nobr> flag, you must include the file argument
  46. for the <nobr><code>-find</code></nobr> flag, even if the name of the
  47. build file you want to find is <code>build.xml</code>.
  48. <p>You can also set <a href="using.html#properties">properties</a> on the
  49. command line. This can be done with
  50. the <nobr><code>-D<i>property</i>=<i>value</i></code></nobr> option,
  51. where <i>property</i> is the name of the property,
  52. and <i>value</i> is the value for that property. If you specify a
  53. property that is also set in the build file
  54. (see the <a href="Tasks/property.html">property</a> task),
  55. the value specified on the
  56. command line will override the value specified in the
  57. build file.
  58. Defining properties on the command line can also be used to pass in
  59. the value of environment variables; just pass
  60. <nobr><code>-DMYVAR=%MYVAR%</code></nobr> (Windows) or
  61. <nobr><code>-DMYVAR=$MYVAR</code></nobr> (Unix)
  62. to Ant. You can then access
  63. these variables inside your build file as <code>${MYVAR}</code>.
  64. You can also access environment variables using the
  65. <a href="Tasks/property.html"> property</a> task's
  66. <code>environment</code> attribute.
  67. </p>
  68. <p>Options that affect the amount of logging output by Ant are:
  69. <nobr><code>-quiet</code></nobr>,
  70. which instructs Ant to print less
  71. information to the console;
  72. <nobr><code>-verbose</code></nobr>, which causes Ant to print
  73. additional information to the console; <nobr><code>-debug</code></nobr>,
  74. which causes Ant to print considerably more additional information; and
  75. <nobr><code>-silent</code></nobr> which makes Ant print nothing but task
  76. output and build failures (useful to capture Ant output by scripts).
  77. </p>
  78. <p>It is also possible to specify one or more targets that should be executed.
  79. When omitted, the target that is specified in the
  80. <code>default</code> attribute of the
  81. <a href="using.html#projects"><code>project</code></a> tag is
  82. used.</p>
  83. <p>The <nobr><code>-projecthelp</code></nobr> option prints out a list
  84. of the build file's targets. Targets that include a
  85. <code>description</code> attribute are listed as &quot;Main targets&quot;,
  86. those without a <code>description</code> are listed as
  87. &quot;Other targets&quot;, then the &quot;Default&quot; target is listed
  88. ("Other targets" are only displayed if there are no main
  89. targets, or if Ant is invoked in -verbose or -debug mode).
  90. <h3><a name="options">Command-line Options Summary</a></h3>
  91. <pre>ant [options] [target [target2 [target3] ...]]
  92. Options:
  93. -help, -h print this message and exit
  94. -projecthelp, -p print project help information and exit
  95. -version print the version information and exit
  96. -diagnostics print information that might be helpful to
  97. diagnose or report problems and exit
  98. -quiet, -q be extra quiet
  99. -silent, -S print nothing but task outputs and build failures
  100. -verbose, -v be extra verbose
  101. -debug, -d print debugging information
  102. -emacs, -e produce logging information without adornments
  103. -lib &lt;path&gt; specifies a path to search for jars and classes
  104. -logfile &lt;file&gt; use given file for log
  105. -l &lt;file&gt; ''
  106. -logger &lt;classname&gt; the class which is to perform logging
  107. -listener &lt;classname&gt; add an instance of class as a project listener
  108. -noinput do not allow interactive input
  109. -buildfile &lt;file&gt; use given buildfile
  110. -file &lt;file&gt; ''
  111. -f &lt;file&gt; ''
  112. -D&lt;property&gt;=&lt;value&gt; use value for given property
  113. -keep-going, -k execute all targets that do not depend
  114. on failed target(s)
  115. -propertyfile &lt;name&gt; load all properties from file with -D
  116. properties taking precedence
  117. -inputhandler &lt;class&gt; the class which will handle input requests
  118. -find &lt;file&gt; (s)earch for buildfile towards the root of
  119. -s &lt;file&gt; the filesystem and use it
  120. -nice number A niceness value for the main thread:
  121. 1 (lowest) to 10 (highest); 5 is the default
  122. -nouserlib Run ant without using the jar files from ${user.home}/.ant/lib
  123. -noclasspath Run ant without using CLASSPATH
  124. -autoproxy Java 1.5+ : use the OS proxies
  125. -main &lt;class&gt; override Ant's normal entry point
  126. </pre>
  127. <p>For more information about <code>-logger</code> and
  128. <code>-listener</code> see
  129. <a href="listeners.html">Loggers &amp; Listeners</a>.
  130. <p>For more information about <code>-inputhandler</code> see
  131. <a href="inputhandler.html">InputHandler</a>.
  132. <p>Easiest way of changing the exit-behaviour is subclassing the original main class:
  133. <pre>
  134. public class CustomExitCode extends org.apache.tools.ant.Main {
  135. protected void exit(int exitCode) {
  136. // implement your own behaviour, e.g. NOT exiting the JVM
  137. }
  138. }
  139. </pre> and starting Ant with access (<tt>-lib path-to-class</tt>) to this class.
  140. </p>
  141. <h3><a name="libs">Library Directories</a></h3>
  142. <p>
  143. Prior to Ant 1.6, all jars in the ANT_HOME/lib would be added to the CLASSPATH
  144. used to run Ant. This was done in the scripts that started Ant. From Ant 1.6,
  145. two directories are scanned by default and more can be added as required. The
  146. default directories scanned are ANT_HOME/lib and a user specific directory,
  147. ${user.home}/.ant/lib. This arrangement allows the Ant installation to be
  148. shared by many users while still allowing each user to deploy additional jars.
  149. Such additional jars could be support jars for Ant's optional tasks or jars
  150. containing third-party tasks to be used in the build. It also allows the main Ant installation to be locked down which will please system administrators.
  151. </p>
  152. <p>
  153. Additional directories to be searched may be added by using the -lib option.
  154. The -lib option specifies a search path. Any jars or classes in the directories
  155. of the path will be added to Ant's classloader. The order in which jars are
  156. added to the classpath is as follows:
  157. </p>
  158. <ul>
  159. <li>-lib jars in the order specified by the -lib elements on the command line</li>
  160. <li>jars from ${user.home}/.ant/lib (unless -nouserlib is set)</li>
  161. <li>jars from ANT_HOME/lib</li>
  162. </ul>
  163. <p>
  164. Note that the CLASSPATH environment variable is passed to Ant using a -lib
  165. option. Ant itself is started with a very minimalistic classpath.
  166. Ant should work perfectly well with an empty CLASSPATH environment variable,
  167. something the the -noclasspath option actually enforces. We get many more support calls related to classpath problems (especially quoting problems) than
  168. we like.
  169. </p>
  170. <p>
  171. The location of ${user.home}/.ant/lib is somewhat dependent on the JVM. On Unix
  172. systems ${user.home} maps to the user's home directory whilst on recent
  173. versions of Windows it will be somewhere such as
  174. C:\Documents&nbsp;and&nbsp;Settings\username\.ant\lib. You should consult your
  175. JVM documentation for more details.
  176. </p>
  177. <h3>Examples</h3>
  178. <blockquote>
  179. <pre>ant</pre>
  180. </blockquote>
  181. <p>runs Ant using the <code>build.xml</code> file in the current directory, on
  182. the default target.</p>
  183. <blockquote>
  184. <pre>ant -buildfile test.xml</pre>
  185. </blockquote>
  186. <p>runs Ant using the <code>test.xml</code> file in the current directory, on
  187. the default target.</p>
  188. <blockquote>
  189. <pre>ant -buildfile test.xml dist</pre>
  190. </blockquote>
  191. <p>runs Ant using the <code>test.xml</code> file in the current directory, on
  192. the target called <code>dist</code>.</p>
  193. <blockquote>
  194. <pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre>
  195. </blockquote>
  196. <p>runs Ant using the <code>test.xml</code> file in the current directory, on
  197. the target called <code>dist</code>, setting the <code>build</code> property
  198. to the value <code>build/classes</code>.</p>
  199. <blockquote>
  200. <pre>ant -lib /home/ant/extras</pre>
  201. </blockquote>
  202. <p>runs Ant picking up additional task and support jars from the
  203. /home/ant/extras location</p>
  204. <blockquote>
  205. <pre>ant -lib one.jar;another.jar</pre>
  206. <pre>ant -lib one.jar -lib another.jar</pre>
  207. </blockquote>
  208. <p>adds two jars to Ants classpath.</p>
  209. <h3><a name="files">Files</a></h3>
  210. <p>The Ant wrapper script for Unix will source (read and evaluate) the
  211. file <code>~/.antrc</code> before it does anything. On Windows, the Ant
  212. wrapper batch-file invokes <code>%HOME%\antrc_pre.bat</code> at the start and
  213. <code>%HOME%\antrc_post.bat</code> at the end. You can use these
  214. files, for example, to set/unset environment variables that should only be
  215. visible during the execution of Ant. See the next section for examples.</p>
  216. <h3><a name="envvars">Environment Variables</a></h3>
  217. <p>The wrapper scripts use the following environment variables (if
  218. set):</p>
  219. <ul>
  220. <li><code>JAVACMD</code> - full path of the Java executable. Use this
  221. to invoke a different JVM than <code>JAVA_HOME/bin/java(.exe)</code>.</li>
  222. <li><code>ANT_OPTS</code> - command-line arguments that should be
  223. passed to the JVM. For example, you can define system properties or set
  224. the maximum Java heap size here.</li>
  225. <li><code>ANT_ARGS</code> - Ant command-line arguments. For example,
  226. set <code>ANT_ARGS</code> to point to a different logger, include a
  227. listener, and to include the <code>-find</code> flag.</li>
  228. <strong>Note:</strong> If you include <code>-find</code>
  229. in <code>ANT_ARGS</code>, you should include the name of the build file
  230. to find, even if the file is called <code>build.xml</code>.
  231. </ul>
  232. <h3><a name="sysprops">Java System Properties</a></h3>
  233. <p>Some of Ant's core classes can be configured via system properties.</p>
  234. <p>Here is the result of a search through the codebase. Because system properties are
  235. available via Project instance, I searched for them with a
  236. <pre>
  237. grep -r -n "getPropert" * &gt; ..\grep.txt
  238. </pre>
  239. command. After that I filtered out the often-used but not-so-important values (most of them
  240. read-only values): <i>path.separator, ant.home, basedir, user.dir, os.name,
  241. line.separator, java.home, java.version, java.version, user.home, java.class.path</i><br>
  242. And I filtered out the <i>getPropertyHelper</i> access.</p>
  243. <table border="1">
  244. <tr>
  245. <th>property name</th>
  246. <th>valid values /default value</th>
  247. <th>description</th>
  248. </tr>
  249. <tr>
  250. <td><code>ant.build.javac.source</code></td>
  251. <td>Source-level version number</td>
  252. <td>Default <em>source</em> value for &lt;javac&gt;/&lt;javadoc&gt;</td>
  253. </tr>
  254. <tr>
  255. <td><code>ant.build.javac.target</code></td>
  256. <td>Class-compatibility version number</td>
  257. <td>Default <em>target</em> value for &lt;javac&gt;</td>
  258. </tr>
  259. <tr>
  260. <td><code>ant.executor.class</code></td>
  261. <td>classname; default is org. apache. tools. ant. helper. DefaultExecutor</td>
  262. <td><b>Since Ant 1.6.3</b> Ant will delegate Target invocation to the
  263. org.apache.tools.ant.Executor implementation specified here.
  264. </td>
  265. </tr>
  266. <tr>
  267. <td><code>ant.file</code></td>
  268. <td>read only: full filename of the build file</td>
  269. <td>This is set to the name of the build file. In
  270. <a href="Tasks/import.html">
  271. &lt;import&gt;-ed</a> files, this is set to the containing build file.
  272. </td>
  273. </tr>
  274. <tr>
  275. <td><code>ant.file.*</code></td>
  276. <td>read only: full filename of the build file of Ant projects
  277. </td>
  278. <td>This is set to the name of a file by project;
  279. this lets you determine the location of <a href="Tasks/import.html">
  280. &lt;import&gt;-ed</a> files,
  281. </td>
  282. </tr>
  283. <tr>
  284. <td><code>ant.input.properties</code></td>
  285. <td>filename (required)</td>
  286. <td>Name of the file holding the values for the
  287. <a href="inputhandler.html">PropertyFileInputHandler</a>.
  288. </td>
  289. </tr>
  290. <tr>
  291. <td><code>ant.logger.defaults</code></td>
  292. <!-- add the blank after the slash, so the browser can do a line break -->
  293. <td>filename (optional, default '/org/ apache/ tools/ ant/ listener/ defaults.properties')</td>
  294. <td>Name of the file holding the color mappings for the
  295. <a href="listeners.html#AnsiColorLogger">AnsiColorLogger</a>.
  296. </td>
  297. </tr>
  298. <tr>
  299. <td><code>ant.netrexxc.*</code></td>
  300. <td>several formats</td>
  301. <td>Use specified values as defaults for <a href="Tasks/netrexxc.html">netrexxc</a>.
  302. </td>
  303. </tr>
  304. <tr>
  305. <td><code>ant.PropertyHelper</code></td>
  306. <td>ant-reference-name (optional)</td>
  307. <td>Specify the PropertyHelper to use. The object must be of the type
  308. org.apache.tools.ant.PropertyHelper. If not defined an object of
  309. org.apache.tools.ant.PropertyHelper will be used as PropertyHelper.
  310. </td>
  311. </tr>
  312. <tr>
  313. <td><code>ant.regexp.regexpimpl</code></td>
  314. <td>classname</td>
  315. <td>classname for a RegExp implementation; if not set Ant uses JDK 1.4's implementation;
  316. <a href="Types/mapper.html#regexp-mapper">RegExp-Mapper</a>
  317. "Choice of regular expression implementation"
  318. </td>
  319. </tr>
  320. <tr>
  321. <td><code>ant.reuse.loader</code></td>
  322. <td>boolean</td>
  323. <td>allow to reuse classloaders
  324. used in org.apache.tools.ant.util.ClasspathUtil
  325. </td>
  326. </tr>
  327. <tr>
  328. <td><code>ant.XmlLogger.stylesheet.uri</code></td>
  329. <td>filename (default 'log.xsl')</td>
  330. <td>Name for the stylesheet to include in the logfile by
  331. <a href="listeners.html#XmlLogger">XmlLogger</a>.
  332. </td>
  333. </tr>
  334. <tr>
  335. <td><code>build.compiler</code></td>
  336. <td>name</td>
  337. <td>Specify the default compiler to use.
  338. see <a href="Tasks/javac.html">javac</a>,
  339. <a href="Tasks/ejb.html#ejbjar_weblogic">EJB Tasks</a>
  340. (compiler attribute),
  341. <a href="Tasks/javah.html">javah</a>
  342. </td>
  343. </tr>
  344. <tr>
  345. <td><code>build.compiler.emacs</code></td>
  346. <td>boolean (default false)</td>
  347. <td>Enable emacs-compatible error messages.
  348. see <a href="Tasks/javac.html">javac</a> "Jikes Notes"
  349. </td>
  350. </tr>
  351. <tr>
  352. <td><code>build.compiler.fulldepend</code></td>
  353. <td>boolean (default false)</td>
  354. <td>Enable full dependency checking
  355. see <a href="Tasks/javac.html">javac</a> "Jikes Notes"
  356. </td>
  357. </tr>
  358. <tr>
  359. <td><code>build.compiler.jvc.extensions</code></td>
  360. <td>boolean (default true)</td>
  361. <td>enable Microsoft extensions of their java compiler
  362. see <a href="Tasks/javac.html">javac</a> "Jvc Notes"
  363. </td>
  364. </tr>
  365. <tr>
  366. <td><code>build.compiler.pedantic</code></td>
  367. <td>boolean (default false)</td>
  368. <td>Enable pedantic warnings.
  369. see <a href="Tasks/javac.html">javac</a> "Jikes Notes"
  370. </td>
  371. </tr>
  372. <tr>
  373. <td><code>build.compiler.warnings</code></td>
  374. <td>Deprecated flag</td>
  375. <td> see <a href="Tasks/javac.html">javac</a> "Jikes Notes" </td>
  376. </tr>
  377. <tr>
  378. <td><code>build.rmic</code></td>
  379. <td>name</td>
  380. <td>control the <a href="Tasks/rmic.html">rmic</a> compiler </td>
  381. </tr>
  382. <tr>
  383. <td><code>build.sysclasspath</code></td>
  384. <td>see <a href="sysclasspath.html">its dedicated page</a>, no
  385. default value</td>
  386. <td>see <a href="sysclasspath.html">its dedicated page</a></td>
  387. </tr>
  388. <tr>
  389. <td><code>file.encoding</code></td>
  390. <td>name of a supported character set (e.g. UTF-8, ISO-8859-1, US-ASCII)</td>
  391. <td>use as default character set of email messages; use as default for source-, dest- and bundleencoding
  392. in <a href="Tasks/translate.html">translate</a> <br>
  393. see JavaDoc of <a target="_blank" href="http://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">java.nio.charset.Charset</a>
  394. for more information about character sets (not used in Ant, but has nice docs).
  395. </td>
  396. </tr>
  397. <tr>
  398. <td><code>jikes.class.path</code></td>
  399. <td>path</td>
  400. <td>The specified path is added to the classpath if jikes is used as compiler.</td>
  401. </tr>
  402. <tr>
  403. <td><code>MailLogger.properties.file, MailLogger.*</code></td>
  404. <td>filename (optional, defaults derived from Project instance)</td>
  405. <td>Name of the file holding properties for sending emails by the
  406. <a href="listeners.html#MailLogger">MailLogger</a>. Override properties set
  407. inside the buildfile or via command line.
  408. </td>
  409. </tr>
  410. <tr>
  411. <td><code>org.apache.tools.ant.ProjectHelper</code></td>
  412. <!-- add the blank after the slash, so the browser can do a line break -->
  413. <td>classname (optional, default 'org.apache.tools.ant.ProjectHelper2')</td>
  414. <td>specifies the classname to use as ProjectHelper. The class must extend
  415. org.apache.tools.ant.ProjectHelper.
  416. </td>
  417. </tr>
  418. <tr>
  419. <td><code>org.apache.tools.ant.ArgumentProcessor</code></td>
  420. <td>classname (optional)</td>
  421. <td>specifies the classname to use as ArgumentProcessor. The class must extend
  422. org.apache.tools.ant.ArgumentProcessor.
  423. </td>
  424. </tr>
  425. <tr>
  426. <td><code>websphere.home</code></td>
  427. <td>path</td>
  428. <td>Points to home directory of websphere.
  429. see <a href="Tasks/ejb.html#ejbjar_websphere">EJB Tasks</a>
  430. </td>
  431. </tr>
  432. <tr>
  433. <td><code>XmlLogger.file</code></td>
  434. <td>filename (default 'log.xml')</td>
  435. <td>Name for the logfile for <a href="listeners.html#MailLogger">MailLogger</a>.
  436. </td>
  437. </tr>
  438. <tr>
  439. <td><code>ant.project-helper-repo.debug</code></td>
  440. <td>boolean (default 'false')</td>
  441. <td>Set it to true to enable debugging with Ant's
  442. <a href="projecthelper.html#repository">ProjectHelper internal repository</a>.
  443. </td>
  444. </tr>
  445. <tr>
  446. <td><code>ant.argument-processor-repo.debug</code></td>
  447. <td>boolean (default 'false')</td>
  448. <td>Set it to true to enable debugging with Ant's
  449. <a href="argumentprocessor.html#repository">ArgumentProcessor internal repository</a>.
  450. </td>
  451. </tr>
  452. <tr>
  453. <td><code>ant.tstamp.now</code></td>
  454. <td>number, seconds since the epoch (midnight 1970-01-01)</td>
  455. <td>The value to use as current time and date for &lt;tstamp&gt;</td>
  456. </tr>
  457. </table>
  458. <p>
  459. If new properties get added (it happens), expect them to appear under the
  460. "ant." and "org.apache.tools.ant" prefixes, unless the developers have a
  461. very good reason to use another prefix. Accordingly, please avoid using
  462. properties that begin with these prefixes. This protects you from future
  463. Ant releases breaking your build file.
  464. </p>
  465. <h3>return code</h3>
  466. <p>the ant start up scripts (in their Windows and Unix version) return
  467. the return code of the java program. So a successful build returns 0,
  468. failed builds return other values.
  469. </p>
  470. <h2><a name="cygwin">Cygwin Users</a></h2>
  471. <p>The Unix launch script that come with Ant works correctly with Cygwin. You
  472. should not have any problems launching Ant from the Cygwin shell. It is
  473. important to note, however, that once Ant is running it is part of the JDK
  474. which operates as a native Windows application. The JDK is not a Cygwin
  475. executable, and it therefore has no knowledge of Cygwin paths, etc. In
  476. particular when using the <code>&lt;exec&gt;</code> task, executable names such
  477. as &quot;/bin/sh&quot; will not work, even though these work from the Cygwin
  478. shell from which Ant was launched. You can use an executable name such as
  479. &quot;sh&quot; and rely on that command being available in the Windows path.
  480. </p>
  481. <h2><a name="os2">OS/2 Users</a></h2>
  482. <p>The OS/2 launch script was developed to perform complex tasks. It has two parts:
  483. <code>ant.cmd</code> which calls Ant and <code>antenv.cmd</code> which sets the environment for Ant.
  484. Most often you will just call <code>ant.cmd</code> using the same command line options as described
  485. above. The behaviour can be modified by a number of ways explained below.</p>
  486. <p>Script <code>ant.cmd</code> first verifies whether the Ant environment is set correctly. The
  487. requirements are:</p>
  488. <ol>
  489. <li>Environment variable <code>JAVA_HOME</code> is set.</li>
  490. <li>Environment variable <code>ANT_HOME</code> is set.</li>
  491. <li>Environment variable <code>CLASSPATH</code> is set and contains at least one element from
  492. <code>JAVA_HOME</code> and at least one element from <code>ANT_HOME</code>.</li>
  493. </ol>
  494. <p>If any of these conditions is violated, script <code>antenv.cmd</code> is called. This script
  495. first invokes configuration scripts if there exist: the system-wide configuration
  496. <code>antconf.cmd</code> from the <code>%ETC%</code> directory and then the user configuration
  497. <code>antrc.cmd</code> from the <code>%HOME%</code> directory. At this moment both
  498. <code>JAVA_HOME</code> and <code>ANT_HOME</code> must be defined because <code>antenv.cmd</code>
  499. now adds <code>classes.zip</code> or <code>tools.jar</code> (depending on version of JVM) and
  500. everything from <code>%ANT_HOME%\lib</code> except <code>ant-*.jar</code> to
  501. <code>CLASSPATH</code>. Finally <code>ant.cmd</code> calls per-directory configuration
  502. <code>antrc.cmd</code>. All settings made by <code>ant.cmd</code> are local and are undone when the
  503. script ends. The settings made by <code>antenv.cmd</code> are persistent during the lifetime of the
  504. shell (of course unless called automatically from <code>ant.cmd</code>). It is thus possible to call
  505. <code>antenv.cmd</code> manually and modify some settings before calling <code>ant.cmd</code>.</p>
  506. <p>Scripts <code>envset.cmd</code> and <code>runrc.cmd</code> perform auxiliary tasks. All scripts
  507. have some documentation inside.</p>
  508. <h2><a name="background">Running Ant as a background process on
  509. Unix(-like) systems</a></h2>
  510. <p>If you start Ant as a background process (like in <code>ant
  511. &amp;</code>) and the build process creates another process, Ant will
  512. immediately try to read from standard input, which in turn will
  513. most likely suspend the process. In order to avoid this, you must
  514. redirect Ant's standard input or explicitly provide input to each
  515. spawned process via the input related attributes of the
  516. corresponding tasks.</p>
  517. <p>Tasks that create such new processes
  518. include <code>&lt;exec&gt;</code>, <code>&lt;apply&gt;</code>
  519. or <code>&lt;java&gt;</code> when the <code>fork</code> attribute is
  520. <code>true</code>.</p>
  521. <h2><a name="viajava">Running Ant via Java</a></h2>
  522. <p>If you have installed Ant in the do-it-yourself way, Ant can be started
  523. from one of two entry points:</p>
  524. <blockquote>
  525. <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
  526. </blockquote>
  527. <blockquote>
  528. <pre>java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]</pre>
  529. </blockquote>
  530. <p>
  531. The first method runs Ant's traditional entry point. The second method uses
  532. the Ant Launcher introduced in Ant 1.6. The former method does not support
  533. the -lib option and all required classes are loaded from the CLASSPATH. You must
  534. ensure that all required jars are available. At a minimum the CLASSPATH should
  535. include:
  536. </p>
  537. <ul>
  538. <li><code>ant.jar</code> and <code>ant-launcher.jar</code></li>
  539. <li>jars/classes for your XML parser</li>
  540. <li>the JDK's required jar/zip files</li>
  541. </ul>
  542. <p>
  543. The latter method supports the -lib, -nouserlib, -noclasspath options and will
  544. load jars from the specified ANT_HOME. You should start the latter with the most minimal
  545. classpath possible, generally just the ant-launcher.jar.
  546. </p>
  547. <a name="viaant"/>
  548. Ant can be started in Ant via the <code>&lt;java&gt;</code> command.
  549. Here is an example:
  550. <pre>
  551. &lt;java
  552. classname="org.apache.tools.ant.launch.Launcher"
  553. fork="true"
  554. failonerror="true"
  555. dir="${sub.builddir}"
  556. timeout="4000000"
  557. taskname="startAnt"&gt;
  558. &lt;classpath&gt;
  559. &lt;pathelement location="${ant.home}/lib/ant-launcher.jar"/&gt;
  560. &lt;/classpath&gt;
  561. &lt;arg value="-buildfile"/&gt;
  562. &lt;arg file="${sub.buildfile}"/&gt;
  563. &lt;arg value="-Dthis=this"/&gt;
  564. &lt;arg value="-Dthat=that"/&gt;
  565. &lt;arg value="-Dbasedir=${sub.builddir}"/&gt;
  566. &lt;arg value="-Dthe.other=the.other"/&gt;
  567. &lt;arg value="${sub.target}"/&gt;
  568. &lt;/java&gt;
  569. </pre>
  570. <br>
  571. </body>
  572. </html>