| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Running Apache Ant</title> |
| </head> |
| |
| <body> |
| |
| <h1>Running Ant</h1> |
| <h2><a name="commandline">Command Line</a></h2> |
| <p> If you've installed Ant as described in the |
| <a href="install.html"> Installing Ant</a> section, |
| running Ant from the command-line is simple: just type |
| <code>ant</code>.</p> |
| <p>When no arguments are specified, Ant looks for a <code>build.xml</code> |
| file in the current directory and, if found, uses that file as the |
| build file and runs the target specified in the <code>default</code> |
| attribute of the <code><project></code> tag. |
| To make Ant use |
| a build file other than <code>build.xml</code>, use the command-line |
| option <nobr><code>-buildfile <i>file</i></code></nobr>, |
| where <i>file</i> is the name of the build file you want to use.</p> |
| If you use the <nobr><code>-find [<i>file</i>]</code></nobr> option, |
| Ant will search for a build file first in the current directory, then in |
| the parent directory, and so on, until either a build file is found or the root |
| of the filesystem has been reached. By default, it will look for a build file |
| called <code>build.xml</code>. To have it search for a build file other |
| than <code>build.xml</code>, specify a file argument. |
| <strong>Note:</strong> If you include any other flags or arguments |
| on the command line after |
| the <nobr><code>-find</code></nobr> flag, you must include the file argument |
| for the <nobr><code>-find</code></nobr> flag, even if the name of the |
| build file you want to find is <code>build.xml</code>. |
| |
| <p>You can also set <a href="using.html#properties">properties</a> on the |
| command line. This can be done with |
| the <nobr><code>-D<i>property</i>=<i>value</i></code></nobr> option, |
| where <i>property</i> is the name of the property, |
| and <i>value</i> is the value for that property. If you specify a |
| property that is also set in the build file |
| (see the <a href="CoreTasks/property.html">property</a> task), |
| the value specified on the |
| command line will override the value specified in the |
| build file. |
| Defining properties on the command line can also be used to pass in |
| the value of environment variables - just pass |
| <nobr><code>-DMYVAR=%MYVAR%</code></nobr> (Windows) or |
| <nobr><code>-DMYVAR=$MYVAR</code></nobr> (Unix) |
| to Ant. You can then access |
| these variables inside your build file as <code>${MYVAR}</code>. |
| You can also access environment variables using the |
| <a href="CoreTasks/property.html"> property</a> task's |
| <code>environment</code> attribute. |
| </p> |
| |
| <p>Options that affect the amount of logging output by Ant are: |
| <nobr><code>-quiet</code></nobr>, |
| which instructs Ant to print less |
| information to the console; |
| <nobr><code>-verbose</code></nobr>, which causes Ant to print |
| additional information to the console; and <nobr><code>-debug</code></nobr>, |
| which causes Ant to print considerably more additional information. |
| </p> |
| |
| <p>It is also possible to specify one or more targets that should be executed. |
| When omitted, the target that is specified in the |
| <code>default</code> attribute of the |
| <a href="using.html#projects"><code>project</code></a> tag is |
| used.</p> |
| |
| <p>The <nobr><code>-projecthelp</code></nobr> option prints out a list |
| of the build file's targets. Targets that include a |
| <code>description</code> attribute are listed as "Main targets", |
| those without a <code>description</code> are listed as |
| "Subtargets", then the "Default" target is listed. |
| |
| <h3><a name="options">Command-line Options Summary</a></h3> |
| <pre>ant [options] [target [target2 [target3] ...]] |
| Options: |
| -help print this message |
| -projecthelp print project help information |
| -version print the version information and exit |
| -quiet be extra quiet |
| -verbose be extra verbose |
| -debug print debugging information |
| -emacs produce logging information without adornments |
| -logfile <file> write logging output to given file |
| -logger <classname> the class that is to perform logging |
| -listener <classname> add an instance of <i>classname</i> as a project listener |
| -buildfile <file> use given build file |
| -D<property>=<value> use value for given property |
| -propertyfile <file> load all properties from <i>file</i> (with -D taking precedence) |
| -inputhandler <class> the class that will handle input requests |
| -find [<file>] search for build.xml, or <i>file</i>, towards the root of the |
| filesystem |
| </pre> |
| <p>For more information about <code>-logger</code> and |
| <code>-listener</code> see |
| <a href="listeners.html">Loggers & Listeners</a>. |
| <p>For more information about <code>-inputhandler</code> see |
| <a href="inputhandler.html">InputHandler</a>. |
| |
| <h3>Examples</h3> |
| <blockquote> |
| <pre>ant</pre> |
| </blockquote> |
| <p>runs Ant using the <code>build.xml</code> file in the current directory, on |
| the default target.</p> |
| <blockquote> |
| <pre>ant -buildfile test.xml</pre> |
| </blockquote> |
| <p>runs Ant using the <code>test.xml</code> file in the current directory, on |
| the default target.</p> |
| <blockquote> |
| <pre>ant -buildfile test.xml dist</pre> |
| </blockquote> |
| <p>runs Ant using the <code>test.xml</code> file in the current directory, on |
| the target called <code>dist</code>.</p> |
| <blockquote> |
| <pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre> |
| </blockquote> |
| <p>runs Ant using the <code>test.xml</code> file in the current directory, on |
| the target called <code>dist</code>, setting the <code>build</code> property |
| to the value <code>build/classes</code>.</p> |
| |
| <h3><a name="files">Files</a></h3> |
| |
| <p>The Ant wrapper script for Unix will source (read and evaluate) the |
| file <code>~/.antrc</code> before it does anything. On Windows, the Ant |
| wrapper batch-file invokes <code>%HOME%\antrc_pre.bat</code> at the start and |
| <code>%HOME%\antrc_post.bat</code> at the end. You can use these |
| files, for example, to set/unset environment variables that should only be |
| visible during the execution of Ant. See the next section for examples.</p> |
| |
| <h3><a name="envvars">Environment Variables</a></h3> |
| |
| <p>The wrapper scripts use the following environment variables (if |
| set):</p> |
| |
| <ul> |
| <li><code>JAVACMD</code> - full path of the Java executable. Use this |
| to invoke a different JVM than <code>JAVA_HOME/bin/java(.exe)</code>.</li> |
| |
| <li><code>ANT_OPTS</code> - command-line arguments that should be |
| passed to the JVM. For example, you can define system properties or set |
| the maximum Java heap size here.</li> |
| |
| <li><code>ANT_ARGS</code> - Ant command-line arguments. For example, |
| set <code>ANT_ARGS</code> to point to a different logger, include a |
| listener, and to include the <code>-find</code> flag.</li> |
| <strong>Note:</strong> If you include <code>-find</code> |
| in <code>ANT_ARGS</code>, you should include the name of the build file |
| to find, even if the file is called <code>build.xml</code>. |
| </ul> |
| |
| <h2><a name="viajava">Running Ant via Java</a></h2> |
| <p>If you have installed Ant in the do-it-yourself way, Ant can be started |
| with:</p> |
| <blockquote> |
| <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre> |
| </blockquote> |
| |
| <p>These instructions actually do exactly the same as the <code>ant</code> |
| command. The options and target are the same as when running Ant with the <code>ant</code> |
| command. This example assumes you have set your classpath to include:</p> |
| <ul> |
| <li><code>ant.jar</code></li> |
| <li>jars/classes for your XML parser</li> |
| <li>the JDK's required jar/zip files</li> |
| </ul> |
| <br> |
| <hr> |
| <p align="center">Copyright © 2000-2002 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |