docs/manual/running.html - ant - Git at Google

 <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>&lt;project&gt;</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 &quot;Main targets&quot;,
 those without a <code>description</code> are listed as
 &quot;Subtargets&quot;, then the &quot;Default&quot; 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 &lt;file&gt;        write logging output to given file
   -logger &lt;classname&gt;    the class that is to perform logging
   -listener &lt;classname&gt;  add an instance of <i>classname</i> as a project listener
   -buildfile &lt;file&gt;      use given build file
   -D&lt;property&gt;=&lt;value&gt;   use value for given property
   -propertyfile &lt;file&gt;   load all properties from <i>file</i> (with -D taking precedence)
   -inputhandler &lt;class&gt;  the class that will handle input requests
   -find [&lt;file&gt;]         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 &amp; 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 &copy; 2000-2002 Apache Software Foundation. All rights
 Reserved.</p>

 </body>
 </html>
	<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>