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:24 UTC
[09/47] ant git commit: Use HTML 5(-ish), fix links
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/listeners.html
----------------------------------------------------------------------
diff --git a/manual/listeners.html b/manual/listeners.html
index 222ad68..e82312a 100644
--- a/manual/listeners.html
+++ b/manual/listeners.html
@@ -57,7 +57,7 @@ listeners and loggers.</p>
<ul>
<li>Receives a handle to the standard output and error print streams and
therefore can log information to the console or the <code>-logfile</code> specified file.</li>
- <li>Logging level (-quiet, -verbose, -debug) aware</li>
+ <li>Logging level (<code>-quiet</code>, <code>-verbose</code>, <code>-debug</code>) aware</li>
<li>Emacs-mode aware</li>
</ul>
@@ -65,9 +65,9 @@ listeners and loggers.</p>
<table>
<tr>
- <td>Classname</td>
- <td>Description</td>
- <td>Type</td>
+ <th>Classname</th>
+ <th>Description</th>
+ <th>Type</th>
</tr>
<tr>
<td><code><a href="#DefaultLogger">org.apache.tools.ant.DefaultLogger</a></code></td>
@@ -76,32 +76,26 @@ listeners and loggers.</p>
<td>BuildLogger</td>
</tr>
<tr>
- <td><code><a href="#NoBannerLogger">
- org.apache.tools.ant.NoBannerLogger</a></code></td>
+ <td><code><a href="#NoBannerLogger">org.apache.tools.ant.NoBannerLogger</a></code></td>
<td>This logger omits output of empty target output.</td>
<td>BuildLogger</td>
</tr>
<tr>
- <td><code><a href="#MailLogger">
- org.apache.tools.ant.listener.MailLogger</a></code></td>
+ <td><code><a href="#MailLogger">org.apache.tools.ant.listener.MailLogger</a></code></td>
<td>Extends DefaultLogger such that output is still generated
the same, and when the build is finished an e-mail can be sent.</td>
<td>BuildLogger</td>
</tr>
<tr>
- <td><code><a href="#AnsiColorLogger">
- org.apache.tools.ant.listener.AnsiColorLogger</a></code></td>
+ <td><code><a href="#AnsiColorLogger">org.apache.tools.ant.listener.AnsiColorLogger</a></code></td>
<td>Colorifies the build output.</td>
<td>BuildLogger</td>
</tr>
<tr>
- <td><code><a href="#Log4jListener">
- org.apache.tools.ant.listener.Log4jListener</a></code></td>
- <td>
- Passes events to Apache Log4j for highly customizable logging.<br>
- <b>Deprecated:</b> Apache Log4j (1.x) is not developed any more. Last
- release is 1.2.17 from 26-May-2012 and contains vulnerability issues.
- </td>
+ <td><code><a href="#Log4jListener">org.apache.tools.ant.listener.Log4jListener</a></code></td>
+ <td>Passes events to Apache Log4j for highly customizable logging.<br/>
+ <em><u>Deprecated</u></em>: Apache Log4j (1.x) is not developed any more. Last
+ release is 1.2.17 from 26 May 2012 and contains vulnerability issues.</td>
<td>BuildListener</td>
</tr>
<tr>
@@ -155,124 +149,120 @@ control for turning off success or failure messages individually.</p>
<th>Required</th>
</tr>
<tr>
- <td>MailLogger.mailhost </td>
+ <td><code>MailLogger.mailhost</code></td>
<td>Mail server to use</td>
- <td>No, default "localhost"</td>
+ <td>No; default <q>localhost</q></td>
</tr>
<tr>
- <td>MailLogger.port </td>
+ <td><code>MailLogger.port</code></td>
<td>SMTP Port for the Mail server</td>
- <td>No, default "25"</td>
+ <td>No; default <q>25</q></td>
</tr>
<tr>
- <td>MailLogger.user</td>
+ <td><code>MailLogger.user</code></td>
<td>user name for SMTP auth</td>
- <td>Yes, if SMTP auth is required on your SMTP server<br>
- the email message will be then sent using Mime and requires JavaMail</td>
+ <td>Yes, if SMTP auth is required on your SMTP server<br/>
+ the email message will be then sent using MIME and requires JavaMail</td>
</tr>
<tr>
- <td>MailLogger.password</td>
+ <td><code>MailLogger.password</code></td>
<td>password for SMTP auth</td>
- <td>Yes, if SMTP auth is required on your SMTP server<br>
- the email message will be then sent using Mime and requires JavaMail</td>
+ <td>Yes, if SMTP auth is required on your SMTP server<br/>
+ the email message will be then sent using MIME and requires JavaMail</td>
</tr>
<tr>
- <td>MailLogger.ssl</td>
- <td>on or true if ssl is needed<br>
+ <td><code>MailLogger.ssl</code></td>
+ <td>on or true if SSL is needed<br/>
This feature requires JavaMail</td>
- <td>
- no</td>
+ <td>No</td>
</tr>
<tr>
- <td>MailLogger.from</td>
- <td>Mail "from" address</td>
+ <td><code>MailLogger.from</code></td>
+ <td>Mail <q>from</q> address</td>
<td>Yes, if mail needs to be sent</td>
</tr>
<tr>
- <td>MailLogger.replyto</td>
- <td>Mail "replyto" address(es), comma-separated</td>
+ <td><code>MailLogger.replyto</code></td>
+ <td>Mail <q>replyto</q> address(es), comma-separated</td>
<td>No</td>
</tr>
<tr>
- <td>MailLogger.failure.notify </td>
+ <td><code>MailLogger.failure.notify</code></td>
<td>Send build failure e-mails?</td>
- <td>No, default "true"</td>
+ <td>No; default <q>true</q></td>
</tr>
<tr>
- <td>MailLogger.success.notify </td>
+ <td><code>MailLogger.success.notify</code></td>
<td>Send build success e-mails?</td>
- <td>No, default "true"</td>
+ <td>No; default <q>true</q></td>
</tr>
<tr>
- <td>MailLogger.failure.to </td>
+ <td><code>MailLogger.failure.to</code></td>
<td>Address(es) to send failure messages to, comma-separated</td>
<td>Yes, if failure mail is to be sent</td>
</tr>
<tr>
- <td>MailLogger.success.to </td>
+ <td><code>MailLogger.success.to</code></td>
<td>Address(es) to send success messages to, comma-separated</td>
<td>Yes, if success mail is to be sent</td>
</tr>
<tr>
- <td>MailLogger.failure.cc </td>
+ <td><code>MailLogger.failure.cc</code></td>
<td>Address(es) to send failure messages to carbon copy (cc), comma-separated</td>
<td>No</td>
</tr>
<tr>
- <td>MailLogger.success.cc </td>
+ <td><code>MailLogger.success.cc</code></td>
<td>Address(es) to send success messages to carbon copy (cc), comma-separated</td>
<td>No</td>
</tr>
<tr>
- <td>MailLogger.failure.bcc </td>
+ <td><code>MailLogger.failure.bcc</code></td>
<td>Address(es) to send failure messages to blind carbon copy (bcc), comma-separated</td>
<td>No</td>
</tr>
<tr>
- <td>MailLogger.success.bcc </td>
+ <td><code>MailLogger.success.bcc</code></td>
<td>Address(es) to send success messages to blind carbon copy (bcc), comma-separated</td>
<td>No</td>
</tr>
<tr>
- <td>MailLogger.failure.subject </td>
+ <td><code>MailLogger.failure.subject</code></td>
<td>Subject of failed build</td>
- <td>No, default "Build Failure"</td>
+ <td>No; default <q>Build Failure</q></td>
</tr>
<tr>
- <td>MailLogger.success.subject </td>
+ <td><code>MailLogger.success.subject</code></td>
<td>Subject of successful build</td>
- <td>No, default "Build Success"</td>
+ <td>No; default <q>Build Success</q></td>
</tr>
<tr>
- <td>MailLogger.failure.body</td>
- <td>Fixed body of the email for a failed
- build. <em>Since Ant 1.8.0</em></td>
- <td>No, default is to send the full log output.</td>
+ <td><code>MailLogger.failure.body</code></td>
+ <td>Fixed body of the email for a failed build. <em>Since Ant 1.8.0</em></td>
+ <td>No; default is to send the full log output</td>
</tr>
<tr>
- <td>MailLogger.success.body</td>
- <td>Fixed body of the email for a successful
- build. <em>Since Ant 1.8.0</em></td>
- <td>No, default is to send the full log output.</td>
+ <td><code>MailLogger.success.body</code></td>
+ <td>Fixed body of the email for a successful build. <em>Since Ant 1.8.0</em></td>
+ <td>No; default is to send the full log output</td>
</tr>
<tr>
- <td>MailLogger.mimeType</td>
+ <td><code>MailLogger.mimeType</code></td>
<td>MIME-Type of the message. <em>Since Ant 1.8.0</em></td>
- <td>No, default is text/plain</td>
+ <td>No; default is <q>text/plain</q></td>
</tr>
<tr>
- <td>MailLogger.charset</td>
+ <td><code>MailLogger.charset</code></td>
<td>Character set of the message. <em>Since Ant 1.8.0</em></td>
<td>No</td>
</tr>
<tr>
- <td>MailLogger.starttls.enable</td>
- <td>on or true if STARTTLS should be supported
- (requires JavaMail). <em>Since Ant 1.8.0</em></td>
- <td>No, default is false</td>
+ <td><code>MailLogger.starttls.enable</code></td>
+ <td>on or true if <code>STARTTLS</code> should be supported (requires JavaMail). <em>Since Ant 1.8.0</em></td>
+ <td>No; default is <q>false</q></td>
</tr>
<tr>
- <td>MailLogger.properties.file </td>
+ <td><code>MailLogger.properties.file</code></td>
<td>Filename of properties file that will override other values.</td>
<td>No</td>
</tr>
@@ -288,79 +278,81 @@ it. It is just an extension of <a href="#DefaultLogger">DefaultLogger</a>
and hence provides all features that DefaultLogger does.</p>
<p>AnsiColorLogger differentiates the output by assigning
different colors depending upon the type of the message.</p>
-<p>If used with the -logfile option, the output file
+<p>If used with the <code>-logfile</code> option, the output file
will contain all the necessary escape codes to
display the text in colorized mode when displayed
-in the console using applications like cat, more, etc.</p>
+in the console using applications like <code>cat</code>, <code>more</code>, etc.</p>
<p>This is designed to work on terminals that support ANSI
color codes. It works on XTerm, ETerm, Win9x Console
(with ANSI.SYS loaded.), etc.</p>
-<p><strong>NOTE:</strong>
-It doesn't work on WinNT and successors, even when a COMMAND.COM console loaded with
-ANSI.SYS is used.</p>
+<p><strong>Note</strong>: It doesn't work on WinNT and successors,
+even when a <code>COMMAND.COM</code> console loaded with ANSI.SYS is used.</p>
<p>If the user wishes to override the default colors
with custom ones, a file containing zero or more of the
custom color key-value pairs must be created. The recognized keys
-and their default values are shown below:</p><pre>
+and their default values are shown below:</p>
+<pre>
AnsiColorLogger.ERROR_COLOR=2;31
AnsiColorLogger.WARNING_COLOR=2;35
AnsiColorLogger.INFO_COLOR=2;36
AnsiColorLogger.VERBOSE_COLOR=2;32
AnsiColorLogger.DEBUG_COLOR=2;34</pre>
<p>Each key takes as value a color combination defined as
-<b>Attribute;Foreground;Background</b>. In the above example, background
+<q>Attribute;Foreground;Background</q>. In the above example, background
value has not been used.</p>
<p>This file must be specified as the value of a system variable
-named ant.logger.defaults and passed as an argument using the -D
-option to the <b>java</b> command that invokes the Ant application.
-An easy way to achieve this is to add -Dant.logger.defaults=
-<i>/path/to/your/file</i> to the ANT_OPTS environment variable.
-Ant's launching script recognizes this flag and will pass it to
-the java command appropriately.</p>
-<p>Format:</p><pre>
+named <code>ant.logger.defaults</code> and passed as an argument using
+the <code>-D</code> option to the <code>java</code> command that
+invokes the Ant application. An easy way to achieve this is to
+add <code>-Dant.logger.defaults=</code><samp>/path/to/your/file</samp>
+to the <code>ANT_OPTS</code> environment variable. Ant's launching
+script recognizes this flag and will pass it to the <code>java</code>
+command appropriately.</p>
+<p>Format:</p>
+<pre>
AnsiColorLogger.*=Attribute;Foreground;Background
Attribute is one of the following:
-0 -> Reset All Attributes (return to normal mode)
-1 -> Bright (Usually turns on BOLD)
-2 -> Dim
-3 -> Underline
-5 -> link
-7 -> Reverse
-8 -> Hidden
+0 → Reset All Attributes (return to normal mode)
+1 → Bright (Usually turns on BOLD)
+2 → Dim
+3 → Underline
+5 → link
+7 → Reverse
+8 → Hidden
Foreground is one of the following:
-30 -> Black
-31 -> Red
-32 -> Green
-33 -> Yellow
-34 -> Blue
-35 -> Magenta
-36 -> Cyan
-37 -> White
+30 → Black
+31 → Red
+32 → Green
+33 → Yellow
+34 → Blue
+35 → Magenta
+36 → Cyan
+37 → White
Background is one of the following:
-40 -> Black
-41 -> Red
-42 -> Green
-43 -> Yellow
-44 -> Blue
-45 -> Magenta
-46 -> Cyan
-47 -> White</pre>
+40 → Black
+41 → Red
+42 → Green
+43 → Yellow
+44 → Blue
+45 → Magenta
+46 → Cyan
+47 → White</pre>
<pre>ant -logger org.apache.tools.ant.listener.AnsiColorLogger</pre>
<h3 id="Log4jListener">Log4jListener</h3>
-<p><b>Deprecated:</b> Apache Log4j (1) is not developed any more. Last
-release is 1.2.17 from 26-May-2012 and contains vulnerability issues.</p>
+<p><em><u>Deprecated</u></em>: Apache Log4j (1) is not developed any more. Last
+release is 1.2.17 from 26 May 2012 and contains vulnerability issues.</p>
<p>Passes build events to Log4j, using the full classname's of the generator of
each build event as the category:</p>
<ul>
- <li>build started / build finished - org.apache.tools.ant.Project</li>
- <li>target started / target finished - org.apache.tools.ant.Target</li>
- <li>task started / task finished - the fully qualified classname of the task</li>
- <li>message logged - the classname of one of the above, so if a task logs a
+ <li>build started / build finished—<code>org.apache.tools.ant.Project</code></li>
+ <li>target started / target finished—<code>org.apache.tools.ant.Target</code></li>
+ <li>task started / task finished—the fully qualified classname of the task</li>
+ <li>message logged—the classname of one of the above, so if a task logs a
message, its classname is the category used, and so on.</li>
</ul>
<p>All start events are logged as INFO. Finish events are either logged as
@@ -370,18 +362,19 @@ corresponding Log4j level.</p>
<pre>ant -listener org.apache.tools.ant.listener.Log4jListener</pre>
-<p>To use Log4j you will need the Log4j JAR file and a 'log4j.properties'
+<p>To use Log4j you will need the Log4j JAR file and a <samp>log4j.properties</samp>
configuration file. Both should be placed somewhere in your Ant
-classpath. If the log4j.properties is in your project root folder you can
-add this with <i>-lib</i> option:</p>
+classpath. If the <samp>log4j.properties</samp> is in your project root folder you can
+add this with <code>-lib</code> option:</p>
<pre>ant -listener org.apache.tools.ant.listener.Log4jListener -lib .</pre>
<p>If, for example, you wanted to capture the same information output to the
-console by the DefaultLogger and send it to a file named 'build.log', you
+console by the DefaultLogger and send it to a file named <samp>build.log</samp>, you
could use the following configuration:</p>
-<pre>log4j.rootLogger=ERROR, LogFile
+<pre>
+log4j.rootLogger=ERROR, LogFile
log4j.logger.org.apache.tools.ant.Project=INFO
log4j.logger.org.apache.tools.ant.Target=INFO
log4j.logger.org.apache.tools.ant.taskdefs=INFO
@@ -390,26 +383,26 @@ log4j.logger.org.apache.tools.ant.taskdefs.Echo=WARN
log4j.appender.LogFile=org.apache.log4j.FileAppender
log4j.appender.LogFile.layout=org.apache.log4j.PatternLayout
log4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%n
-log4j.appender.LogFile.file=build.log
-</pre>
+log4j.appender.LogFile.file=build.log</pre>
-<p>For more information about configuring Log4J see <a href="http://logging.apache.org/log4j/docs/documentation.html">its
+<p>For more information about configuring Log4J see <a href="https://logging.apache.org/log4j/1.2/">its
documentation page</a>.</p>
<h4>Using the Log4j 1.2 Bridge</h4>
-You could use the <a href="http://logging.apache.org/log4j/2.x/log4j-1.2-api/index.html">Log4j Bridge</a>
+You could use the <a href="https://logging.apache.org/log4j/2.x/log4j-1.2-api/index.html">Log4j Bridge</a>
if your application is written against the Log4j (1.x) API, but you want to use the Log4j 2.x runtime.
For using the bridge with Ant you have to add
<ul>
- <li>log4j-1.2-api-${log4j.version}.jar</li>
- <li>log4j-api-${log4j.version}.jar</li>
- <li>log4j-core-${log4j.version}.jar</li>
- <li>log4j2.xml</li>
+ <li><samp>log4j-1.2-api-${log4j.version}.jar</samp></li>
+ <li><samp>log4j-api-${log4j.version}.jar</samp></li>
+ <li><samp>log4j-core-${log4j.version}.jar</samp></li>
+ <li><samp>log4j2.xml</samp></li>
</ul>
-to your classpath (e.g. via the <code>-lib</code> option).
-(For using the bridge Ant 1.9.10/1.10.2 or higher is required.)
+to your classpath, e.g. via the <code>-lib</code> option.
+(For using the bridge, Ant 1.9.10/1.10.2 or higher is required.)
Translating the 1.x properties file into the 2.x xml syntax would result in
-<pre><?xml version="1.0" encoding="UTF-8"?>
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
<Appenders>
<File name="file" fileName="build.log">
@@ -427,43 +420,42 @@ Translating the 1.x properties file into the 2.x xml syntax would result in
<Logger name="org.apache.tools.ant.taskdefs" level="INFO"/>
<Logger name="org.apache.tools.ant.taskdefs.Echo" level="WARN"/>
</Loggers>
-</Configuration>
-</pre>
+</Configuration></pre>
<h3 id="XmlLogger">XmlLogger</h3>
-<p>Writes all build information out to an XML file named log.xml, or the value
-of the <code>XmlLogger.file</code> property if present, when used as a
+<p>Writes all build information out to an XML file
+named <samp>log.xml</samp>, or the value of
+the <code>XmlLogger.file</code> property if present, when used as a
listener. When used as a logger, it writes all output to either the
-console or to the value of <code>-logfile</code>. Whether used as a listener
-or logger, the output is not generated until the build is complete, as it
-buffers the information in order to provide timing information for task,
-targets, and the project.</p>
-<p>By default the XML file creates a reference to an XSLT file "log.xsl" in the current directory;
-look in ANT_HOME/etc for one of these. You can set the property
-<code>ant.XmlLogger.stylesheet.uri</code> to provide a uri to a style sheet.
-this can be a relative or absolute file path, or an http URL.
-If you set the property to the empty string, "", no XSLT transform
-is declared at all.</p>
+console or to the value of <code>-logfile</code>. Whether used as a
+listener or logger, the output is not generated until the build is
+complete, as it buffers the information in order to provide timing
+information for task, targets, and the project.</p>
+<p>By default the XML file creates a reference to an XSLT
+file <samp>log.xsl</samp> in the current directory; look
+in <samp>ANT_HOME/etc</samp> for one of these. You can set the
+property <code>ant.XmlLogger.stylesheet.uri</code> to provide a URI
+to a style sheet. This can be a relative or absolute file path, or
+an HTTP URL. If you set the property to the empty string, <q></q>,
+no XSLT transform is declared at all.</p>
<pre>ant -listener org.apache.tools.ant.XmlLogger
ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml</pre>
<h3 id="TimestampedLogger">TimestampedLogger</h3>
<p>
- Acts like the default logger, except that the final success/failure message also includes
- the time that the build completed. For example:
+Acts like the default logger, except that the final success/failure message also includes
+the time that the build completed. For example:
</p>
-<pre>
- BUILD SUCCESSFUL - at 16/08/05 16:24
-</pre>
+<pre>BUILD SUCCESSFUL - at 16/08/05 16:24</pre>
<p>To use this listener, use the command:</p>
<pre>ant -logger org.apache.tools.ant.listener.TimestampedLogger</pre>
<h3 id="BigProjectLogger">BigProjectLogger</h3>
<p>
- This logger is designed to make examining the logs of a big build easier,
- especially those run under continuous integration tools. It
+This logger is designed to make examining the logs of a big build easier,
+especially those run under continuous integration tools. It
</p>
<ol>
<li>When entering a child project, prints its name and directory</li>
@@ -473,13 +465,12 @@ ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml</pre>
<li>Includes the build finished timestamp of the TimeStamp logger</li>
</ol>
<p>
- This is useful when using <subant> to build a large project
- from many smaller projects -the output shows which particular
- project is building. Here is an example in which "clean" is being called
- on all a number of child projects, only some of which perform work:
+This is useful when using <code><subant></code> to build a large project
+from many smaller projects—the output shows which particular
+project is building. Here is an example in which "clean" is being called
+on all a number of child projects, only some of which perform work:
</p>
<pre>
-
======================================================================
Entering project "xunit"
In /home/ant/components/xunit
@@ -500,22 +491,21 @@ In /home/ant/components/junit
======================================================================
Exiting project "junit"
-======================================================================
-</pre>
+======================================================================</pre>
<p>
- The entry and exit messages are very verbose in this example, but in
- a big project compiling or testing many child components, the messages
- are reduced to becoming clear delimiters of where different projects
- are in charge -or more importantly, which project is failing.
+The entry and exit messages are very verbose in this example, but in
+a big project compiling or testing many child components, the messages
+are reduced to becoming clear delimiters of where different projects
+are in charge—or, more importantly, which project is failing.
</p>
<p>To use this listener, use the command:</p>
-<pre>ant -logger org.apache.tools.ant.listener.BigProjectLogger</pre>
+<pre>ant -logger org.apache.tools.ant.listener.BigProjectLogger</pre>
<h3 id="SimpleBigProjectLogger">SimpleBigProjectLogger</h3>
-<p>Like <code>BigProjectLogger</code>, project-qualified target names are printed,
-useful for big builds with subprojects.
-Otherwise it is as quiet as <code>NoBannerLogger</code>:</p>
+<p>Like <code>BigProjectLogger</code>, project-qualified target names
+are printed, useful for big builds with subprojects. Otherwise it is
+as quiet as <code>NoBannerLogger</code>:</p>
<pre>
Buildfile: /sources/myapp/build.xml
@@ -534,16 +524,16 @@ myapp.jar:
Building jar: /sources/myapp/build/myapp.jar
BUILD SUCCESSFUL
-Total time: 1 second
-</pre>
+Total time: 1 second</pre>
<p><em>since Ant 1.8.1</em></p>
<p>To use this listener, use the command:</p>
<pre>ant -logger org.apache.tools.ant.listener.SimpleBigProjectLogger</pre>
<h3 id="ProfileLogger">ProfileLogger</h3>
-<p>This logger stores the time needed for executing a task, target and the whole build and prints
-these information. The output contains a timestamp when entering the build, target or task and a timestamp and the needed time when exiting.
-</p>
+<p>This logger stores the time needed for executing a task, target and
+the whole build and prints these information. The output contains a
+timestamp when entering the build, target or task and a timestamp
+and the needed time when exiting.</p>
<!-- This is the 'since' as described in the Loggers JavaDoc -->
<p><em>since Ant 1.8.0</em></p>
<h4>Example</h4>
@@ -559,9 +549,8 @@ Having that buildfile
<target name="anotherTarget" depends="aTarget">
<echo>another-echo-task</echo>
</target>
-</project>
-</pre>
-and executing with <tt>ant -logger org.apache.tools.ant.listener.ProfileLogger anotherTarget</tt> gives that output (with other timestamps and duration of course ;) :
+</project></pre>
+and executing with <code>ant -logger org.apache.tools.ant.listener.ProfileLogger anotherTarget</code> gives that output (with other timestamps and duration of course ;-):
<pre>
Buildfile: ...\build.xml
@@ -589,13 +578,11 @@ echo: finished Thu Jan 22 09:01:01 CET 2009 (0ms)
Target anotherTarget: finished Thu Jan 22 09:01:01 CET 2009 (0ms)
BUILD SUCCESSFUL
-Total time: 2 seconds
-</pre>
+Total time: 2 seconds</pre>
<h2 id="dev">Writing your own</h2>
-<p>See the <a href="develop.html#buildevents">Build Events</a> section for
-developers.</p>
+<p>See the <a href="develop.html#buildevents">Build Events</a> section for developers.</p>
<p>Notes:</p>
@@ -610,7 +597,7 @@ developers.</p>
</li>
<li>When a build is started, and <code>BuildListener.buildStarted(BuildEvent event)</code> is called,
the project is not fully functional. The build has started, yes, and the <code>event.getProject()</code> method call
- returns the Project instance, but that project is initialized with JVM and ant properties, nor has it
+ returns the Project instance, but that project is initialized with JVM and Ant properties, nor has it
parsed the build file yet. You cannot call <code>Project.getProperty()</code> for property lookup, or
<code>Project.getName()</code> to get the project name (it will return null).
</li>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/platform.html
----------------------------------------------------------------------
diff --git a/manual/platform.html b/manual/platform.html
index 0213b23..29158f1 100644
--- a/manual/platform.html
+++ b/manual/platform.html
@@ -25,105 +25,103 @@
<h1>Platform Issues</h1>
<h2>Java versions</h2>
-<h3>Java 1.5</h3>
-
-You may need a bigger stack than default, especially if you are using the built in
-XSLT engine. We recommend you use Apache Xalan; indeed, some tasks (JUnit report in XML,
-for example) may not work against the shipping XSL engine.
+<h3>Java 5</h3>
+<p>
+You may need a bigger stack than default, especially if you are using
+the built in XSLT engine. We recommend you use Apache Xalan; indeed,
+some tasks (JUnit report in XML, for example) may not work against the
+shipping XSL engine.
+</p>
<h2>Unix and Linux</h2>
-
<ul>
-<li> You should use a GNU version of <tt>tar</tt> to untar the Apache
+<li>You should use a GNU version of <code>tar</code> to untar the Apache
Ant source tree, if you have downloaded this as a tar file. If you get
-weird errors about missing files, this is the problem.
-</li>
-<li> Ant does not preserve file permissions when a file is copied, moved or
-archived, because Java does not let it read or write the permissions.
- Use <tt><chmod></tt> to set permissions, and when creating a
-tar archive, use the <tt>mode</tt> attribute of <tt><tarfileset></tt>
-to set the permissions in the tar file, or <code><apply></code> the real tar program.
-</li>
-<li> Ant is not symbolic link aware in moves, deletes and when recursing down a tree
-of directories to build up a list of files. Unexpected things can happen.
-</li>
-<li> Linux on IA-64: apparently you need a larger heap than the default
-one (64M) to compile big projects. If you get out of heap
-errors, either increase the heap or use a forking javac. Better yet,
-use jikes for extra compilation speed.
-</li>
+weird errors about missing files, this is the problem.</li>
+<li>Ant does not preserve file permissions when a file is copied,
+moved or archived, because Java does not let it read or write the
+permissions. Use <code><chmod></code> to set permissions, and
+when creating a tar archive, use the <var>mode</var> attribute
+of <code><tarfileset></code> to set the permissions in the tar
+file, or <code><apply></code> the real tar program.</li>
+<li>Ant is not symbolic link aware in moves, deletes and when
+recursing down a tree of directories to build up a list of
+files. Unexpected things can happen.</li>
+<li>Linux on IA-64: apparently you need a larger heap than the default
+one (64M) to compile big projects. If you get out of heap errors,
+either increase the heap or use a forking javac. Better yet, use jikes
+for extra compilation speed.</li>
</ul>
<h2>Microsoft Windows</h2>
<p>
Windows 9x (win95, win98, win98SE and winME) are not supported in Ant1.7,
</p>
-
<p>
-The Ant team has retired support for these products because they are outdated and
-can expose customers to security risks. We recommend that customers who are
-still running Windows 98 or Windows Me upgrade to a newer, more secure
-operating system, as soon as possible.
+The Ant team has retired support for these products because they are
+outdated and can expose customers to security risks. We recommend that
+customers who are still running Windows 98 or Windows Me upgrade to a
+newer, more secure operating system, as soon as possible.
</p>
<p>
Customers who upgrade to Linux report improved security, richer
functionality, and increased productivity.
</p>
-<h2>Microsoft Windows 2K, XP and Server 2K03 </h2>
-
+<h2>Microsoft Windows 2K, XP and Server 2K03</h2>
<p>
-Windows 9x (win95, win98, win98SE and winME) has a batch file system which
-does not work fully with long file names, so we recommend that ant and the JDK
-are installed into directories without spaces, and with 8.3 filenames.
-The Perl and Python launcher scripts do not suffer from this limitation.
+Windows 9x (win95, win98, win98SE and winME) has a batch file system
+which does not work fully with long file names, so we recommend that
+ant and the JDK are installed into directories without spaces, and
+with 8.3 filenames. The Perl and Python launcher scripts do not
+suffer from this limitation.
</p>
<p>
-All versions of windows are usually case insensitive, although mounted
-file systems (Unix drives, Clearcase views) can be case sensitive underneath,
-confusing patternsets.
+All versions of Windows are usually case insensitive, although mounted
+file systems (Unix drives, ClearCase views) can be case sensitive
+underneath, confusing patternsets.
</p>
<p>
-Ant can often not delete a directory which is open in an Explorer window.
-There is nothing we can do about this short of spawning a program to kill
-the shell before deleting directories.
-Nor can files that are in use be overwritten.
+Ant can often not delete a directory which is open in an Explorer
+window. There is nothing we can do about this short of spawning a
+program to kill the shell before deleting directories. Nor can files
+that are in use be overwritten.
</p>
<p>
- Finally, if any Ant task fails with an IOError=2, it means that whatever
- native program Ant is trying to run, it is not on the path.
+Finally, if any Ant task fails with an <code>error=2</code>, it
+means that whatever native program Ant is trying to run, it is not
+on the path.
</p>
<h2>Microsoft Windows Vista</h2>
-
<p>
- There are reports of problems with Windows Vista security bringing up
- dialog boxes asking if the user wants to run an untrusted executable
- during an ant run, such as when the <signjar> task runs the jarsigner.exe
- program. This is beyond Ant's control, and stems from the OS trying to provide
- some illusion of security by being reluctant to run unsigned native executables.
- The latest Java versions appear to resolve this problem by having signed
- binaries.
+There are reports of problems with Windows Vista security bringing
+up dialog boxes asking if the user wants to run an untrusted
+executable during an Ant run, such as when the <signjar> task
+runs the <code>jarsigner.exe</code> program. This is beyond Ant's
+control, and stems from the OS trying to provide some illusion of
+security by being reluctant to run unsigned native executables. The
+latest Java versions appear to resolve this problem by having signed
+binaries.
</p>
<h2>Cygwin</h2>
-
<p>
Cygwin is not an operating system; rather it is an application suite
-running under Windows and providing some UNIX like functionality. Sun has
-not created any specific Java Development Kit or Java Runtime Environment for
-cygwin. See this link :
-<a href="http://www.inonit.com/cygwin/faq/">http://www.inonit.com/cygwin/faq/</a> .
-Only Windows path
-names are supported by JDK and JRE tools under Windows or cygwin. Relative path
-names such as "src/org/apache/tools" are supported, but Java tools do not
-understand /cygdrive/c to mean c:\.
+running under Windows and providing some UNIX like functionality. Sun
+has not created any specific Java Development Kit or Java Runtime
+Environment for cygwin. See this
+link: <a href="http://www.inonit.com/cygwin/faq/">http://www.inonit.com/cygwin/faq/</a>.
+Only Windows path names are supported by JDK and JRE tools under
+Windows or cygwin. Relative path names such as "src/org/apache/tools"
+are supported, but Java tools do not
+understand <samp>/cygdrive/c</samp> to mean <samp>c:\</samp>.
</p>
<p>
-The utility cygpath (used industrially in the ant script to support cygwin) can
-convert cygwin path names to Windows.
-You can use the <code><exec></code> task in ant to convert cygwin paths to Windows path, for
-instance like that:
+The utility <code>cygpath</code> (used industrially in
+the <code>ant</code> script to support cygwin) can convert cygwin path
+names to Windows. You can use the <code><exec></code> task in
+Ant to convert cygwin paths to Windows path, for instance like that:
</p>
<pre>
<property name="some.cygwin.path" value="/cygdrive/h/somepath"/>
@@ -134,49 +132,67 @@ instance like that:
<echo message="${windows.pathname}"/>
</pre>
<p>
-We get lots of support calls from Cygwin users. Either it is incredibly
-popular, or it is trouble. If you do use it, remember that Java is a
-Windows application, so Ant is running in a Windows process, not a
-Cygwin one. This will save us having to mark your bug reports as invalid.
+We get lots of support calls from Cygwin users. Either it is
+incredibly popular, or it is trouble. If you do use it, remember that
+Java is a Windows application, so Ant is running in a Windows process,
+not a Cygwin one. This will save us having to mark your bug reports as
+invalid.
</p>
-<h2>Apple MacOS X</h2>
-
+<h2>Apple MacOS X/macOS</h2>
<p>
-MacOS X is the first of the Apple platforms that Ant supports completely;
-it is treated like any other Unix.
+MacOS X a.k.a. macOS is the first of the Apple platforms that Ant
+supports completely; it is treated like any other Unix.
</p>
<h2>Novell Netware</h2>
-
-<p>To give the same level of sophisticated control as Ant's startup scripts on other platforms, it was decided to make the main ant startup on NetWare be via a Perl Script, "runant.pl". This is found in the bin directory (for instance - bootstrap\bin or dist\bin).</p>
+<p>
+To give the same level of sophisticated control as Ant's startup
+scripts on other platforms, it was decided to make the main ant
+startup on NetWare be via a Perl Script, <code>runant.pl</code>. This
+is found in the <samp>bin</samp> directory (for
+instance—<samp>bootstrap\bin</samp>
+or <samp>dist\bin</samp>).
+</p>
<p>One important item of note is that you need to set up the following to run Ant:</p>
-<ul><li><code>CLASSPATH</code> - put ant.jar and any other needed jars on the system classpath.</li>
- <li><code>ANT_OPTS</code> - On NetWare, <code>ANT_OPTS</code> needs to include a parameter of the form, "<code>-envCWD=<i>ANT_HOME</i></code>", with <code><i>ANT_HOME</i></code> being the fully expanded location of Ant, <b>not</b> an environment variable. This is due to the fact that the NetWare System Console has no notion of a current working directory.</li>
+<ul>
+ <li><code>CLASSPATH</code>—put <samp>ant.jar</samp> and any other needed jars on the system classpath.</li>
+ <li><code>ANT_OPTS</code>—On NetWare, <code>ANT_OPTS</code>
+ needs to include a parameter of the
+ form, <code>-envCWD=<i>ANT_HOME</i></code>,
+ with <code><i>ANT_HOME</i></code> being the fully expanded location
+ of Ant, <strong>not</strong> an environment variable. This is due
+ to the fact that the NetWare System Console has no notion of a
+ current working directory.</li>
</ul>
-<p>It is suggested that you create up an ant.ncf that sets up these parameters, and calls <code>perl ANT_HOME/dist/bin/runant.pl</code></p>
-<p>The following is an example of such an NCF file (assuming Ant is installed in <code>'sys:/apache-ant/'</code>):</p>
+<p>It is suggested that you create up an ant.ncf that sets up these parameters, and calls <samp>perl ANT_HOME/dist/bin/runant.pl</samp></p>
+<p>The following is an example of such an NCF file (assuming Ant is installed in <samp>sys:/apache-ant/</samp>):</p>
<pre>
- envset CLASSPATH=SYS:/apache-ant/bootstrap/lib/ant.jar
- envset CLASSPATH=$CLASSPATH;SYS:/apache-ant/lib/optional/junit.jar
- envset CLASSPATH=$CLASSPATH;SYS:/apache-ant/bootstrap/lib/optional.jar
+envset CLASSPATH=sys:/apache-ant/bootstrap/lib/ant.jar
+envset CLASSPATH=$CLASSPATH;sys:/apache-ant/lib/optional/junit.jar
+envset CLASSPATH=$CLASSPATH;sys:/apache-ant/bootstrap/lib/optional.jar
- setenv ANT_OPTS=-envCWD=sys:/apache-ant
- envset ANT_OPTS=-envCWD=sys:/apache-ant
- setenv ANT_HOME=sys:/apache-ant/dist/lib
- envset ANT_HOME=sys:/apache-ant/dist/lib
+setenv ANT_OPTS=-envCWD=sys:/apache-ant
+envset ANT_OPTS=-envCWD=sys:/apache-ant
+setenv ANT_HOME=sys:/apache-ant/dist/lib
+envset ANT_HOME=sys:/apache-ant/dist/lib
- perl sys:/apache-ant/dist/bin/runant.pl
-</pre>
+perl sys:/apache-ant/dist/bin/runant.pl</pre>
-<p>Ant works on JVM version 1.3 or higher. You may have some luck running it on JVM 1.2, but serious problems have been found running Ant on JVM 1.1.7B. These problems are caused by JVM bugs that will not be fixed.</p>
+<p>Ant works on JVM version 1.3 or higher. You may have some luck
+running it on JVM 1.2, but serious problems have been found running
+Ant on JVM 1.1.7B. These problems are caused by JVM bugs that will
+not be fixed.</p>
<p>JVM 1.3 is supported on Novell NetWare versions 5.1 and higher.</p>
<h2>Other platforms</h2>
-Support for other platforms is not guaranteed to be complete, as certain
-techniques to hide platform details from build files need to be written and
-tested on every particular platform. Contributions in this area are welcome.
+<p>
+Support for other platforms is not guaranteed to be complete, as
+certain techniques to hide platform details from build files need to
+be written and tested on every particular platform. Contributions in
+this area are welcome.
+</p>
</body>
</html>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/projecthelper.html
----------------------------------------------------------------------
diff --git a/manual/projecthelper.html b/manual/projecthelper.html
index 4961694..4c2523e 100644
--- a/manual/projecthelper.html
+++ b/manual/projecthelper.html
@@ -29,102 +29,103 @@
<p>
The <code>ProjectHelper</code> in Apache Ant is responsible for parsing the build file
-and creating java instances representing the build workflow. It also signals which
+and creating Java instances representing the build workflow. It also signals which
kind of file it can parse, and which file name it expects as default input file.
</p>
<p>
-Ant' default <code>ProjectHelper</code>
+Ant's default <code>ProjectHelper</code>
(<code>org.apache.tools.ant.helper.ProjectHelper2</code>) parses the
-usual build.xml files. And if no build file is specified on the command line, it
-will expect to find a file named <code>build.xml</code>.
+usual <code>build.xml</code> files. And if no build file is specified on the command
+line, it will expect to find a file named <code>build.xml</code>.
</p>
<p>
The immediate benefit of a such abstraction it that it is possible to make Ant
-understand other kind of descriptive languages than XML. Some experiments have
-been done around a pure java frontend, and a groovy one too (ask the dev mailing
-list for further info about these).
+understand other kind of descriptive languages than XML. Some experiments have been
+done around a pure Java frontend, and a Groovy one too (ask the dev mailing list for
+further info about these).
</p>
-<p>Since Ant 1.8.2, the <a href="Tasks/import.html">import</a> task will also
-try to use the proper helper to parse the imported file. So it is possible to
-write different build files in different languages and have them import each
-other.
+<p>
+<em>Since Ant 1.8.2</em>, the <a href="Tasks/import.html">import</a> task will also
+try to use the proper helper to parse the imported file. So it is possible to write
+different build files in different languages and have them import each other.
</p>
<h2 id="repository">How is Ant is selecting the proper ProjectHelper</h2>
<p>
-Ant knows about several implementations of <code>ProjectHelper</code>
-and has to decide which to use for each build file.
+Ant knows about several implementations of <code>ProjectHelper</code> and has to
+decide which to use for each build file.
</p>
-<p>At startup Ant lists the all implementations found and keeps them
- in the same order they've been found in an internal 'repository':</p>
+<p>
+At startup Ant lists the all implementations found and keeps them in the same order
+they've been found in an internal 'repository':
+</p>
<ul>
- <li>the first to be searched for is the one declared by the system property
- <code>org.apache.tools.ant.ProjectHelper</code> (see
- <a href="running.html#sysprops">Java System Properties</a>);</li>
- <li>then it searches with its class loader for a <code>ProjectHelper</code>
- service declarations in the META-INF: it searches in the classpath for a
- file <code>META-INF/services/org.apache.tools.ant.ProjectHelper</code>.
- This file will just contain the fully qualified name of the
- implementation of <code>ProjectHelper</code> to instantiate;</li>
- <li>it will also search with the system class loader for
- <code>ProjectHelper</code> service declarations in the META-INF;</li>
- <li>last but not least it will add its default <code>ProjectHelper</code>
- that can parse classical build.xml files.</li>
+ <li>the first to be searched for is the one declared by the system property
+ <code>org.apache.tools.ant.ProjectHelper</code> (see
+ <a href="running.html#sysprops">Java System Properties</a>);</li>
+ <li>then it searches with its class loader for a <code>ProjectHelper</code>
+ service declarations in the <samp>META-INF</samp>: it searches in the classpath for a
+ file <samp>META-INF/services/org.apache.tools.ant.ProjectHelper</samp>.
+ This file will just contain the fully qualified name of the
+ implementation of <code>ProjectHelper</code> to instantiate;</li>
+ <li>it will also search with the system class loader for
+ <code>ProjectHelper</code> service declarations in the <samp>META-INF</samp>;</li>
+ <li>last but not least it will add its default <code>ProjectHelper</code>
+ that can parse classical <samp>build.xml</samp> files.</li>
</ul>
-<p>In case of an error while trying to instantiate a <code>ProjectHelper</code>, Ant
-will log an error but won't stop. If you want further debugging
-info about the <code>ProjectHelper</code> internal 'repository', use the <b>system</b>
-property <code>ant.project-helper-repo.debug</code> and set it to
-<code>true</code>; the full stack trace will then also be printed.
+<p>
+In case of an error while trying to instantiate a <code>ProjectHelper</code>, Ant will
+log an error but won't stop. If you want further debugging info about
+the <code>ProjectHelper</code> internal 'repository', use the <strong>system</strong>
+property <code>ant.project-helper-repo.debug</code> and set it to <code>true</code>;
+the full stack trace will then also be printed.
</p>
<p>
-When Ant is expected to parse a file, it will ask the
-<code>ProjectHelper</code> repository to find an implementation that will be
-able to parse the input file. Actually it will just iterate over the ordered list
-and the first implementation that returns <code>true</code> to
-<code>supportsBuildFile(File buildFile)</code> will be selected.
+When Ant is expected to parse a file, it will ask the <code>ProjectHelper</code>
+repository to find an implementation that will be able to parse the input
+file. Actually it will just iterate over the ordered list and the first implementation
+that returns <code>true</code> to <code>supportsBuildFile(File buildFile)</code> will
+be selected.
</p>
<p>
-When Ant is started and no input file has been specified, it will search for
-a default input file. It will iterate over list of <code>ProjectHelper</code>s
-and will select the first one that expects a default file that actually exist.
+When Ant is started and no input file has been specified, it will search for a default
+input file. It will iterate over list of <code>ProjectHelper</code>s and will select
+the first one that expects a default file that actually exist.
</p>
<h2 id="writing">Writing your own ProjectHelper</h2>
<p>
-The class <code>org.apache.tools.ant.ProjectHelper</code> is the API expected to
-be implemented. So write your own <code>ProjectHelper</code> by extending that
-abstract class. You are then expected to implement at least the function
-<code>parse(Project project, Object source)</code>. Note also that your
-implementation will be instantiated by Ant, and it is expecting a default
-constructor with no arguments.
+The class <code>org.apache.tools.ant.ProjectHelper</code> is the API expected to be
+implemented. So write your own <code>ProjectHelper</code> by extending that abstract
+class. You are then expected to implement at least the function <code>parse(Project
+project, Object source)</code>. Note also that your implementation will be
+instantiated by Ant, and it is expecting a default constructor with no arguments.
</p>
<p>
-There are some functions that will help you define what your helper is
-capable of and what is is expecting:
+There are some functions that will help you define what your helper is capable of and
+what is is expecting:
</p>
<ul>
- <li><code>getDefaultBuildFile()</code>: defines which file name is expected if
+ <li><code>getDefaultBuildFile()</code>: defines which file name is expected if
none provided</li>
- <li><code>supportsBuildFile(File buildFile)</code>: defines if your parser
+ <li><code>supportsBuildFile(File buildFile)</code>: defines if your parser
can parse the input file</li>
-
- <li><code>canParseAntlibDescriptor(URL url)</code>: whether your
- implementation is capable of parsing a given Antlib
- descriptor. The base class returns <code>false</code></li>
- <li><code>parseAntlibDescriptor(Project containingProject, URL
- source)</code>: invoked to actually parse the Antlib
- descriptor if your implementation returned <code>true</code>
- for the previous method.</li>
+ <li><code>canParseAntlibDescriptor(URL url)</code>: whether your
+ implementation is capable of parsing a given Antlib
+ descriptor. The base class returns <code>false</code></li>
+ <li><code>parseAntlibDescriptor(Project containingProject, URL
+ source)</code>: invoked to actually parse the Antlib
+ descriptor if your implementation returned <code>true</code>
+ for the previous method.</li>
</ul>
<p>
@@ -132,17 +133,17 @@ Now that you have your implementation ready, you have to declare it to Ant. Thre
solutions here:
</p>
<ul>
- <li>use the system property <code>org.apache.tools.ant.ProjectHelper</code>
- (see also the <a href="running.html#sysprops">Java System Properties</a>);</li>
- <li>use the service file in META-INF: in the jar you will build with your
- implementation, add a file
- <code>META-INF/services/org.apache.tools.ant.ProjectHelper</code>.
- And then in this file just put the fully qualified name of your
- implementation</li>
- <li>use the <a href="Tasks/projecthelper.html">projecthelper</a> task (since
- Ant 1.8.2) which will install dynamically an helper in the internal helper
- 'repository'. Then your helper can be used on the next call to the
- <a href="Tasks/import.html">import</a> task.</li>
+ <li>use the system property <code>org.apache.tools.ant.ProjectHelper</code>
+ (see also the <a href="running.html#sysprops">Java System Properties</a>);</li>
+ <li>use the service file in <samp>META-INF</samp>: in the jar you will build with your
+ implementation, add a file
+ <samp>META-INF/services/org.apache.tools.ant.ProjectHelper</samp>.
+ And then in this file just put the fully qualified name of your
+ implementation</li>
+ <li>use the <a href="Tasks/projecthelper.html">projecthelper</a> task (<em>since
+ Ant 1.8.2</em>) which will install dynamically a helper in the internal helper
+ 'repository'. Then your helper can be used on the next call to the
+ <a href="Tasks/import.html">import</a> task.</li>
</ul>
</body>
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/properties.html
----------------------------------------------------------------------
diff --git a/manual/properties.html b/manual/properties.html
index 54d231d..a8439a8 100644
--- a/manual/properties.html
+++ b/manual/properties.html
@@ -25,7 +25,7 @@
<body>
<h1>Properties</h1>
- <p>Properties are key-value-pairs where Apache Ant tries to
+ <p>Properties are key-value pairs where Apache Ant tries to
expand <code>${key}</code> to <code>value</code> at runtime.</p>
<p>There are many tasks that can set properties, the most common one
@@ -38,78 +38,83 @@
set, most tasks will not allow its value to be modified. In
general properties are of global scope, i.e. once they have been
defined they are available for any task or target invoked
- subsequently - it is not possible to set a property in a child
+ subsequently—it is not possible to set a property in a child
build process created via
- the <a href="Tasks/ant.html">ant</a>, antcall or subant tasks
- and make it available to the calling build process, though.</p>
-
- <p><em>Since Ant 1.8.0</em>
- the <a href="Tasks/local.html">local</a> task can be used to
- create properties that are locally scoped to a target or
- a <a href="Tasks/sequential.html">sequential</a> element like
- the one of the <a href="Tasks/macrodef.html">macrodef</a>
+ the <a href="Tasks/ant.html">ant</a>, <a href="Tasks/antcall.html">antcall</a>
+ or <a href="Tasks/subant.html">subant</a> tasks and make it
+ available to the calling build process, though.</p>
+
+ <p><em>Since Ant 1.8.0</em> the <a href="Tasks/local.html">local</a>
+ task can be used to create properties that are locally scoped to a
+ target or a <a href="Tasks/sequential.html">sequential</a> element
+ like the one of the <a href="Tasks/macrodef.html">macrodef</a>
task.</p>
<h2 id="built-in-props">Built-in Properties</h2>
<p>Ant provides access to all system properties as if they had been
defined using a <code><property></code> task. For
- example, <code>${os.name}</code> expands to the name of the
+ example, <samp>${os.name}</samp> expands to the name of the
operating system.</p>
- <p>For a list of system properties see
- <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/System.html#getProperties%28%29">the Javadoc of System.getProperties</a>.
+
+ <p>For a list of system properties,
+ see <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getProperties--">the javadoc of System.getProperties</a>.
</p>
<p>In addition, Ant has some built-in properties:</p>
-<pre><!-- TODO use <dl><dt><code>...</code></dt><dd>...</dd></dl> instead -->
-basedir the absolute path of the project's basedir (as set
- with the basedir attribute of <a href="using.html#projects"><project></a>).
-ant.file the absolute path of the buildfile.
-ant.version the version of Ant
-ant.project.name the name of the project that is currently executing;
- it is set in the name attribute of <project>.
-ant.project.default-target
- the name of the currently executing project's
- default target; it is set via the default
- attribute of <project>.
-ant.project.invoked-targets
- a comma separated list of the targets that have
- been specified on the command line (the IDE,
- an <ant> task ...) when invoking the current
- project.
- This property is set properly when the first target is executed.
- If you use it in the implicit target (directly
- under the <project> tag) the list will be
- empty if no target has been specified while it
- will contain the project's default target in this
- case for tasks nested into targets..
-ant.java.version the JVM version Ant detected; currently it can hold
- the values "9", "1.8",
- "1.7", "1.6", "1.5",
- "1.4", "1.3" and
- "1.2".
-ant.core.lib the absolute path of the <code>ant.jar</code> file.
-</pre>
+ <dl>
+ <dt><code>basedir</code></dt>
+ <dd>the absolute path of the project's basedir (as set
+ with the <var>basedir</var> attribute of <a href="using.html#projects"><project></a>).</dd>
+ <dt><code>ant.file</code></dt>
+ <dd>the absolute path of the buildfile.</dd>
+ <dt><code>ant.version</code></dt>
+ <dd>the version of Ant</dd>
+ <dt><code>ant.project.name</code></dt>
+ <dd>the name of the project that is currently executing; it is set
+ in the <var>name</var> attribute of <project>.</dd>
+ <dt><code>ant.project.default-target</code></dt>
+ <dd>the name of the currently executing project's default target;
+ it is set via the <var>default</var> attribute
+ of <code><project></code>.</dd>
+ <dt><code>ant.project.invoked-targets</code></dt>
+ <dd>a comma separated list of the targets that have been specified
+ on the command line (the IDE, an <code><ant></code> task
+ ...) when invoking the current project.<br/>
+ This property is set properly when the first target is executed.
+ If you use it in the implicit target (directly under
+ the <code><project></code> tag) the list will be empty if
+ no target has been specified while it will contain the project's
+ default target in this case for tasks nested into targets.</dd>
+ <dt><code>ant.java.version</code></dt>
+ <dd>the JVM version Ant detected; currently it can hold the
+ values <q>9</q>, <q>1.8</q>, <q>1.7</q>, <q>1.6</q>, <q>1.5</q>, <q>1.4</q>, <q>1.3</q>
+ and <q>1.2</q>.</dd>
+ <dt><code>ant.core.lib</code></dt>
+ <dd>the absolute path of the <samp>ant.jar</samp> file.</dd>
+ </dl>
<p>There is also another property, but this is set by the launcher
script and therefore maybe not set inside IDEs:</p>
-<pre>
-ant.home home directory of Ant
-</pre>
+ <dl>
+ <dt><code>ant.home</code></dt>
+ <dd>home directory of Ant</dd>
+ </dl>
<p>The following property is only set if Ant is started via the
Launcher class (which means it may not be set inside IDEs
either):</p>
-<pre>
-ant.library.dir the directory that has been used to load Ant's
- jars from. In most cases this is ANT_HOME/lib.
-</pre>
+ <dl>
+ <dt><code>ant.library.dir</code></dt>
+ <dd>the directory that has been used to load Ant's
+ jars from. In most cases this is <samp>ANT_HOME/lib</samp>.</dd>
+ </dl>
<h1 id="propertyHelper">PropertyHelpers</h1>
- <p>Ant's property handling is accomplished by an instance of
- <code>org.apache.tools.ant.PropertyHelper</code> associated with
- the current Project. You can learn more about this class by
+ <p>Ant's property handling is accomplished by an instance
+ of <code>org.apache.tools.ant.PropertyHelper</code> associated
+ with the current Project. You can learn more about this class by
examining Ant's Java API. In Ant 1.8 the PropertyHelper class was
much reworked and now itself employs a number of helper classes
(actually instances of
@@ -117,9 +122,9 @@ ant.library.dir the directory that has been used to load Ant's
marker interface) to take care of discrete tasks such as property
setting, retrieval, parsing, etc. This makes Ant's property
handling highly extensible; also of interest is the
- new <a href="Tasks/propertyhelper.html">propertyhelper</a>
- task used to manipulate the PropertyHelper and its delegates from
- the context of the Ant buildfile.
+ new <a href="Tasks/propertyhelper.html">propertyhelper</a> task
+ used to manipulate the PropertyHelper and its delegates from the
+ context of the Ant buildfile.</p>
<p>There are three sub-interfaces of <code>Delegate</code> that may be
useful to implement.</p>
@@ -127,22 +132,22 @@ ant.library.dir the directory that has been used to load Ant's
<ul>
<li><code>org.apache.tools.ant.property.PropertyExpander</code> is
responsible for finding the property name inside a string in the
- first place (the default extracts <code>foo</code>
- from <code>${foo}</code>).
+ first place (the default extracts <samp>foo</samp>
+ from <samp>${foo}</samp>).
<p>This is the interface you'd implement if you wanted to invent
- your own property syntax - or allow nested property expansions
+ your own property syntax—or allow nested property expansions
since the default implementation doesn't balance braces
(see <a href="https://git-wip-us.apache.org/repos/asf?p=ant-antlibs-props.git;a=blob;f=src/main/org/apache/ant/props/NestedPropertyExpander.java;hb=HEAD"><code>NestedPropertyExpander</code>
- in the "props" Antlib</a> for an example).</p>
+ in the <samp>props</samp> Antlib</a> for an example).</p>
</li>
<li><code>org.apache.tools.ant.PropertyHelper$PropertyEvaluator</code>
- is used to expand <code>${some-string}</code> into
+ is used to expand <samp>${some-string}</samp> into
an <code>Object</code>.
<p>This is the interface you'd implement if you want to provide
- your own storage independent of Ant's project instance - the
+ your own storage independent of Ant's project instance—the
interface represents the reading end. An example for this
would
be <code>org.apache.tools.ant.property.LocalProperties</code>
@@ -152,7 +157,7 @@ ant.library.dir the directory that has been used to load Ant's
<p>Another reason to implement this interface is if you wanted
to provide your own "property protocol" like
expanding <code>toString:foo</code> by looking up the project
- reference foo and invoking <code>toString()</code> on it
+ reference <samp>foo</samp> and invoking <code>toString()</code> on it
(which is already implemented in Ant, see below).</p>
</li>
@@ -160,7 +165,7 @@ ant.library.dir the directory that has been used to load Ant's
is responsible for setting properties.
<p>This is the interface you'd implement if you want to provide
- your own storage independent of Ant's project instance - the
+ your own storage independent of Ant's project instance—the
interface represents the reading end. An example for this
would
be <code>org.apache.tools.ant.property.LocalProperties</code>
@@ -188,12 +193,11 @@ public class DefaultExpander implements PropertyExpander {
}
return null;
}
-}
-</pre>
+}</pre>
- <p>The logic that replaces <code>${toString:some-id}</code> with the
+ <p>The logic that replaces <samp>${toString:<i>some-id</i>}</samp> with the
stringified representation of the object with
- id <code>some-id</code> inside the current build is contained in a
+ <var>id</var> <samp>some-id</samp> inside the current build is contained in a
PropertyEvaluator similar to the following code:</p>
<pre>
@@ -207,198 +211,194 @@ public class ToStringEvaluator implements PropertyHelper.PropertyEvaluator {
}
return o == null ? null : o.toString();
}
-}
-</pre>
+}</pre>
<h1>Property Expansion</h1>
- <p>When Ant encounters a construct <code>${some-text}</code> the
+ <p>When Ant encounters a construct <samp>${some-text}</samp> the
exact parsing semantics are subject to the configured property
helper delegates.</p>
<h2><code>$$</code> Expansion</h2>
- <p>In its default configuration Ant will expand the
- text <code>$$</code> to a single <code>$</code> and suppress the
- normal property expansion mechanism for the text immediately
- following it, i.e. <code>$${key}</code> expands
- to <code>${key}</code> and not <code>value</code> even though a
- property named <code>key</code> was defined and had the
- value <code>value</code>. This can be used to escape
- literal <code>$</code> characters and is useful in constructs that
- only look like property expansions or when you want to provide
+ <p>In its default configuration Ant will expand the text <q>$$</q>
+ to a single <q>$</q> and suppress the normal property expansion
+ mechanism for the text immediately following it,
+ i.e. <samp>$${key}</samp> expands to <samp>${key}</samp> and
+ not <code>value</code> even though a property
+ named <code>key</code> was defined and had the
+ value <samp>value</samp>. This can be used to escape
+ literal <q>$</q> characters and is useful in constructs that only
+ look like property expansions or when you want to provide
diagnostic output like in</p>
-<pre> <echo>$${builddir}=${builddir}</echo></pre>
+<pre><echo>$${builddir}=${builddir}</echo></pre>
- <p>which will echo this message:</p>
+ <p>which will echo this message:</p>
-<pre> ${builddir}=build/classes</pre>
+<pre>${builddir}=build/classes</pre>
<p>if the property <code>builddir</code> has the
- value <code>build/classes</code>.</p>
+ value <samp>build/classes</samp>.</p>
<p>In order to maintain backward compatibility with older Ant
- releases, a single '$' character encountered apart from a
+ releases, a single <q>$</q> character encountered apart from a
property-like construct (including a matched pair of french
- braces) will be interpreted literally; that is, as '$'. The
+ braces) will be interpreted literally; that is, as <q>$</q>. The
"correct" way to specify this literal character, however, is by
- using the escaping mechanism unconditionally, so that "$$" is
- obtained by specifying "$$$$". Mixing the two approaches yields
- unpredictable results, as "$$$" results in "$$".</p>
+ using the escaping mechanism unconditionally, so that <q>$$</q> is
+ obtained by specifying <q>$$$$</q>. Mixing the two approaches
+ yields unpredictable results, as <q>$$$</q> results
+ in <q>$$</q>.</p>
<h2>Nesting of Braces</h2>
<p>In its default configuration Ant will not try to balance braces
in property expansions, it will only consume the text up to the
first closing brace when creating a property name. I.e. when
- expanding something like <code>${a${b}}</code> it will be
+ expanding something like <samp>${a${b}}</samp> it will be
translated into two parts:</p>
<ol>
- <li>the expansion of property <code>a${b</code> - likely nothing
+ <li>the expansion of property <samp>a${b</samp>—likely nothing
useful.</li>
- <li>the literal text <code>}</code> resulting from the second
+ <li>the literal text <samp>}</samp> resulting from the second
closing brace</li>
</ol>
<p>This means you can't use easily expand properties whose names are
given by properties, but there
- are <a href="http://ant.apache.org/faq.html#propertyvalue-as-name-for-property">some
+ are <a href="https://ant.apache.org/faq.html#propertyvalue-as-name-for-property">some
workarounds</a> for older versions of Ant. With Ant 1.8.0 and the
- <a href="http://ant.apache.org/antlib/props/">the props Antlib</a>
+ <a href="https://ant.apache.org/antlib/props/">the props Antlib</a>
you can configure Ant to use
the <code>NestedPropertyExpander</code> defined there if you need
such a feature.</p>
<h2>Expanding a "Property Name"</h2>
- <p>In its most simple form <code>${key}</code> is supposed to look
+ <p>In its most simple form <samp>${key}</samp> is supposed to look
up a property named <code>key</code> and expand to the value of
the property. Additional <code>PropertyEvaluator</code>s may
result in a different interpretation of <code>key</code>,
though.</p>
- <p>The <a href="http://ant.apache.org/antlibs/props/">props
- Antlib</a> provides a few interesting evaluators but there are
- also a few built-in ones.</p>
+ <p>The <a href="https://ant.apache.org/antlibs/props/">props Antlib</a>
+ provides a few interesting evaluators but there are
+ also a few built-in ones.</p>
<h3 id="toString">Getting the value of a Reference with
- ${toString:}</h3>
+ <samp>${toString:}</samp></h3>
<p>Any Ant type which has been declared with a reference can also
- its string value extracted by using the <code>${toString:}</code>
+ its string value extracted by using the <samp>${toString:}</samp>
operation, with the name of the reference listed after
the <code>toString:</code> text. The <code>toString()</code>
- method of the Java class instance that is referenced is invoked
- -all built in types strive to produce useful and relevant output
- in such an instance.</p>
+ method of the Java class instance that is referenced is
+ invoked—all built in types strive to produce useful and
+ relevant output in such an instance.</p>
<p>For example, here is how to get a listing of the files in a fileset,<p>
<pre>
-<fileset id="sourcefiles" dir="src" includes="**/*.java" />
-<echo> sourcefiles = ${toString:sourcefiles} </echo>
-</pre>
+<fileset id="sourcefiles" dir="src" includes="**/*.java"/>
+<echo> sourcefiles = ${toString:sourcefiles} </echo></pre>
<p>There is no guarantee that external types provide meaningful
information in such a situation</p>
- <h3 id="ant.refid">Getting the value of a Reference with
- ${ant.refid:}</h3>
+ <h3 id="ant.refid">Getting the value of a Reference with <samp>${ant.refid:}</samp></h3>
<p>Any Ant type which has been declared with a reference can also be
- used as a property by using the <code>${ant.refid:}</code>
+ used as a property by using the <samp>${ant.refid:}</samp>
operation, with the name of the reference listed after
the <code>ant.refid:</code> text. The difference between this
- operation and <a href="#toString"><code>${toString:}</code></a> is
- that <code>${ant.refid:}</code> will expand to the referenced
- object itself. In most circumstances the toString method will be
- invoked anyway, for example if the <code>${ant.refid:}</code> is
- surrounded by other text.</p>
+ operation and <a href="#toString"><samp>${toString:}</samp></a> is
+ that <samp>${ant.refid:}</samp> will expand to the referenced
+ object itself. In most circumstances the <code>toString</code>
+ method will be invoked anyway, for example if
+ the <samp>${ant.refid:}</samp> is surrounded by other text.</p>
<p>This syntax is most useful when using a task with attribute
- setters that accept objects other than String. For example if the
- setter accepts a Resource object as in</p>
-<pre>
-public void setAttr(Resource r) { ... }
-</pre>
+ setters that accept objects other than String. For example, if
+ the setter accepts a Resource object as in</p>
+
+ <pre>public void setAttr(Resource r) { ... }</pre>
<p>then the syntax can be used to pass in resource subclasses
previously defined as references like</p>
<pre>
- <url url="http://ant.apache.org/" id="anturl"/>
- <my:task attr="${ant.refid:anturl}"/>
-</pre>
+<url url="http://ant.apache.org/" id="anturl"/>
+<my:task attr="${ant.refid:anturl}"/></pre>
<h2 id="if+unless">If/Unless Attributes</h2>
<p>
- The <code><target></code> element and various tasks (such as
- <code><fail></code>) and task elements (such as <code><test></code>
- in <code><junit></code>) support <code>if</code> and <code>unless</code>
- attributes which can be used to control whether the item is run or otherwise
- takes effect.
+ The <code><target></code> element and various tasks (such
+ as <code><fail></code>) and task elements (such
+ as <code><test></code> in <code><junit></code>)
+ support <var>if</var> and <var>unless</var> attributes which can
+ be used to control whether the item is run or otherwise takes
+ effect.
</p>
<p>
- In Ant 1.7.1 and earlier, these attributes could only be property names.
- The item was enabled if a property with that name was defined - even to be
- the empty string or <tt>false</tt> - and disabled if the property was not
- defined. For example, the following works but there is no way to override
- the file existence check negatively (only positively):
+ In Ant 1.7.1 and earlier, these attributes could only be property
+ names. The item was enabled if a property with that name was
+ defined—even to be the empty string
+ or <q>false</q>—and disabled if the property was not
+ defined. For example, the following works but there is no way to
+ override the file existence check negatively (only positively):
</p>
<pre>
-<target name="-check-use-file">
- <available property="file.exists" file="some-file"/>
-</target>
-<target name="use-file" depends="-check-use-file" <b>if="file.exists"</b>>
- <!-- do something requiring that file... -->
+<target name="-check-use-file">
+ <available property="file.exists" file="some-file"/>
+</target>
+<target name="use-file" depends="-check-use-file" <strong>if="file.exists"</strong>>
+ <!-- do something requiring that file... -->
</target>
-<target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/>
- </pre>
+<target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/></pre>
<p>
- <em>Since Ant 1.8.0</em>, you may instead use property expansion; a value of
- <tt>true</tt> (or <tt>on</tt> or <tt>yes</tt>) will enable the
- item, while <tt>false</tt> (or <tt>off</tt> or <tt>no</tt>) will
- disable it. Other values are still assumed to be property
- names and so the item is enabled only if the named property is defined.
+ <em>Since Ant 1.8.0</em>, you may instead use property expansion;
+ a value of <q>true</q> (or <q>on</q> or <q>yes</q>) will enable
+ the item, while <q>false</q> (or <q>off</q> or <q>no</q>) will
+ disable it. Other values are still assumed to be property names
+ and so the item is enabled only if the named property is defined.
</p>
<p>
- Compared to the older style, this gives you additional flexibility, because
- you can override the condition from the command line or parent scripts:
+ Compared to the older style, this gives you additional
+ flexibility, because you can override the condition from the
+ command line or parent scripts:
</p>
<pre>
-<target name="-check-use-file" <b>unless="file.exists"</b>>
- <available property="file.exists" file="some-file"/>
+<target name="-check-use-file" <strong>unless="file.exists"</strong>>
+ <available property="file.exists" file="some-file"/>
</target>
-<target name="use-file" depends="-check-use-file" <b>if="${file.exists}"</b>>
- <!-- do something requiring that file... -->
+<target name="use-file" depends="-check-use-file" <strong>if="${file.exists}"</strong>>
+ <!-- do something requiring that file... -->
</target>
-<target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/>
- </pre>
+<target name="lots-of-stuff" depends="use-file,other-unconditional-stuff"/></pre>
<p>
- Now <code>ant -Dfile.exists=false lots-of-stuff</code> will run
- <code>other-unconditional-stuff</code> but not <code>use-file</code>,
- as you might expect, and you can disable the condition from another script
- too:
+ Now <code>ant -Dfile.exists=false lots-of-stuff</code> will
+ run <q>other-unconditional-stuff</q> but not <q>use-file</q>, as
+ you might expect, and you can disable the condition from another
+ script too:
</p>
<pre>
-<antcall target="lots-of-stuff">
- <param name="file.exists" value="false"/>
-</antcall>
- </pre>
+<antcall target="lots-of-stuff">
+ <param name="file.exists" value="false"/>
+</antcall></pre>
<p>
- Similarly, an <code>unless</code> attribute disables the item if it is
- either the name of property which is defined, or if it evaluates to a
- <tt>true</tt>-like value. For example, the following allows you to define
- <tt>skip.printing.message=true</tt> in <tt>my-prefs.properties</tt> with
- the results you might expect:
+ Similarly, an <var>unless</var> attribute disables the item if it
+ is either the name of property which is defined, or if it
+ evaluates to a <q>true</q>-like value. For example, the following
+ allows you to define <code>skip.printing.message=true</code>
+ in <samp>my-prefs.properties</samp> with the results you might
+ expect:
</p>
<pre>
-<property file="my-prefs.properties"/>
-<target name="print-message" <b>unless="${skip.printing.message}"</b>>
+<property file="my-prefs.properties"/>
+<target name="print-message" <strong>unless="${skip.printing.message}"</strong>>
<echo>hello!</echo>
-</target>
- </pre>
+</target></pre>
</body>
</html>