2001-12-14 12:23:50 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2002-02-04 20:57:49 +00:00
|
|
|
<title>Listeners & Loggers</title>
|
2001-12-14 12:23:50 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<h1>Listeners & Loggers</h1>
|
|
|
|
|
|
|
|
|
|
<h2><a name="Overview">Overview</a></h2>
|
|
|
|
|
|
2002-01-31 19:56:33 +00:00
|
|
|
<p>Ant has two related features to allow the build process to be monitored:
|
2001-12-14 12:23:50 +00:00
|
|
|
listeners and loggers.</p>
|
|
|
|
|
|
|
|
|
|
<h3><a name="Listeners">Listeners</a></h3>
|
|
|
|
|
|
|
|
|
|
<p>A listener is alerted of the following events:</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li>build started</li>
|
|
|
|
|
<li>build finished</li>
|
|
|
|
|
<li>target started</li>
|
|
|
|
|
<li>target finished</li>
|
|
|
|
|
<li>task started</li>
|
|
|
|
|
<li>task finished</li>
|
|
|
|
|
<li>message logged</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3><a name="Loggers">Loggers</a></h3>
|
|
|
|
|
|
|
|
|
|
<p>Loggers extend the capabilities of listeners and add the following features:</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2002-01-31 19:56:33 +00:00
|
|
|
<li>Receives a handle to the standard output and error print streams and
|
2001-12-14 12:23:50 +00:00
|
|
|
therefore can log information to the console or the -logfile specified file.</li>
|
|
|
|
|
<li>Logging level (-quiet, -verbose, -debug) aware</li>
|
|
|
|
|
<li>Emacs-mode aware</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h2><a name="builtin">Built-in Listeners/Loggers</a></h2>
|
|
|
|
|
|
|
|
|
|
<table border="1" cellspacing="1" width="100%" id="AutoNumber1">
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="33%">Classname</td>
|
|
|
|
|
<td width="33%">Description</td>
|
|
|
|
|
<td width="34%">Type</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="33%"><code><a href="#DefaultLogger">org.apache.tools.ant.DefaultLogger</a></code></td>
|
2002-01-31 19:56:33 +00:00
|
|
|
<td width="33%">The logger used implicitly unless overridden with the
|
2001-12-14 12:23:50 +00:00
|
|
|
<code>-logger</code> command-line switch.</td>
|
|
|
|
|
<td width="34%">BuildLogger</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="33%"><code><a href="#NoBannerLogger">
|
|
|
|
|
org.apache.tools.ant.NoBannerLogger</a></code></td>
|
|
|
|
|
<td width="33%">This logger omits output of empty target output.</td>
|
|
|
|
|
<td width="34%">BuildLogger</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="33%"><code><a href="#MailLogger">
|
|
|
|
|
org.apache.tools.ant.listener.MailLogger</a></code></td>
|
2002-01-31 19:56:33 +00:00
|
|
|
<td width="33%">Extends DefaultLogger such that output is still generated
|
2001-12-14 12:23:50 +00:00
|
|
|
the same, and when the build is finished an e-mail can be sent.</td>
|
|
|
|
|
<td width="34%">BuildLogger</td>
|
|
|
|
|
</tr>
|
2002-01-31 19:56:33 +00:00
|
|
|
<tr>
|
|
|
|
|
<td width="33%"><code><a href="#AnsiColorLogger">
|
|
|
|
|
org.apache.tools.ant.listener.AnsiColorLogger</a></code></td>
|
|
|
|
|
<td width="33%">Colorifies the build output.</td>
|
|
|
|
|
<td width="34%">BuildLogger</td>
|
|
|
|
|
</tr>
|
2001-12-14 12:23:50 +00:00
|
|
|
<tr>
|
|
|
|
|
<td width="33%"><code><a href="#Log4jListener">
|
|
|
|
|
org.apache.tools.ant.listener.Log4jListener</a></code></td>
|
|
|
|
|
<td width="33%">Passes events to Log4j for highly customizable logging.</td>
|
|
|
|
|
<td width="34%">BuildListener</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="33%"><code><a href="#XmlLogger">org.apache.tools.ant.XmlLogger</a></code></td>
|
|
|
|
|
<td width="33%">Writes the build information to an XML file.</td>
|
2002-04-17 01:36:50 +00:00
|
|
|
<td width="34%">BuildLogger</td>
|
2001-12-14 12:23:50 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
<h3><a name="DefaultLogger">DefaultLogger</a></h3>
|
|
|
|
|
|
|
|
|
|
<p>Simply run Ant normally, or:</p>
|
|
|
|
|
|
|
|
|
|
<blockquote>
|
|
|
|
|
|
|
|
|
|
<p><code>ant -logger org.apache.tools.ant.DefaultLogger</code></p>
|
|
|
|
|
|
|
|
|
|
</blockquote>
|
|
|
|
|
|
|
|
|
|
<h3><a name="NoBannerLogger">NoBannerLogger</a></h3>
|
|
|
|
|
|
|
|
|
|
<p>Removes output of empty target output.</p>
|
|
|
|
|
|
|
|
|
|
<blockquote>
|
|
|
|
|
|
|
|
|
|
<p><code>ant -logger org.apache.tools.ant.NoBannerLogger</code></p>
|
|
|
|
|
|
|
|
|
|
</blockquote>
|
|
|
|
|
|
|
|
|
|
<h3><a name="MailLogger">MailLogger</a></h3>
|
|
|
|
|
|
2002-01-31 19:56:33 +00:00
|
|
|
<p>The MailLogger captures all output logged through DefaultLogger (standard Ant
|
|
|
|
|
output) and will send success and failure messages to unique e-mail lists, with
|
2001-12-14 12:23:50 +00:00
|
|
|
control for turning off success or failure messages individually.</p>
|
|
|
|
|
<p>Properties controlling the operation of MailLogger:</p>
|
|
|
|
|
<table border="1" cellspacing="1" width="100%" id="AutoNumber2">
|
|
|
|
|
<tr>
|
|
|
|
|
<th width="337">Property</th>
|
|
|
|
|
<th width="63%">Description</th>
|
|
|
|
|
<th width="63%">Required</th>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.mailhost </td>
|
|
|
|
|
<td width="63%">Mail server to use</td>
|
|
|
|
|
<td width="63%">No, default "localhost"</td>
|
|
|
|
|
</tr>
|
2002-08-08 19:05:03 +00:00
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.port </td>
|
|
|
|
|
<td width="63%">SMTP Port for the Mail server</td>
|
|
|
|
|
<td width="63%">No, default "25"</td>
|
|
|
|
|
</tr>
|
2001-12-14 12:23:50 +00:00
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.from</td>
|
|
|
|
|
<td width="63%">Mail "from" address</td>
|
|
|
|
|
<td width="63%">Yes, if mail needs to be sent</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.failure.notify </td>
|
|
|
|
|
<td width="63%">Send build failure e-mails?</td>
|
|
|
|
|
<td width="63%">No, default "true"</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.success.notify </td>
|
|
|
|
|
<td width="63%">Send build success e-mails?</td>
|
|
|
|
|
<td width="63%">No, default "true"</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.failure.to </td>
|
|
|
|
|
<td width="63%">Address(es) to send failure messages to, comma-separated</td>
|
|
|
|
|
<td width="63%">Yes, if failure mail is to be sent</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.success.to </td>
|
|
|
|
|
<td width="63%">Address(es) to send success messages to, comma-separated</td>
|
|
|
|
|
<td width="63%">Yes, if success mail is to be sent</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.failure.subject </td>
|
|
|
|
|
<td width="63%">Subject of failed build</td>
|
|
|
|
|
<td width="63%">No, default "Build Failure"</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.success.subject </td>
|
|
|
|
|
<td width="63%">Subject of successful build</td>
|
|
|
|
|
<td width="63%">No, default "Build Success"</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td width="337">MailLogger.properties.file </td>
|
|
|
|
|
<td width="63%">Filename of properties file that will override other values.</td>
|
|
|
|
|
<td width="63%">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
<blockquote>
|
|
|
|
|
|
2001-12-28 00:16:15 +00:00
|
|
|
<p><code>ant -logger org.apache.tools.ant.listener.MailLogger</code></p>
|
2001-12-14 12:23:50 +00:00
|
|
|
|
|
|
|
|
</blockquote>
|
|
|
|
|
|
2002-01-31 19:56:33 +00:00
|
|
|
<h3><a name="AnsiColorLogger">AnsiColorLogger</a></h3>
|
|
|
|
|
|
|
|
|
|
<p>The AnsiColorLogger adds color to the standard Ant output
|
|
|
|
|
by prefixing and suffixing ANSI color code escape sequences to
|
|
|
|
|
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
|
|
|
|
|
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>
|
|
|
|
|
<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 even when a COMMAND.COM 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><code><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></code>
|
|
|
|
|
<p>Each key takes as value a color combination defined as
|
|
|
|
|
<b>Attribute;Foreground;Background</b>. In the above example, background
|
|
|
|
|
value has not been used.</p>
|
|
|
|
|
<p>This file must be specfied 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>
|
|
|
|
|
AnsiColorLogger.*=Attribute;Foreground;Background
|
|
|
|
|
|
|
|
|
|
Attribute is one of the following:
|
2002-09-03 15:24:08 +00:00
|
|
|
0 -> Reset All Attributes (return to normal mode)
|
|
|
|
|
1 -> Bright (Usually turns on BOLD)
|
|
|
|
|
2 -> Dim
|
|
|
|
|
3 -> Underline
|
|
|
|
|
5 -> link
|
|
|
|
|
7 -> Reverse
|
|
|
|
|
8 -> Hidden
|
2002-01-31 19:56:33 +00:00
|
|
|
|
|
|
|
|
Foreground is one of the following:
|
2002-09-03 15:24:08 +00:00
|
|
|
30 -> Black
|
|
|
|
|
31 -> Red
|
|
|
|
|
32 -> Green
|
|
|
|
|
33 -> Yellow
|
|
|
|
|
34 -> Blue
|
|
|
|
|
35 -> Magenta
|
|
|
|
|
36 -> Cyan
|
|
|
|
|
37 -> White
|
2002-01-31 19:56:33 +00:00
|
|
|
|
|
|
|
|
Background is one of the following:
|
2002-09-03 15:24:08 +00:00
|
|
|
40 -> Black
|
|
|
|
|
41 -> Red
|
|
|
|
|
42 -> Green
|
|
|
|
|
43 -> Yellow
|
|
|
|
|
44 -> Blue
|
|
|
|
|
45 -> Magenta
|
|
|
|
|
46 -> Cyan
|
|
|
|
|
47 -> White</pre>
|
2002-01-31 19:56:33 +00:00
|
|
|
|
|
|
|
|
<blockquote>
|
|
|
|
|
|
|
|
|
|
<p><code>ant -logger org.apache.tools.ant.listener.AnsiColorLogger</code></p>
|
|
|
|
|
|
|
|
|
|
</blockquote>
|
|
|
|
|
|
2001-12-14 12:23:50 +00:00
|
|
|
<h3><a name="Log4jListener">Log4jListener</a></h3>
|
|
|
|
|
|
2002-01-31 19:56:33 +00:00
|
|
|
<p>Passes build events to Log4j, using the full classname's of the generator of
|
2001-12-14 12:23:50 +00:00
|
|
|
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>
|
2002-01-31 19:56:33 +00:00
|
|
|
<li>message logged - the classname of one of the above, so if a task logs a
|
2001-12-14 12:23:50 +00:00
|
|
|
message, its classname is the category used, and so on.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
2002-01-31 19:56:33 +00:00
|
|
|
<p>All start events are logged as INFO. Finish events are either logged as
|
|
|
|
|
INFO or ERROR depending on whether the build failed during that stage. Message
|
|
|
|
|
events are logged according to their Ant logging level, mapping directly to a
|
2001-12-14 12:23:50 +00:00
|
|
|
corresponding Log4j level.</p>
|
|
|
|
|
|
|
|
|
|
<blockquote>
|
|
|
|
|
|
|
|
|
|
<p><code>ant -listener org.apache.tools.ant.listener.Log4jListener</code></p>
|
|
|
|
|
|
|
|
|
|
</blockquote>
|
|
|
|
|
|
|
|
|
|
<h3><a name="XmlLogger">XmlLogger</a></h3>
|
|
|
|
|
|
2002-01-31 19:56:33 +00:00
|
|
|
<p>Writes all build information out to an XML file named log.xml, or the value
|
2002-04-17 01:36:50 +00:00
|
|
|
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.
|
2002-03-23 19:52:30 +00:00
|
|
|
<p>
|
2002-08-08 19:05:03 +00:00
|
|
|
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
|
2002-03-23 19:52:30 +00:00
|
|
|
<code>ant.XmlLogger.stylesheet.uri</code> to provide a uri to a style sheet.
|
2002-08-08 19:05:03 +00:00
|
|
|
this can be a relative or absolute file path, or an http URL.
|
2002-03-23 19:52:30 +00:00
|
|
|
If you set the property to the empty string, "", no XSLT transform
|
2002-08-08 19:05:03 +00:00
|
|
|
is declared at all.
|
|
|
|
|
|
2002-03-23 19:52:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</p>
|
2001-12-14 12:23:50 +00:00
|
|
|
|
|
|
|
|
<blockquote>
|
|
|
|
|
|
2002-04-17 01:36:50 +00:00
|
|
|
<p><code>ant -listener org.apache.tools.ant.XmlLogger</code><br/>
|
|
|
|
|
<code>ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml</code></p>
|
2001-12-14 12:23:50 +00:00
|
|
|
|
|
|
|
|
</blockquote>
|
|
|
|
|
|
|
|
|
|
<h2><a name="dev">Writing your own</a></h2>
|
|
|
|
|
|
2002-01-31 19:56:33 +00:00
|
|
|
<p>See the <a href="develop.html#buildevents">Build Events</a> section for
|
2001-12-14 12:23:50 +00:00
|
|
|
developers.</p>
|
|
|
|
|
|
|
|
|
|
<p>Notes:</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2002-01-31 19:56:33 +00:00
|
|
|
<li>A listener or logger should not write to standard output or error - Ant
|
2001-12-14 12:23:50 +00:00
|
|
|
captures these internally and may cause an infinite loop.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<hr>
|
2002-06-01 12:26:43 +00:00
|
|
|
<p align="center">Copyright © 2000-2002 Apache Software Foundation. All rights
|
2001-12-14 12:23:50 +00:00
|
|
|
Reserved.</p>
|
|
|
|
|
|
|
|
|
|
</body>
|
2001-12-28 00:16:15 +00:00
|
|
|
</html>
|
