You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by gi...@apache.org on 2018/02/28 07:01:23 UTC
[08/47] ant git commit: Use HTML 5(-ish), fix links
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/proxy.html
----------------------------------------------------------------------
diff --git a/manual/proxy.html b/manual/proxy.html
index f614803..a2cd7f8 100644
--- a/manual/proxy.html
+++ b/manual/proxy.html
@@ -26,80 +26,82 @@
<h2>Proxy Configuration</h2>
<p>
-This page discussing proxy issues on command-line Apache Ant.
-Consult your IDE documentation for IDE-specific information upon proxy setup.
+ This page discussing proxy issues on command-line Apache Ant.
+ Consult your IDE documentation for IDE-specific information upon
+ proxy setup.
</p>
<p>
-All tasks and threads running in Ant's JVM share the same HTTP/FTP/Socks
-proxy configuration.
+ All tasks and threads running in Ant's JVM share the same
+ HTTP/FTP/Socks proxy configuration.
</p>
<p>
- When any task tries to retrieve content from an HTTP page, including the
- <code><get></code> task, any automated URL retrieval in
- an XML/XSL task, or any third-party task that uses the <code>java.net.URL</code>
- classes, the proxy settings may make the difference between success and failure.
+ When any task tries to retrieve content from an HTTP page, including
+ the <code><get></code> task, any automated URL retrieval in an
+ XML/XSL task, or any third-party task that uses
+ the <code>java.net.URL</code> classes, the proxy settings may make
+ the difference between success and failure.
</p>
<p>
- Anyone authoring a build file behind a blocking firewall will immediately appreciate
- the problems and may want to write a build file to deal with the problem, but
- users of third party build build files may find that the build file itself
- does not work behind the firewall.
+ Anyone authoring a build file behind a blocking firewall will
+ immediately appreciate the problems and may want to write a build
+ file to deal with the problem, but users of third party build build
+ files may find that the build file itself does not work behind the
+ firewall.
</p>
<p>
- This is a long standing problem with Java and Ant. The only way to fix
- it is to explicitly configure Ant with the proxy settings, either
- by passing down the proxy details as JVM properties, or to
- tell Ant on a Java1.5+ system to have the JVM work it out for itself.
-
+ This is a long standing problem with Java and Ant. The only way to
+ fix it is to explicitly configure Ant with the proxy settings,
+ either by passing down the proxy details as JVM properties, or to
+ tell Ant on a Java 5+ system to have the JVM work it out for itself.
</p>
-<h3>Java1.5+ proxy support (<em>since Ant 1.7</em>)</h3>
+<h3>Java 5+ proxy support (<em>since Ant 1.7</em>)</h3>
<p>
- When Ant starts up, if the <code>-autoproxy</code>
- command is supplied, Ant sets the
- <code>java.net.useSystemProxies</code> system property. This tells
- a Java1.5+ JVM to use the current set of property settings of the host
- environment. Other JVMs, such as the Kaffe and Apache Harmony runtimes,
- may also use this property in future.
- It is ignored on the Java1.4 and earlier runtimes.
+ When Ant starts up, if the <code>-autoproxy</code> command is
+ supplied, Ant sets the <code>java.net.useSystemProxies</code> system
+ property. This tells a Java 5+ JVM to use the current set of
+ property settings of the host environment. Other JVMs, such as the
+ Kaffe and Apache Harmony runtimes, may also use this property in
+ future. It is ignored on the Java 1.4 and earlier runtimes.
</p>
<p>
- This property maybe enough to give command-line Ant
- builds network access, although in practise the results
- are inconsistent.
+ This property maybe enough to give command-line Ant builds network
+ access, although in practise the results are inconsistent.
</p>
<p>
- It is has also been reported a breaking the IBM Java 5 JRE on AIX,
- and does not always work on Linux (presumably due to missing gconf settings)
- Other odd things can go wrong, like Oracle JDBC drivers or pure Java SVN clients.
+ It is has also been reported a breaking the IBM Java 5 JRE on AIX,
+ and does not always work on Linux (presumably due to
+ missing <code>gconf</code> settings) Other odd things can go wrong,
+ like Oracle JDBC drivers or pure Java SVN clients.
</p>
-
<p>
- To make the <code>-autoproxy</code> option the default, add it to the environment variable
- <code>ANT_ARGS</code>, which contains a list of arguments to pass to Ant on every
- command line run.
+ To make the <code>-autoproxy</code> option the default, add it to
+ the environment variable <code>ANT_ARGS</code>, which contains a
+ list of arguments to pass to Ant on every command line run.
</p>
<h4>How Autoproxy works</h4>
<p>
-The <code>java.net.useSystemProxies</code> is checked only
-once, at startup time, the other checks (registry, gconf, system properties) are done
-dynamically whenever needed (socket connection, URL connection etc..).
+ The <code>java.net.useSystemProxies</code> is checked only once, at
+ startup time, the other checks (registry, <code>gconf</code>, system
+ properties) are done dynamically whenever needed (socket connection,
+ URL connection etc..).
</p>
<h5>Windows</h5>
<p>
-The JVM goes straight to the registry, bypassing WinInet, as it is not
-present/consistent on all supported Windows platforms (it is part of IE,
-really). Java 7 may use the Windows APIs on the platforms when it is present.
+ The JVM goes straight to the registry, bypassing WinInet, as it is
+ not present/consistent on all supported Windows platforms (it is
+ part of IE, really). Java 7 may use the Windows APIs on the
+ platforms when it is present.
</p>
<h5>Linux</h5>
<p>
-The JVM uses the gconf library to look at specific entries.
-The GConf-2 settings used are:
+ The JVM uses the <code>gconf</code> library to look at specific
+ entries. The <code>GConf-2</code> settings used are:
</p>
<pre>
- /system/http_proxy/use_http_proxy boolean
@@ -120,166 +122,166 @@ The GConf-2 settings used are:
- /system/proxy/gopher_port int
</pre>
<p>
-If you are using KDE or another GUI than Gnome, you can still use the
-<code>gconf-editor</code> tool to add these entries.
+ If you are using KDE or another GUI than Gnome, you can still use
+ the <code>gconf-editor</code> tool to add these entries.
</p>
<h3>Manual JVM options</h3>
<p>
- Any JVM can have its proxy options explicitly configured by passing
- the appropriate <code>-D</code> system property options to the runtime.
- Ant can be configured through all its shell scripts via the
- <code>ANT_OPTS</code> environment variable, which is a list of options to
- supply to Ant's JVM:
+ Any JVM can have its proxy options explicitly configured by passing
+ the appropriate <code>-D</code> system property options to the
+ runtime. Ant can be configured through all its shell scripts via
+ the <code>ANT_OPTS</code> environment variable, which is a list of
+ options to supply to Ant's JVM:
</p>
<p>
For bash:
</p>
-<pre>
- export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
-</pre>
- For csh/tcsh:
-<pre>
- setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
-</pre>
+<pre>export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"</pre>
+<p>
+For csh/tcsh:
+</p>
+<pre>setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"</pre>
<p>
-If you insert this line into the Ant shell script itself, it gets picked up
-by all continuous integration tools running on the system that call Ant via the
-command line.
+ If you insert this line into the Ant shell script itself, it gets
+ picked up by all continuous integration tools running on the system
+ that call Ant via the command line.
</p>
<p>
- For Windows, set the <code>ANT_OPTS</code> environment variable in the appropriate "My Computer"
- properties dialog box (winXP), "Computer" properties (Vista)
+ For Windows, set the <code>ANT_OPTS</code> environment variable in
+ the appropriate "My Computer" properties dialog box (XP), "Computer"
+ properties (Vista)
</p>
<p>
- This mechanism works across Java versions, is cross-platform and reliable.
- Once set, all build files run via the command line will automatically have
- their proxy setup correctly, without needing any build file changes. It also
- apparently overrides Ant's automatic proxy settings options.
+ This mechanism works across Java versions, is cross-platform and
+ reliable. Once set, all build files run via the command line will
+ automatically have their proxy setup correctly, without needing any
+ build file changes. It also apparently overrides Ant's automatic
+ proxy settings options.
</p>
<p>
It is limited in the following ways:
</p>
- <ol>
+<ol>
<li>Does not work under IDEs. These need their own proxy settings changed</li>
<li>Not dynamic enough to deal with laptop configuration changes.</li>
- </ol>
+</ol>
<h3>SetProxy Task</h3>
<p>
- The <a href="Tasks/setproxy.html">setproxy task</a> can be used to
- explicitly set a proxy in a build file. This manipulates the many proxy
- configuration properties of a JVM, and controls the proxy settings for all
- network operations in the same JVM from that moment.
+ The <a href="Tasks/setproxy.html">setproxy task</a> can be used to
+ explicitly set a proxy in a build file. This manipulates the many
+ proxy configuration properties of a JVM, and controls the proxy
+ settings for all network operations in the same JVM from that
+ moment.
</p>
<p>
- If you have a build file that is only to be used in-house, behind a firewall, on
- an older JVM, <i>and you cannot change Ant's JVM proxy settings</i>, then
- this is your best option. It is ugly and brittle, because the build file now contains
- system configuration information. It is also hard to get this right across
- the many possible proxy options of different users (none, HTTP, SOCKS).
+ If you have a build file that is only to be used in-house, behind a
+ firewall, on an older JVM, <em>and you cannot change Ant's JVM proxy
+ settings</em>, then this is your best option. It is ugly and
+ brittle, because the build file now contains system configuration
+ information. It is also hard to get this right across the many
+ possible proxy options of different users (none, HTTP, SOCKS).
</p>
-
<p>
- Note that proxy configurations set with this task will probably override
- any set by other mechanisms. It can also be used with fancy tricks to
- only set a proxy if the proxy is considered reachable:
+ Note that proxy configurations set with this task will probably
+ override any set by other mechanisms. It can also be used with fancy
+ tricks to only set a proxy if the proxy is considered reachable:
</p>
<pre>
- <target name="probe-proxy" depends="init">
- <condition property="proxy.enabled">
- <and>
- <isset property="proxy.host"/>
- <isreachable host="${proxy.host}"/>
- </and>
- </condition>
- </target>
+<target name="probe-proxy" depends="init">
+ <condition property="proxy.enabled">
+ <and>
+ <isset property="proxy.host"/>
+ <isreachable host="${proxy.host}"/>
+ </and>
+ </condition>
+</target>
- <target name="proxy" depends="probe-proxy" if="proxy.enabled">
- <property name="proxy.port" value="80"/>
- <property name="proxy.user" value=""/>
- <property name="proxy.pass" value=""/>
- <setproxy proxyhost="${proxy.host}" proxyport="${proxy.port}"
- proxyuser="${proxy.user}" proxypassword="${proxy.pass}"/>
- </target>
-</pre>
+<target name="proxy" depends="probe-proxy" if="proxy.enabled">
+ <property name="proxy.port" value="80"/>
+ <property name="proxy.user" value=""/>
+ <property name="proxy.pass" value=""/>
+ <setproxy proxyhost="${proxy.host}" proxyport="${proxy.port}"
+ proxyuser="${proxy.user}" proxypassword="${proxy.pass}"/>
+</target></pre>
<h3>Custom ProxySelector implementations</h3>
<p>
- As Java lets developers write their own ProxySelector implementations, it
- is theoretically possible for someone to write their own proxy selector class that uses
- different policies to determine proxy settings. There is no explicit support
- for this in Ant, and it has not, to the team's knowledge, been attempted.
+ As Java lets developers write their own ProxySelector
+ implementations, it is theoretically possible for someone to write
+ their own proxy selector class that uses different policies to
+ determine proxy settings. There is no explicit support for this in
+ Ant, and it has not, to the team's knowledge, been attempted.
</p>
<p>
- This could be the most flexible of solutions, as one could easily imagine
- an Ant-specific proxy selector that was driven off ant properties, rather
- than system properties. Developers could set proxy options in their
- custom build.properties files, and have this propagate.
+ This could be the most flexible of solutions, as one could easily
+ imagine an Ant-specific proxy selector that was driven off ant
+ properties, rather than system properties. Developers could set
+ proxy options in their custom build.properties files, and have this
+ propagate.
</p>
<p>
- One issue here is with concurrency: the default proxy selector is per-JVM,
- not per-thread, and so the proxy settings will apply to all sockets opened
- on all threads; we also have the problem of how to propagate options from
- one build to the JVM-wide selector.
+ One issue here is with concurrency: the default proxy selector is
+ per-JVM, not per-thread, and so the proxy settings will apply to all
+ sockets opened on all threads; we also have the problem of how to
+ propagate options from one build to the JVM-wide selector.
</p>
<h3>Configuring the Proxy settings of Java programs under Ant</h3>
<p>
- Any program that is executed with <code><java></code> without setting
- <code>fork="true"</code> will pick up the Ant's settings. If you need
- different values, set <code>fork="false"</code> and provide the values
+ Any program that is executed with <code><java></code> without
+ setting <var>fork</var>=<q>true</q> will pick up the Ant's
+ settings. If you need different values,
+ set <var>fork</var>=<q>false</q> and provide the values
in <code><sysproperty></code> elements.
</p>
<p>
- If you wish to have
- a forked process pick up the Ant's settings, use the
- <a href="Types/propertyset.html"><code><syspropertyset></code></a>
- element to propagate the normal proxy settings. The following propertyset
- is a datatype which can be referenced in a <code><java></code> task to
- pass down the current values.
-
+ If you wish to have a forked process pick up the Ant's settings, use
+ the <a href="Types/propertyset.html"><code><syspropertyset></code></a>
+ element to propagate the normal proxy settings. The following
+ propertyset is a datatype which can be referenced in
+ a <code><java></code> task to pass down the current values.
</p>
<pre>
-<propertyset id="proxy.properties">
- <propertyref prefix="java.net.useSystemProxies"/>
- <propertyref prefix="http."/>
- <propertyref prefix="https."/>
- <propertyref prefix="ftp."/>
- <propertyref prefix="socksProxy"/>
-</propertyset>
-</pre>
+<propertyset id="proxy.properties">
+ <propertyref prefix="java.net.useSystemProxies"/>
+ <propertyref prefix="http."/>
+ <propertyref prefix="https."/>
+ <propertyref prefix="ftp."/>
+ <propertyref prefix="socksProxy"/>
+</propertyset></pre>
<h3>Summary and conclusions</h3>
<p>
-There are four ways to set up proxies in Ant.
+ There are four ways to set up proxies in Ant.
</p>
<ol>
-<li>With Ant1.7 and Java 1.5+ using the <code>-autoproxy</code> parameter.</li>
-<li>Via JVM system properties -set these in the ANT_ARGS environment variable.</li>
-<li>Via the <setproxy> task.</li>
-<li>Custom ProxySelector implementations</li>
+ <li>With Ant 1.7 and Java 5+ using the <code>-autoproxy</code> parameter.</li>
+ <li>Via JVM system properties—set these in the <var>ANT_ARGS</var> environment variable.</li>
+ <li>Via the <setproxy> task.</li>
+ <li>Custom ProxySelector implementations</li>
</ol>
<p>
-Proxy settings are automatically shared with Java programs started under Ant <i>
-that are not forked</i>; to pass proxy settings down to subsidiary programs, use
-a propertyset.
+ Proxy settings are automatically shared with Java programs started
+ under Ant <em>that are not forked</em>; to pass proxy settings down
+ to subsidiary programs, use a propertyset.
</p>
<p>
-Over time, we expect the Java 5+ proxy features to stabilize, and for Java code
-to adapt to them. However, given the fact that it currently does break some
-builds, it will be some time before Ant enables the automatic proxy feature by
-default. Until then, you have to enable the <code>-autoproxy</code> option or
-use one of the alternate mechanisms to configure the JVM.
+ Over time, we expect the Java 5+ proxy features to stabilize, and
+ for Java code to adapt to them. However, given the fact that it
+ currently does break some builds, it will be some time before Ant
+ enables the automatic proxy feature by default. Until then, you have
+ to enable the <code>-autoproxy</code> option or use one of the
+ alternate mechanisms to configure the JVM.
+</p>
<h4>Further reading</h4>
<ul>
-<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html">
-Java Networking Properties</a>.
-</li>
+ <li><a href="https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html">Java Networking Properties</a>.</li>
</ul>
</body>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/running.html
----------------------------------------------------------------------
diff --git a/manual/running.html b/manual/running.html
index dbd7810..c87159b 100644
--- a/manual/running.html
+++ b/manual/running.html
@@ -26,76 +26,70 @@
<h1>Running Apache Ant</h1>
<h2 id="commandline">Command Line</h2>
-<p> If you've installed Apache 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 <code>-buildfile <i>file</i></code>,
-where <i>file</i> is the name of the build file you want to use
-(or a directory containing a <code>build.xml</code> file).</p>
-If you use the <code>-find [<i>file</i>]</code> 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 <code>-find</code> flag, you must include the file argument
-for the <code>-find</code> 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 <code>-D<i>property</i>=<i>value</i></code> 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="Tasks/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
-<code>-DMYVAR=%MYVAR%</code> (Windows) or
-<code>-DMYVAR=$MYVAR</code> (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="Tasks/property.html"> property</a> task's
-<code>environment</code> attribute.
-</p>
-<p>Options that affect the amount of logging output by Ant are:
-<code>-quiet</code>,
-which instructs Ant to print less
-information to the console;
-<code>-verbose</code>, which causes Ant to print
-additional information to the console; <code>-debug</code>,
-which causes Ant to print considerably more additional information; and
-<code>-silent</code> which makes Ant print nothing but task
-output and build failures (useful to capture Ant output by scripts).
-</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
+<p>If you've installed Apache 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 <samp>build.xml</samp> file in the current directory and, if found,
+uses that file as the build file and runs the target specified in
+the <var>default</var> attribute of the <code><project></code>
+tag. To make Ant use a build file other than <samp>build.xml</samp>,
+use the command-line option <code>-buildfile <em>file</em></code>,
+where <em>file</em> is the name of the build file you want to use (or
+a directory containing a <samp>build.xml</samp> file).</p>
+
+<p>If you use the <code>-find [<em>file</em>]</code> 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 <samp>build.xml</samp>. To have it search for a
+build file other than <samp>build.xml</samp>, specify a file
+argument. <strong>Note</strong>: If you include any other flags or
+arguments on the command line after the <code>-find</code> flag, you
+must include the file argument for the <code>-find</code> flag, even
+if the name of the build file you want to find
+is <samp>build.xml</samp>.</p>
+
+<p>You can also set <a href="using.html#properties">properties</a> on
+the command line. This can be done with
+the <code>-D<i>property</i>=<i>value</i></code> option,
+where <em>property</em> is the name of the property,
+and <em>value</em> is the value for that property. If you specify a
+property that is also set in the build file (see
+the <a href="Tasks/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 <code>-DMYVAR=%MYVAR%</code> (Windows)
+or <code>-DMYVAR=$MYVAR</code> (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="Tasks/property.html">property</a>
+task's <var>environment</var> attribute.</p>
+
+<p>Options that affect the amount of logging output by Ant
+are: <code>-quiet</code>, which instructs Ant to print less
+information to the console; <code>-verbose</code>, which causes Ant to
+print additional information to the console; <code>-debug</code>,
+which causes Ant to print considerably more additional information;
+and <code>-silent</code> which makes Ant print nothing but task output
+and build failures (useful to capture Ant output by scripts).</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 <var>default</var> attribute of
+the <a href="using.html#projects"><code>project</code></a> tag is
used.</p>
-<p>The <code>-projecthelp</code> 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
-"Other targets", then the "Default" target is listed
-("Other targets" are only displayed if there are no main
-targets, or if Ant is invoked in -verbose or -debug mode).
+<p>The <code>-projecthelp</code> option prints out a list of the build
+file's targets. Targets that include a <var>description</var>
+attribute are listed as "Main targets", those without
+a <var>description</var> are listed as "Other targets", then
+the "Default" target is listed ("Other targets" are only
+displayed if there are no main targets, or if Ant is invoked
+in <code>-verbose</code> or <code>-debug</code> mode).</p>
<h3 id="options">Command-line Options Summary</h3>
<pre>ant [options] [target [target2 [target3] ...]]
@@ -131,7 +125,7 @@ Options:
1 (lowest) to 10 (highest); 5 is the default
-nouserlib Run ant without using the jar files from ${user.home}/.ant/lib
-noclasspath Run ant without using CLASSPATH
- -autoproxy Java 1.5+ : use the OS proxies
+ -autoproxy Java 5+ : use the OS proxies
-main <class> override Ant's normal entry point
</pre>
<p>For more information about <code>-logger</code> and
@@ -147,71 +141,74 @@ public class CustomExitCode extends org.apache.tools.ant.Main {
}
}
</pre>
-<p>and starting Ant with access (<tt>-lib path-to-class</tt>) to this class.</p>
+<p>and starting Ant with access (<code>-lib <i>path-to-class</i></code>) to this class.</p>
<h3 id="libs">Library Directories</h3>
-<p>
-Prior to Ant 1.6, all jars in the ANT_HOME/lib would be added to the CLASSPATH
- used to run Ant. This was done in the scripts that started Ant. <em>Since Ant 1.6</em>,
-two directories are scanned by default and more can be added as required. The
-default directories scanned are ANT_HOME/lib and a user specific directory,
-${user.home}/.ant/lib. This arrangement allows the Ant installation to be
-shared by many users while still allowing each user to deploy additional jars.
-Such additional jars could be support jars for Ant's optional tasks or jars
-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.
-</p>
-<p>
-Additional directories to be searched may be added by using the -lib option.
-The -lib option specifies a search path. Any jars or classes in the directories
-of the path will be added to Ant's classloader. The order in which jars are
-added to the classpath is as follows:
-</p>
+<p>Prior to Ant 1.6, all jars in the <samp>ANT_HOME/lib</samp> would
+be added to the <samp>CLASSPATH</samp> used to run Ant. This was done
+in the scripts that started Ant. <em>Since Ant 1.6</em>, two
+directories are scanned by default and more can be added as
+required. The default directories scanned
+are <samp>ANT_HOME/lib</samp> and a user specific
+directory, <samp>${user.home}/.ant/lib</samp>. This arrangement allows
+the Ant installation to be shared by many users while still allowing
+each user to deploy additional jars. Such additional jars could be
+support jars for Ant's optional tasks or jars 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.</p>
+
+<p>Additional directories to be searched may be added by using
+the <code>-lib</code> option. The <code>-lib</code> option specifies
+a search path. Any jars or classes in the directories of the path will
+be added to Ant's classloader. The order in which jars are added to
+the classpath is as follows:</p>
<ul>
- <li>-lib jars in the order specified by the -lib elements on the command line</li>
- <li>jars from ${user.home}/.ant/lib (unless -nouserlib is set)</li>
- <li>jars from ANT_HOME/lib</li>
+ <li><code>-lib</code> jars in the order specified by the <code>-lib</code> options on the command line</li>
+ <li>jars from <samp>${user.home}/.ant/lib</samp> (unless <code>-nouserlib</code> is set)</li>
+ <li>jars from <samp>ANT_HOME/lib</samp></li>
</ul>
-<p>
-Note that the CLASSPATH environment variable is passed to Ant using a -lib
-option. Ant itself is started with a very minimalistic classpath.
-Ant should work perfectly well with an empty CLASSPATH environment variable,
-something the the -noclasspath option actually enforces. We get many more support calls related to classpath problems (especially quoting problems) than
-we like.
-</p>
-
-<p>
-The location of ${user.home}/.ant/lib is somewhat dependent on the JVM. On Unix
-systems ${user.home} maps to the user's home directory whilst on recent
-versions of Windows it will be somewhere such as
-C:\Documents and Settings\username\.ant\lib. You should consult your
-JVM documentation for more details.
-</p>
+<p>Note that the <code>CLASSPATH</code> environment variable is passed
+to Ant using a <code>-lib</code> option. Ant itself is started with a
+very minimalistic classpath. Ant should work perfectly well with an
+empty <code>CLASSPATH</code> environment variable, something the
+the <code>-noclasspath</code> option actually enforces. We get many
+more support calls related to classpath problems (especially quoting
+problems) than we like.</p>
+
+<p>The location of <samp>${user.home}/.ant/lib</samp> is somewhat
+dependent on the JVM. On Unix systems <samp>${user.home}</samp> maps
+to the user's home directory whilst on recent versions of Windows it
+will be somewhere such
+as <code>C:\Users\<i>username</i>\.ant\lib</code>. You should consult
+your JVM documentation for more details.</p>
<h3>Examples</h3>
<pre>ant</pre>
-<p>runs Ant using the <code>build.xml</code> file in the current directory, on
-the default target.</p>
+<p>runs Ant using the <samp>build.xml</samp> file in the current
+directory, on the default target.</p>
<pre>ant -buildfile test.xml</pre>
-<p>runs Ant using the <code>test.xml</code> file in the current directory, on
-the default target.</p>
+<p>runs Ant using the <samp>test.xml</samp> file in the current
+directory, on the default target.</p>
<pre>ant -buildfile test.xml dist</pre>
-<p>runs Ant using the <code>test.xml</code> file in the current directory, on
-the target called <code>dist</code>.</p>
+<p>runs Ant using the <samp>test.xml</samp> file in the current
+directory, on the target called <samp>dist</samp>.</p>
<pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre>
-<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>
+<p>runs Ant using the <samp>test.xml</samp> file in the current
+directory, on the target called <samp>dist</samp>, setting
+the <code>build</code> property to the
+value <samp>build/classes</samp>.</p>
<pre>ant -lib /home/ant/extras</pre>
-<p>runs Ant picking up additional task and support jars from the
-/home/ant/extras location</p>
+<p>runs Ant picking up additional task and support jars from
+the <samp>/home/ant/extras</samp> location</p>
<pre>ant -lib one.jar;another.jar</pre>
<pre>ant -lib one.jar -lib another.jar</pre>
@@ -220,95 +217,95 @@ to the value <code>build/classes</code>.</p>
<h3 id="files">Files</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>
+file <samp>~/.antrc</samp> before it does anything. On Windows, the
+Ant wrapper batch-file invokes <samp>%HOME%\antrc_pre.bat</samp> at
+the start and <samp>%HOME%\antrc_post.bat</samp> 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 id="envvars">Environment Variables</h3>
-<p>The wrapper scripts use the following environment variables (if
-set):</p>
+<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>JAVACMD</code>—full path of the Java executable. Use this
+ to invoke a different JVM than <samp>JAVA_HOME/bin/java(.exe)</samp>.</li>
- <li><code>ANT_OPTS</code> - command-line arguments that should be
+ <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,
+ <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.<br/>
- <strong>Note:</strong> If you include <code>-find</code>
+ <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>.</li>
+ to find, even if the file is called <samp>build.xml</samp>.</li>
</ul>
<h3 id="sysprops">Java System Properties</h3>
<p>Some of Ant's core classes can be configured via system properties.</p>
-<p>Here is the result of a search through the codebase. Because system properties are
- available via Project instance, I searched for them with a</p>
+<p>Here is the result of a search through the codebase. Because system
+properties are available via Project instance, I searched for them with a</p>
<pre>grep -r -n "getPropert" * > ..\grep.txt</pre>
-<p>command. After that I filtered out the often-used but not-so-important values (most of them
-read-only values): <i>path.separator, ant.home, basedir, user.dir, os.name,
-line.separator, java.home, java.version, java.version, user.home, java.class.path</i><br>
-And I filtered out the <i>getPropertyHelper</i> access.</p>
+<p>command. After that I filtered out the often-used but
+ not-so-important values (most of them read-only
+ values): <code>path.separator</code>, <code>ant.home</code>, <code>basedir</code>, <code>user.dir</code>, <code>os.name</code>, <code>line.separator</code>, <code>java.home</code>, <code>java.version</code>, <code>java.version</code>, <code>user.home</code>, <code>java.class.path</code><br/>
+ And I filtered out the <code>getPropertyHelper</code> access.</p>
+
<table>
<tr>
<th>property name</th>
- <th>valid values /default value</th>
+ <th>valid values/default value</th>
<th>description</th>
</tr>
<tr>
<td><code>ant.build.javac.source</code></td>
<td>Source-level version number</td>
- <td>Default <em>source</em> value for <javac>/<javadoc></td>
+ <td>Default <var>source</var> value for <javac>/<javadoc></td>
</tr>
<tr>
<td><code>ant.build.javac.target</code></td>
<td>Class-compatibility version number</td>
- <td>Default <em>target</em> value for <javac></td>
+ <td>Default <var>target</var> value for <javac></td>
</tr>
<tr>
<td><code>ant.executor.class</code></td>
- <td>classname; default is org. apache. tools. ant. helper. DefaultExecutor</td>
+ <td>classname; default is <q>org.<wbr>apache.<wbr>tools.<wbr>ant.<wbr>helper.<wbr>DefaultExecutor</q></td>
<td><em>Since Ant 1.6.3</em> Ant will delegate Target invocation to the
-org.apache.tools.ant.Executor implementation specified here.
+ <code>org.apache.tools.ant.Executor</code> implementation specified here.
</td>
</tr>
<tr>
<td><code>ant.file</code></td>
<td>read only: full filename of the build file</td>
- <td>This is set to the name of the build file. In
- <a href="Tasks/import.html">
- <import>-ed</a> files, this is set to the containing build file.
+ <td>This is set to the name of the build
+ file. In <a href="Tasks/import.html"><import>-ed</a> files,
+ this is set to the containing build file.
</td>
</tr>
<tr>
<td><code>ant.file.*</code></td>
<td>read only: full filename of the build file of Ant projects
</td>
- <td>This is set to the name of a file by project;
- this lets you determine the location of <a href="Tasks/import.html">
- <import>-ed</a> files,
+ <td>This is set to the name of a file by project; this lets you
+ determine the location
+ of <a href="Tasks/import.html"><import>-ed</a> files,
</td>
</tr>
<tr>
<td><code>ant.input.properties</code></td>
<td>filename (required)</td>
- <td>Name of the file holding the values for the
- <a href="inputhandler.html">PropertyFileInputHandler</a>.
+ <td>Name of the file holding the values for
+ the <a href="inputhandler.html">PropertyFileInputHandler</a>.
</td>
</tr>
<tr>
<td><code>ant.logger.defaults</code></td>
- <!-- add the blank after the slash, so the browser can do a line break -->
- <td>filename (optional, default '/org/ apache/ tools/ ant/ listener/ defaults.properties')</td>
- <td>Name of the file holding the color mappings for the
- <a href="listeners.html#AnsiColorLogger">AnsiColorLogger</a>.
+ <td>filename (optional, default <q>/org/<wbr>apache/<wbr>tools/<wbr>ant/<wbr>listener/<wbr>defaults.properties</q>)</td>
+ <td>Name of the file holding the color mappings for
+ the <a href="listeners.html#AnsiColorLogger">AnsiColorLogger</a>.
</td>
</tr>
<tr>
@@ -319,157 +316,160 @@ org.apache.tools.ant.Executor implementation specified here.
</tr>
<tr>
<td><code>ant.PropertyHelper</code></td>
- <td>ant-reference-name (optional)</td>
- <td>Specify the PropertyHelper to use. The object must be of the type
- org.apache.tools.ant.PropertyHelper. If not defined an object of
- org.apache.tools.ant.PropertyHelper will be used as PropertyHelper.
+ <td>Ant reference name (optional)</td>
+ <td>Specify the PropertyHelper to use. The object must be of the
+ type <code>org.apache.tools.ant.PropertyHelper</code>. By default,
+ an object of <code>org.apache.tools.ant.PropertyHelper</code> will
+ be used as PropertyHelper.
</td>
</tr>
<tr>
<td><code>ant.regexp.regexpimpl</code></td>
<td>classname</td>
- <td>classname for a RegExp implementation; if not set Ant uses JDK 1.4's implementation;
- <a href="Types/mapper.html#regexp-mapper">RegExp-Mapper</a>
- "Choice of regular expression implementation"
+ <td>classname for a RegExp implementation; by default, JDK 1.4+
+ implementation; <a href="Types/mapper.html#regexp-mapper">RegExp
+ Mapper</a> "Choice of regular expression implementation".
</td>
</tr>
<tr>
<td><code>ant.reuse.loader</code></td>
<td>boolean</td>
- <td>allow to reuse classloaders
- used in org.apache.tools.ant.util.ClasspathUtil
+ <td>allow to reuse classloaders used
+ in <code>org.apache.tools.ant.util.ClasspathUtil</code>.
</td>
</tr>
<tr>
<td><code>ant.XmlLogger.stylesheet.uri</code></td>
- <td>filename (default 'log.xsl')</td>
- <td>Name for the stylesheet to include in the logfile by
- <a href="listeners.html#XmlLogger">XmlLogger</a>.
+ <td>filename (default <q>log.xsl</q>)</td>
+ <td>Name for the stylesheet to include in the logfile
+ by <a href="listeners.html#XmlLogger">XmlLogger</a>.
</td>
</tr>
<tr>
<td><code>build.compiler</code></td>
<td>name</td>
- <td>Specify the default compiler to use.
- see <a href="Tasks/javac.html">javac</a>,
- <a href="Tasks/ejb.html#ejbjar_weblogic">EJB Tasks</a>
- (compiler attribute),
- <a href="Tasks/javah.html">javah</a>
+ <td>Specify the default compiler to use;
+ see <a href="Tasks/javac.html">javac</a>, <a href="Tasks/ejb.html#ejbjar_weblogic">EJB
+ Tasks</a> (<var>compiler</var>
+ attribute), <a href="Tasks/javah.html">javah</a>.
</td>
</tr>
<tr>
<td><code>build.compiler.emacs</code></td>
- <td>boolean (default false)</td>
- <td>Enable emacs-compatible error messages.
- see <a href="Tasks/javac.html">javac</a> "Jikes Notes"
+ <td>boolean (default <q>false</q>)</td>
+ <td>Enable emacs-compatible error messages;
+ see <a href="Tasks/javac.html">javac</a> "Jikes Notes".
</td>
</tr>
<tr>
<td><code>build.compiler.fulldepend</code></td>
<td>boolean (default false)</td>
- <td>Enable full dependency checking
- see <a href="Tasks/javac.html">javac</a> "Jikes Notes"
+ <td>Enable full dependency checking;
+ see <a href="Tasks/javac.html">javac</a> "Jikes Notes".
</td>
</tr>
<tr>
<td><code>build.compiler.jvc.extensions</code></td>
- <td>boolean (default true)</td>
- <td>enable Microsoft extensions of their java compiler
- see <a href="Tasks/javac.html">javac</a> "Jvc Notes"
+ <td><em><u>Deprecated</u></em></td>
+ <td>Enable Microsoft extensions of their Java compiler;
+ see <a href="Tasks/javac.html">javac</a> "Jvc Notes".
</td>
</tr>
<tr>
<td><code>build.compiler.pedantic</code></td>
- <td>boolean (default false)</td>
- <td>Enable pedantic warnings.
- see <a href="Tasks/javac.html">javac</a> "Jikes Notes"
+ <td>boolean (default <q>false</q>)</td>
+ <td>Enable pedantic warnings;
+ see <a href="Tasks/javac.html">javac</a> "Jikes Notes".
</td>
</tr>
<tr>
<td><code>build.compiler.warnings</code></td>
- <td>Deprecated flag</td>
- <td> see <a href="Tasks/javac.html">javac</a> "Jikes Notes" </td>
+ <td><em><u>Deprecated</u></em></td>
+ <td>See <a href="Tasks/javac.html">javac</a> "Jikes Notes"</td>
</tr>
<tr>
<td><code>build.rmic</code></td>
<td>name</td>
- <td>control the <a href="Tasks/rmic.html">rmic</a> compiler </td>
+ <td>Control the <a href="Tasks/rmic.html">rmic</a> compiler</td>
</tr>
<tr>
<td><code>build.sysclasspath</code></td>
- <td>see <a href="sysclasspath.html">its dedicated page</a>, no
- default value</td>
- <td>see <a href="sysclasspath.html">its dedicated page</a></td>
+ <td>No default value</td>
+ <td>See <a href="sysclasspath.html">its dedicated page</a></td>
</tr>
<tr>
<td><code>file.encoding</code></td>
<td>name of a supported character set (e.g. UTF-8, ISO-8859-1, US-ASCII)</td>
- <td>use as default character set of email messages; use as default for source-, dest- and bundleencoding
- in <a href="Tasks/translate.html">translate</a> <br>
- 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>
- for more information about character sets (not used in Ant, but has nice docs).
+ <td>use as default character set of email messages; use as default
+ for <var>srcencoding</var>, <var>destencoding</var>
+ and <var>bundleencoding</var>
+ in <a href="Tasks/translate.html">translate</a><br/> see JavaDoc
+ of <a target="_blank"
+ href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">java.nio.charset.Charset</a>
+ for more information about character sets (not used in Ant, but
+ has nice docs).
</td>
</tr>
<tr>
<td><code>jikes.class.path</code></td>
<td>path</td>
- <td>The specified path is added to the classpath if jikes is used as compiler.</td>
+ <td>The specified path is added to the classpath if Jikes is used as compiler.</td>
</tr>
<tr>
<td><code>MailLogger.properties.file, MailLogger.*</code></td>
<td>filename (optional, defaults derived from Project instance)</td>
- <td>Name of the file holding properties for sending emails by the
- <a href="listeners.html#MailLogger">MailLogger</a>. Override properties set
- inside the buildfile or via command line.
+ <td>Name of the file holding properties for sending emails by
+ the <a href="listeners.html#MailLogger">MailLogger</a>. Override
+ properties set inside the buildfile or via command line.
</td>
</tr>
<tr>
<td><code>org.apache.tools.ant.ProjectHelper</code></td>
- <!-- add the blank after the slash, so the browser can do a line break -->
- <td>classname (optional, default 'org.apache.tools.ant.ProjectHelper2')</td>
- <td>specifies the classname to use as ProjectHelper. The class must extend
- org.apache.tools.ant.ProjectHelper.
+ <td>classname (optional, default <q>org.<wbr>apache.<wbr>tools.<wbr>ant.<wbr>ProjectHelper2</q>)</td>
+ <td>specifies the classname to use as ProjectHelper. The class must
+ extend <code>org.apache.tools.ant.ProjectHelper</code>.
</td>
</tr>
<tr>
<td><code>org.apache.tools.ant.ArgumentProcessor</code></td>
<td>classname (optional)</td>
- <td>specifies the classname to use as ArgumentProcessor. The class must extend
- org.apache.tools.ant.ArgumentProcessor.
+ <td>specifies the classname to use as ArgumentProcessor. The class
+ must extend <code>org.apache.tools.ant.ArgumentProcessor</code>.
</td>
</tr>
-
<tr>
<td><code>websphere.home</code></td>
<td>path</td>
- <td>Points to home directory of websphere.
- see <a href="Tasks/ejb.html#ejbjar_websphere">EJB Tasks</a>
+ <td>Points to home directory of WebSphere;
+ see <a href="Tasks/ejb.html#ejbjar_websphere">EJB Tasks</a>
</td>
</tr>
<tr>
<td><code>XmlLogger.file</code></td>
- <td>filename (default 'log.xml')</td>
+ <td>filename (default <q>log.xml</q>)</td>
<td>Name for the logfile for <a href="listeners.html#MailLogger">MailLogger</a>.
</td>
</tr>
<tr>
<td><code>ant.project-helper-repo.debug</code></td>
- <td>boolean (default 'false')</td>
- <td>Set it to true to enable debugging with Ant's
- <a href="projecthelper.html#repository">ProjectHelper internal repository</a>.
+ <td>boolean (default <q>false</q>)</td>
+ <td>Set it to <q>true</q> to enable debugging with
+ Ant's <a href="projecthelper.html#repository">ProjectHelper internal
+ repository</a>.
</td>
</tr>
<tr>
<td><code>ant.argument-processor-repo.debug</code></td>
- <td>boolean (default 'false')</td>
- <td>Set it to true to enable debugging with Ant's
- <a href="argumentprocessor.html#repository">ArgumentProcessor internal repository</a>.
+ <td>boolean (default <q>false</q>)</td>
+ <td>Set it to <q>true</q> to enable debugging with
+ Ant's <a href="argumentprocessor.html#repository">ArgumentProcessor
+ internal repository</a>.
</td>
</tr>
<tr>
<td><code>ant.tstamp.now</code></td>
<td>number, seconds since the epoch (midnight 1970-01-01)</td>
- <td>The value to use as current time and date for <tstamp></td>
+ <td rowspan="2">The value to use as current time and date for <tstamp></td>
</tr>
<tr>
<td><code>ant.tstamp.now.iso</code></td>
@@ -478,38 +478,48 @@ org.apache.tools.ant.Executor implementation specified here.
</table>
<p>
-If new properties get added (it happens), expect them to appear under the
-"ant." and "org.apache.tools.ant" prefixes, unless the developers have a
-very good reason to use another prefix. Accordingly, please avoid using
-properties that begin with these prefixes. This protects you from future
-Ant releases breaking your build file.
+If new properties get added (it happens), expect them to appear under
+the <code>ant.</code> and <code>org.apache.tools.ant.</code> prefixes,
+unless the developers have a very good reason to use another
+prefix. Accordingly, please avoid using properties that begin with
+these prefixes. This protects you from future Ant releases breaking
+your build file.
</p>
<h3>return code</h3>
-<p>the ant start up scripts (in their Windows and Unix version) return
-the return code of the java program. So a successful build returns 0,
-failed builds return other values.
+<p>
+Ant start up scripts (in their Windows and Unix version) return the
+return code of the <code>java</code> program. So a successful build
+returns 0, failed builds return other values.
</p>
<h2 id="cygwin">Cygwin Users</h2>
-<p>The Unix launch script that come with Ant works correctly with Cygwin. You
-should not have any problems launching Ant from the Cygwin shell. It is
-important to note, however, that once Ant is running it is part of the JDK
-which operates as a native Windows application. The JDK is not a Cygwin
-executable, and it therefore has no knowledge of Cygwin paths, etc. In
-particular when using the <code><exec></code> task, executable names such
-as "/bin/sh" will not work, even though these work from the Cygwin
-shell from which Ant was launched. You can use an executable name such as
-"sh" and rely on that command being available in the Windows path.
+<p>
+Unix launch script that come with Ant works correctly with Cygwin. You
+should not have any problems launching Ant from the Cygwin shell. It
+is important to note, however, that once Ant is running it is part of
+the JDK which operates as a native Windows application. The JDK is not
+a Cygwin executable, and it therefore has no knowledge of Cygwin
+paths, etc. In particular when using the <code><exec></code>
+task, executable names such as <q>/bin/sh</q> will not work, even
+though these work from the Cygwin shell from which Ant was
+launched. You can use an executable name such as <q>sh</q> and rely on
+that command being available in the Windows path.
</p>
<h2 id="os2">OS/2 Users</h2>
-<p>The OS/2 launch script was developed to perform complex tasks. It has two parts:
-<code>ant.cmd</code> which calls Ant and <code>antenv.cmd</code> which sets the environment for Ant.
-Most often you will just call <code>ant.cmd</code> using the same command line options as described
-above. The behaviour can be modified by a number of ways explained below.</p>
+<p>
+The OS/2 launch script was developed to perform complex tasks. It has
+two parts: <code>ant.cmd</code> which calls Ant
+and <code>antenv.cmd</code> which sets the environment for Ant. Most
+often you will just call <code>ant.cmd</code> using the same command
+line options as described above. The behaviour can be modified by a
+number of ways explained below.
+</p>
-<p>Script <code>ant.cmd</code> first verifies whether the Ant environment is set correctly. The
-requirements are:</p>
+<p>
+Script <code>ant.cmd</code> first verifies whether the Ant environment
+is set correctly. The requirements are:
+</p>
<ol>
<li>Environment variable <code>JAVA_HOME</code> is set.</li>
<li>Environment variable <code>ANT_HOME</code> is set.</li>
@@ -517,77 +527,94 @@ requirements are:</p>
<code>JAVA_HOME</code> and at least one element from <code>ANT_HOME</code>.</li>
</ol>
-<p>If any of these conditions is violated, script <code>antenv.cmd</code> is called. This script
-first invokes configuration scripts if there exist: the system-wide configuration
-<code>antconf.cmd</code> from the <code>%ETC%</code> directory and then the user configuration
-<code>antrc.cmd</code> from the <code>%HOME%</code> directory. At this moment both
-<code>JAVA_HOME</code> and <code>ANT_HOME</code> must be defined because <code>antenv.cmd</code>
-now adds <code>classes.zip</code> or <code>tools.jar</code> (depending on version of JVM) and
-everything from <code>%ANT_HOME%\lib</code> except <code>ant-*.jar</code> to
-<code>CLASSPATH</code>. Finally <code>ant.cmd</code> calls per-directory configuration
-<code>antrc.cmd</code>. All settings made by <code>ant.cmd</code> are local and are undone when the
-script ends. The settings made by <code>antenv.cmd</code> are persistent during the lifetime of the
-shell (of course unless called automatically from <code>ant.cmd</code>). It is thus possible to call
-<code>antenv.cmd</code> manually and modify some settings before calling <code>ant.cmd</code>.</p>
-
-<p>Scripts <code>envset.cmd</code> and <code>runrc.cmd</code> perform auxiliary tasks. All scripts
-have some documentation inside.</p>
-
-<h2 id="background">Running Ant as a background process on
- Unix(-like) systems</h2>
-
-<p>If you start Ant as a background process (like in <code>ant
- &</code>) and the build process creates another process, Ant will
- immediately try to read from standard input, which in turn will
- most likely suspend the process. In order to avoid this, you must
- redirect Ant's standard input or explicitly provide input to each
- spawned process via the input related attributes of the
- corresponding tasks.</p>
-
-<p>Tasks that create such new processes
- include <code><exec></code>, <code><apply></code>
- or <code><java></code> when the <code>fork</code> attribute is
- <code>true</code>.</p>
+<p>
+If any of these conditions is violated, script <code>antenv.cmd</code>
+is called. This script first invokes configuration scripts if there
+exist: the system-wide configuration <code>antconf.cmd</code> from
+the <samp>%ETC%</samp> directory and then the user
+configuration <code>antrc.cmd</code> from the <samp>%HOME%</samp>
+directory. At this moment both <code>JAVA_HOME</code>
+and <code>ANT_HOME</code> must be defined
+because <code>antenv.cmd</code> now adds <samp>classes.zip</samp>
+or <samp>tools.jar</samp> (depending on version of JVM) and everything
+from <samp>%ANT_HOME%\lib</samp> except <samp>ant-*.jar</samp>
+to <code>CLASSPATH</code>. Finally <code>ant.cmd</code> calls
+per-directory configuration <code>antrc.cmd</code>. All settings made
+by <code>ant.cmd</code> are local and are undone when the script
+ends. The settings made by <code>antenv.cmd</code> are persistent
+during the lifetime of the shell (of course unless called
+automatically from <code>ant.cmd</code>). It is thus possible to
+call <code>antenv.cmd</code> manually and modify some settings before
+calling <code>ant.cmd</code>.
+</p>
+
+<p>
+Scripts <code>envset.cmd</code> and <code>runrc.cmd</code> perform
+auxiliary tasks. All scripts have some documentation inside.
+</p>
+
+<h2 id="background">Running Ant as a background process on Unix(-like) systems</h2>
+
+<p>
+If you start Ant as a background process (like in <code>ant
+&</code>) and the build process creates another process, Ant will
+immediately try to read from standard input, which in turn will most
+likely suspend the process. In order to avoid this, you must redirect
+Ant's standard input or explicitly provide input to each spawned
+process via the input related attributes of the corresponding tasks.
+</p>
+
+<p>
+Tasks that create such new processes
+include <code><exec></code>, <code><apply></code>
+or <code><java></code> when the <var>fork</var> attribute
+is <q>true</q>.
+</p>
<h2 id="viajava">Running Ant via Java</h2>
-<p>If you have installed Ant in the do-it-yourself way, Ant can be started
-from one of two entry points:</p>
+<p>
+If you have installed Ant in the do-it-yourself way, Ant can be
+started from one of two entry points:
+</p>
<pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
<pre>java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]</pre>
<p>
-The first method runs Ant's traditional entry point. The second method uses
-the Ant Launcher introduced in Ant 1.6. The former method does not support
-the -lib option and all required classes are loaded from the CLASSPATH. You must
-ensure that all required jars are available. At a minimum the CLASSPATH should
-include:
+The first method runs Ant's traditional entry point. The second method
+uses the Ant Launcher introduced in Ant 1.6. The former method does
+not support the <code>-lib</code> option and all required classes are
+loaded from the <code>CLASSPATH</code>. You must ensure that all
+required jars are available. At a minimum the <code>CLASSPATH</code>
+should include:
</p>
<ul>
-<li><code>ant.jar</code> and <code>ant-launcher.jar</code></li>
+<li><samp>ant.jar</samp> and <samp>ant-launcher.jar</samp></li>
<li>jars/classes for your XML parser</li>
<li>the JDK's required jar/zip files</li>
</ul>
<p>
-The latter method supports the -lib, -nouserlib, -noclasspath options and will
- load jars from the specified ANT_HOME. You should start the latter with the most minimal
-classpath possible, generally just the ant-launcher.jar.
+The latter method supports
+the <code>-lib</code>, <code>-nouserlib</code>, <code>-noclasspath</code>
+options and will load jars from the
+specified <code>ANT_HOME</code>. You should start the latter with the
+most minimal classpath possible, generally just
+the <samp>ant-launcher.jar</samp>.
</p>
<p id="viaant">
- Ant can be started in Ant via the <code><java></code> command.
- Here is an example:
+Ant can be started in Ant via the <code><java></code> command.
+Here is an example:
</p>
<pre>
-<java
- classname="org.apache.tools.ant.launch.Launcher"
- fork="true"
- failonerror="true"
- dir="${sub.builddir}"
- timeout="4000000"
- taskname="startAnt">
+<java classname="org.apache.tools.ant.launch.Launcher"
+ fork="true"
+ failonerror="true"
+ dir="${sub.builddir}"
+ timeout="4000000"
+ taskname="startAnt">
<classpath>
<pathelement location="${ant.home}/lib/ant-launcher.jar"/>
</classpath>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/runninglist.html
----------------------------------------------------------------------
diff --git a/manual/runninglist.html b/manual/runninglist.html
index e2b8010..d0bfaf2 100644
--- a/manual/runninglist.html
+++ b/manual/runninglist.html
@@ -29,18 +29,16 @@
<h3>Running Apache Ant</h3>
<ul class="inlinelist">
-<li><a href="running.html#commandline">Command Line</a></li>
-<div style="padding-left:1em">
- <li><a href="running.html#options">Options</a></li>
- <li><a href="running.html#libs">Library Directories</a></li>
- <li><a href="running.html#files">Files</a></li>
- <li><a href="running.html#envvars">Environment Variables</a></li>
- <li><a href="running.html#sysprops">Java System Properties</a></li>
- <li><a href="running.html#cygwin">Cygwin Users</a></li>
- <li><a href="running.html#os2">OS/2 Users</a></li>
- <li><a href="running.html#background">Running "in the background"</a></li>
-</div>
-<li><a href="running.html#viajava">Running Ant via Java</a></li>
+ <li><a href="running.html#commandline">Command Line</a></li>
+ <li class="indent"><a href="running.html#options">Options</a></li>
+ <li class="indent"><a href="running.html#libs">Library Directories</a></li>
+ <li class="indent"><a href="running.html#files">Files</a></li>
+ <li class="indent"><a href="running.html#envvars">Environment Variables</a></li>
+ <li class="indent"><a href="running.html#sysprops">Java System Properties</a></li>
+ <li class="indent"><a href="running.html#cygwin">Cygwin Users</a></li>
+ <li class="indent"><a href="running.html#os2">OS/2 Users</a></li>
+ <li class="indent"><a href="running.html#background">Running "in the background"</a></li>
+ <li><a href="running.html#viajava">Running Ant via Java</a></li>
</ul>
</body>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/stylesheets/style.css
----------------------------------------------------------------------
diff --git a/manual/stylesheets/style.css b/manual/stylesheets/style.css
index 0b474ac..187953a 100644
--- a/manual/stylesheets/style.css
+++ b/manual/stylesheets/style.css
@@ -15,6 +15,10 @@
* limitations under the License.
*
*/
+body {
+ font-family: “Palatino Linotype”, Palatino, Georgia, “Century Schoolbook”, serif;
+}
+
h2 {
font-size: 200%;
background-color: white;
@@ -52,51 +56,119 @@ h5 + p, h6 + p {
margin-bottom: .5rem;
}
-h1 > a, h2 > a, h3 > a, h4 > a, h5 > a, h6 > a {
+h3 > a, h4 > a, h5 > a, h6 > a {
color: white;
}
-h1 > a:visited, h2 > a:visited, h3 > a:visited, h4 > a:visited, h5 > a:visited, h6 > a:visited,
-h1 > a:hover, h2 > a:hover, h3 > a:hover, h4 > a:hover, h5 > a:hover, h6 > a:hover {
+h3 > a:visited, h4 > a:visited, h5 > a:visited, h6 > a:visited,
+h3 > a:hover, h4 > a:hover, h5 > a:hover, h6 > a:hover {
color: lightskyblue;
}
-td {
- background-color: #eeeeee;
- color: black;
+var {
+ font-family: Verdana, Geneva, sans-serif;
+ font-size: 0.8rem;
}
-/* first row */
-table tr:first-child td {
- background-color: silver;
- color: black;
+q {
+ font-family: "Lucida Console", Monaco, monospace;
+ font-size: 0.8rem;
}
-/* or th as first row */
-table th {
- background-color: silver;
- color: black;
+q.no-break {
+ white-space: nowrap;
+ hyphens: none;
}
-code {
+code, samp {
white-space: nowrap;
+ hyphens: none;
+ font-size: 1.125rem;
+}
+
+h2 > code, h2 > samp {
+ font-size: 2rem;
+}
+
+h3 > code, h3 > samp {
+ font-size: 1.5rem;
}
pre {
background-color: #efefef;
margin-right: 4rem;
margin-left: 4rem;
+ font-size: 1.125rem;
+}
+
+pre var, code var {
+ font-size: 0.65rem;
}
/* code snippets in examples and tutorials */
-.code {
+.code {
background: #efefef;
}
/* highlight console output */
-.output {
+.output {
color: white;
- background: #837A67;
+ background: #837A67;
+}
+
+td {
+ vertical-align: top;
+ background-color: #eeeeee;
+ color: black;
+}
+
+th {
+ background-color: silver;
+ color: black;
+ vertical-align: middle;
+}
+
+td pre {
+ margin: 0 0 0 0;
+ font-size: 1rem;
+}
+
+thead.no-bold th {
+ font-weight: normal;
+ white-space: nowrap;
+}
+
+table.attr {
+ width: 100%;
+}
+
+table.attr td:first-child {
+ font-family: Verdana, Geneva, sans-serif;
+ font-size: 0.8rem;
+ font-style: italic;
+}
+
+table.attr td:last-child {
+ text-align: center;
+}
+
+table.attr td.center, h1.center, p.center {
+ text-align: center;
+}
+
+table.attr td.left {
+ font-family: “Palatino Linotype”, Palatino, Georgia, “Century Schoolbook”, serif;
+ font-size: 1rem;
+ font-style: normal;
+ text-align: left;
+}
+
+table.attr td.var {
+ text-align: left;
+}
+
+td[rowspan] {
+ vertical-align: middle;
}
ul.inlinelist {
@@ -105,6 +177,10 @@ ul.inlinelist {
padding: 0;
}
+li.indent {
+ padding-left: 1rem;
+}
+
div.float {
margin-top: 0.5rem;
width: 100%;
@@ -130,7 +206,7 @@ div.float + table tr:first-child {
span.left {
float: left;
- font-family: Arial, Helvetica, sans-serif;
+ font-family: Verdana, Geneva, sans-serif;
font-weight: bold;
}
@@ -153,7 +229,7 @@ ol.refs > li {
}
ol.refs > li:before {
- content: "[" counter(refs, decimal) "] ";
+ content: "[" counter(refs, decimal) "]";
counter-increment: refs;
position: absolute;
left: -2rem;
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/sysclasspath.html
----------------------------------------------------------------------
diff --git a/manual/sysclasspath.html b/manual/sysclasspath.html
index 3c50d26..4ad6a12 100644
--- a/manual/sysclasspath.html
+++ b/manual/sysclasspath.html
@@ -25,7 +25,7 @@
<body>
<h2 id="sysclasspath">build.sysclasspath</h2>
-<p>The value of the build.sysclasspath property
+<p>The value of the <code>build.sysclasspath</code> property
controls how the system classpath, i.e. the classpath in effect when
Apache Ant is run, affects the behavior of classpaths in Ant.
The default behavior varies from task to task.</p>
@@ -35,7 +35,7 @@ The values and their meanings are:
<table>
<tr><th>value</th><th>meaning</th></tr>
<tr>
-<td align="left" valign="top">only</td>
+<td>only</td>
<td>Only the system classpath is used and classpaths specified in build files,
etc are ignored. This situation could be considered as the person running
the build file knows more about the environment than the person writing the
@@ -44,7 +44,7 @@ build file.
</tr>
<tr>
-<td align="left" valign="top">ignore</td>
+<td>ignore</td>
<td>
The system classpath is ignored. This situation is the reverse of the
above. The person running the build trusts the build file writer to get the
@@ -53,7 +53,7 @@ build file right. This mode is recommended for portable scripts.
</tr>
<tr>
-<td align="left" valign="top">last</td>
+<td>last</td>
<td>
The classpath is concatenated to any specified classpaths at the end. This
is a compromise, where the build file writer has priority.
@@ -61,7 +61,7 @@ is a compromise, where the build file writer has priority.
</tr>
<tr>
-<td align="left" valign="top">first</td>
+<td>first</td>
<td>
Any specified classpaths are concatenated to the system classpath. This is
the other form of compromise where the build runner has priority.
@@ -70,9 +70,9 @@ the other form of compromise where the build runner has priority.
</table>
<p><em>Since Ant 1.7</em> the value of this property also affects the
-bootclasspath settings--it combines the bootclasspath that has been
-specified for a task with the bootclasspath of the Java VM running
-Ant. If the property has not been set, it defaults to "ignore" in
+bootclasspath settings—it combines the bootclasspath that has been
+specified for a task with the bootclasspath of the JVM running
+Ant. If the property has not been set, it defaults to <q>ignore</q> in
this case.</p>
</body>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/targets.html
----------------------------------------------------------------------
diff --git a/manual/targets.html b/manual/targets.html
index 4c1c891..cf38a07 100644
--- a/manual/targets.html
+++ b/manual/targets.html
@@ -33,9 +33,9 @@
example you might have a target for compiling and a
target for creating a distributable. You can only build a
distributable when you have compiled first, so the distribute
- target <i>depends on</i> the compile target.</p>
+ target <em>depends on</em> the compile target.</p>
- <p>Ant tries to execute the targets in the <code>depends</code>
+ <p>Ant tries to execute the targets in the <var>depends</var>
attribute in the order they appear (from left to right). Keep in
mind that it is possible that a target can get executed earlier
when an earlier target depends on it:</p>
@@ -46,12 +46,12 @@
<target name="D" depends="C,B,A"/></pre>
<p>Suppose we want to execute target D. From its
- <code>depends</code> attribute, you might think that first target
+ <var>depends</var> attribute, you might think that first target
C, then B and then A is executed. Wrong! C depends on B, and B
depends on A, so first A is executed, then B, then C, and finally
D.</p>
- <pre><b>Call-Graph:</b> A --> B --> C --> D</pre>
+ <pre><b>Call-Graph:</b> A → B → C → D</pre>
<p>In a chain of dependencies stretching back from a given target
such as D above, each target gets executed only once, even when
@@ -59,7 +59,7 @@
will first result in C being called, which in turn will first call
B, which in turn will first call A. After A, then B, then C have
executed, execution returns to the dependency list of D, which
- will <u>not</u> call B and A, since they were already called in
+ will <strong>not</strong> call B and A, since they were already called in
process of dependency resolution for C and B respectively as
dependencies of D. Had no such dependencies been discovered in
processing C and B, B and A would have been executed after C in
@@ -68,9 +68,9 @@
<p>A target also has the ability to perform its execution if (or
unless) a property has been set. This allows, for example, better
control on the building process depending on the state of the
- system (java version, OS, command-line property defines, etc.).
- To make a target <i>sense</i> this property, you should add
- the <code>if</code> (or <code>unless</code>) attribute with the
+ system (Java version, OS, command-line property defines, etc.).
+ To make a target <em>sense</em> this property, you should add
+ the <var>if</var> (or <var>unless</var>) attribute with the
name of the property that the target should react
to. <strong>Note:</strong> In the most simple case Ant will only
check whether the property has been set, the value doesn't matter,
@@ -83,14 +83,15 @@
<pre><target name="build-own-fake-module-A" unless="module-A-present"/></pre>
<p>In the first example, if the <code>module-A-present</code>
- property is set (to any value, e.g. <i>false</i>), the target will
+ property is set (to any value, e.g. <q>false</q>), the target will
be run. In the second example, if
the <code>module-A-present</code> property is set (again, to any
value), the target will not be run.</p>
- <p>Only one propertyname can be specified in the if/unless
- clause. If you want to check multiple conditions, you can use a
- dependent target for computing the result for the check:</p>
+ <p>Only one property name can be specified in
+ the <var>if</var>/<var>unless</var> attribute. If you want to
+ check multiple conditions, you can use a dependent target for
+ computing the result for the check:</p>
<pre>
<target name="myTarget" depends="myTarget.check" if="myTarget.run">
@@ -104,22 +105,21 @@
<available file="bar.txt"/>
</and>
</condition>
-</target>
-</pre>
+</target></pre>
- <pre><b>Call-Graph:</b> myTarget.check --> maybe(myTarget)</pre>
+ <pre><b>Call-Graph:</b> myTarget.check → maybe(myTarget)</pre>
- <p>If no <code>if</code> and no <code>unless</code> attribute is
+ <p>If no <var>if</var> and no <var>unless</var> attribute is
present, the target will always be executed.</p>
- <p><b>Important</b>: the <code>if</code> and <code>unless</code>
+ <p><strong>Important</strong>: the <var>if</var> and <var>unless</var>
attributes only enable or disable the target to which they are
attached. They do not control whether or not targets that a
conditional target depends upon get executed. In fact, they do
not even get evaluated until the target is about to be executed,
and all its predecessors have already run.
- <p>The optional <code>description</code> attribute can be used to
+ <p>The optional <var>description</var> attribute can be used to
provide a one-line description of this target, which is printed by
the <code>-projecthelp</code> command-line option. Targets without
such a description are deemed internal and will not be listed,
@@ -128,134 +128,136 @@
<p>It is a good practice to place
your <a href="Tasks/tstamp.html">tstamp</a> tasks in a
- so-called <i>initialization</i> target, on which all other targets
+ so-called <em>initialization</em> target, on which all other targets
depend. Make sure that target is always the first one in the
depends list of the other targets. In this manual, most
initialization targets have the name <code>"init"</code>.</p>
<pre>
- <project>
- <target name="init">
- <tstamp/>
- </target>
- <target name="otherTarget" depends="init">
- ...
- </target>
- </project>
- </pre>
+<project>
+ <target name="init">
+ <tstamp/>
+ </target>
+ <target name="otherTarget" depends="init">
+ ...
+ </target>
+</project></pre>
<p>Especially if you only have a few tasks you also could place these
- tasks directly under the project tag (since Ant 1.6.0):</p>
- <pre>
- <project>
- <tstamp/>
- </project>
- </pre>
+ tasks directly under the project tag (<em>since Ant 1.6.0</em>):</p>
+ <pre>
+<project>
+ <tstamp/>
+</project></pre>
- <p>If the depends attribute and the if/unless attribute are set, the
- depends attribute is executed first.</p>
+ <p>If the <var>depends</var> attribute and
+ the <var>if</var>/<var>unless</var> attribute are set,
+ the <var>depends</var> attribute is executed first.</p>
<p>A target has the following attributes:</p>
- <table>
+ <table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required</th>
</tr>
<tr>
- <td valign="top">name</td>
- <td valign="top">the name of the target.</td>
- <td align="center" valign="top">Yes</td>
+ <td>name</td>
+ <td>the name of the target.</td>
+ <td>Yes</td>
</tr>
<tr>
- <td valign="top">depends</td>
- <td valign="top">a comma-separated list of names of targets on
+ <td>depends</td>
+ <td>a comma-separated list of names of targets on
which this target depends.</td>
- <td align="center" valign="top">No</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">if</td>
- <td valign="top">the name of the property that must be set in
+ <td>if</td>
+ <td>the name of the property that must be set in
order for this target to execute,
or <a href="properties.html#if+unless">something evaluating to
- true</a>.</td>
- <td align="center" valign="top">No</td>
+ <q>true</q></a>.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">unless</td>
- <td valign="top">the name of the property that must not be set
+ <td>unless</td>
+ <td>the name of the property that must not be set
in order for this target to execute,
or <a href="properties.html#if+unless">something evaluating to
- false</a>.</td>
- <td align="center" valign="top">No</td>
+ <q>false</q></a>.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">description</td>
- <td valign="top">a short description of this target's function.</td>
- <td align="center" valign="top">No</td>
+ <td>description</td>
+ <td>a short description of this target's function.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">extensionOf</td>
- <td valign="top">Adds the current target to the depends list of
+ <td>extensionOf</td>
+ <td>Adds the current target to the depends list of
the named <a href="#extension-points">extension-point</a>.
- <em>since Ant 1.8.0.</em></td>
- <td align="center" valign="top">No</td>
+ <em>since Ant 1.8.0</em>.</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">onMissingExtensionPoint</td>
- <td valign="top">What to do if this target tries to extend a
+ <td>onMissingExtensionPoint</td>
+ <td>What to do if this target tries to extend a
missing
- <a href="#extension-points">extension-point</a>. ("fail",
- "warn", "ignore").
- <em>since Ant 1.8.2.</em></td>
- <td align="center" valign="top">No. Not allowed unless
- <code>extensionOf</code> is present. Defaults to <code>fail</code>.
+ <a href="#extension-points">extension-point</a>. (<q>fail</q>,
+ <q>warn</q>, <q>ignore</q>).
+ <em>since Ant 1.8.2</em>.</td>
+ <td>No; not allowed unless
+ <var>extensionOf</var> is present, defaults to <q>fail</q>.
</td>
</tr>
</table>
<p>A target name can be any alphanumeric string valid in the
- encoding of the XML file. The empty string "" is in this
- set, as is comma "," and space " ". Please
- avoid using these, as they will not be supported in future Ant
- versions because of all the confusion they cause on command line and IDE. IDE support of
- unusual target names, or any target name containing spaces, varies
- with the IDE.</p>
-
- <p>Targets beginning with a hyphen such
- as <code>"-restart"</code> are valid, and can be used to
- name targets that should not be called directly from the command
- line. <br>
- For Ants main class every option starting with hyphen is an
- option for Ant itself and not a target. For that reason calling these
- target from command line is not possible. On the other hand IDEs usually
- don't use Ants main class as entry point and calling them from the IDE
- is usually possible.</p>
+ encoding of the XML file. The empty string <q></q> is in this set,
+ as is comma <q>,</q> and space <q> </q>. Please avoid using
+ these, as they will not be supported in future Ant versions
+ because of all the confusion they cause on command line and
+ IDE. IDE support of unusual target names, or any target name
+ containing spaces, varies with the IDE.</p>
+
+ <p>Targets beginning with a hyphen such as <q>-restart</q> are
+ valid, and can be used to name targets that should not be called
+ directly from the command line.<br/>
+ For Ant's main class every option starting with hyphen is an
+ option for Ant itself and not a target. For that reason calling
+ these targets from command line is not possible. On the other
+ hand, IDEs usually don't use Ant's main class as entry point and
+ calling them from the IDE is usually possible.</p>
<h1 id="extension-points">Extension-Points</h1>
- <p><em>since Ant 1.8.0.</em></p>
+ <p><em>since Ant 1.8.0</em>.</p>
- <p>Extension-Points are similar to targets in that they have a name and
- a depends list and can be executed from the command line. Just
- like targets they represent a state during the build process.</p>
+ <p>Extension-Points are similar to targets in that they have a name
+ and a <var>depends</var> list and can be executed from the command
+ line. Just like targets they represent a state during the build
+ process.</p>
<p>Unlike targets they don't contain any tasks, their main purpose
is to collect targets that contribute to the desired state in
their depends list.</p>
- <p>Targets can add themselves to an extension-point's depends list via
- their extensionOf attribute. The targets that add themselves will be
- added after the targets of the explicit depends attribute of the
- extension-point, if multiple targets add themselves, their relative
- order is not defined.</p>
+ <p>Targets can add themselves to an
+ extension-point's <var>depends</var> list via
+ their <var>extensionOf</var> attribute. The targets that add
+ themselves will be added after the targets of the
+ explicit <var>depends</var> attribute of the extension-point, if
+ multiple targets add themselves, their relative order is not
+ defined.</p>
<p>The main purpose of an extension-point is to act as an extension
point for build files designed to
be <a href="Tasks/import.html">imported</a>. In the imported
file, an extension-point defines a state that must be reached and
- targets from other build files can join the depends list of said
- extension-point in order to contribute to that state.</p>
+ targets from other build files can join the <var>depends</var>
+ list of said extension-point in order to contribute to that
+ state.</p>
<p>For example your imported build file may need to compile code, it
might look like:</p>
@@ -267,10 +269,9 @@
depends="create-directory-layout"/>
<target name="compile" depends="ready-to-compile">
...
-</target>
-</pre>
+</target></pre>
- <pre><b>Call-Graph:</b> create-directory-layout --> 'empty slot' --> compile</pre>
+ <pre><b>Call-Graph:</b> create-directory-layout → 'empty slot' → compile</pre>
<p>And you need to generate some source before compilation, then in
your main build file you may use something like</p>
@@ -278,17 +279,16 @@
<target name="generate-sources"
extensionOf="ready-to-compile">
...
-</target>
-</pre>
+</target></pre>
- <pre><b>Call-Graph:</b> create-directory-layout --> generate-sources --> compile</pre>
+ <pre><b>Call-Graph:</b> create-directory-layout → generate-sources → compile</pre>
- <p>This will ensure that the <em>generate-sources</em> target is
- executed before the <em>compile</em> target.</p>
+ <p>This will ensure that the <q>generate-sources</q> target is
+ executed before the <q>compile</q> target.</p>
<p>Don't rely on the order of the depends list,
- if <em>generate-sources</em> depends
- on <em>create-directory-layout</em> then it must explicitly depend
+ if <q>generate-sources</q> depends
+ on <q>create-directory-layout</q> then it must explicitly depend
on it via its own depends attribute.</p>
</body>
</html>