| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Listeners & Loggers</title> |
| </head> |
| |
| <body> |
| <h1>Listeners & Loggers</h1> |
| |
| <h2><a name="Overview">Overview</a></h2> |
| |
| <p>Ant has two related features to allow the build process to be monitored: |
| 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> |
| <li>Receives a handle to the standard output and error print streams and |
| 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> |
| <td width="33%">The logger used implicitly unless overridden with the |
| <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> |
| <td width="33%">Extends DefaultLogger such that output is still generated |
| the same, and when the build is finished an e-mail can be sent.</td> |
| <td width="34%">BuildLogger</td> |
| </tr> |
| <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> |
| <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> |
| <td width="34%">BuildListener</td> |
| </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> |
| |
| <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 |
| 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> |
| <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> |
| |
| <p><code>ant -logger org.apache.tools.ant.listener.MailLogger</code></p> |
| |
| </blockquote> |
| |
| <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: |
| 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 |
| |
| Background is one of the following: |
| 40 -> Black |
| 41 -> Red |
| 42 -> Green |
| 43 -> Yellow |
| 44 -> Blue |
| 45 -> Magenta |
| 46 -> Cyan |
| 47 -> White</pre> |
| |
| <blockquote> |
| |
| <p><code>ant -logger org.apache.tools.ant.listener.AnsiColorLogger</code></p> |
| |
| </blockquote> |
| |
| <h3><a name="Log4jListener">Log4jListener</a></h3> |
| |
| <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 |
| 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 |
| 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 |
| 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> |
| |
| <p>Writes all build information out to an XML file named log.xml, or the value |
| of the XmlLogger.file property if present.</p> |
| |
| <blockquote> |
| |
| <p><code>ant -listener org.apache.tools.ant.XmlLogger</code></p> |
| |
| </blockquote> |
| |
| <h2><a name="dev">Writing your own</a></h2> |
| |
| <p>See the <a href="develop.html#buildevents">Build Events</a> section for |
| developers.</p> |
| |
| <p>Notes:</p> |
| |
| <ul> |
| <li>A listener or logger should not write to standard output or error - Ant |
| captures these internally and may cause an infinite loop.</li> |
| </ul> |
| |
| <hr> |
| <p align="center">Copyright © 2001-2002 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
