source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual1.7.0/manual/listeners.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 13.7 KB
Line 
1<!--
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
22<title>Listeners &amp; Loggers</title>
23</head>
24
25<body>
26<h1>Listeners &amp; Loggers</h1>
27
28<h2><a name="Overview">Overview</a></h2>
29
30<p>Ant has two related features to allow the build process to be monitored:
31listeners and loggers.</p>
32
33<h3><a name="Listeners">Listeners</a></h3>
34
35<p>A listener is alerted of the following events:</p>
36
37<ul>
38 <li>build started</li>
39 <li>build finished</li>
40 <li>target started</li>
41 <li>target finished</li>
42 <li>task started</li>
43 <li>task finished</li>
44 <li>message logged</li>
45</ul>
46
47<h3><a name="Loggers">Loggers</a></h3>
48
49<p>Loggers extend the capabilities of listeners and add the following features:</p>
50
51<ul>
52 <li>Receives a handle to the standard output and error print streams and
53 therefore can log information to the console or the -logfile specified file.</li>
54 <li>Logging level (-quiet, -verbose, -debug) aware</li>
55 <li>Emacs-mode aware</li>
56</ul>
57
58<h2><a name="builtin">Built-in Listeners/Loggers</a></h2>
59
60<table border="1" cellspacing="1" width="100%" id="AutoNumber1">
61 <tr>
62 <td width="33%">Classname</td>
63 <td width="33%">Description</td>
64 <td width="34%">Type</td>
65 </tr>
66 <tr>
67 <td width="33%"><code><a href="#DefaultLogger">org.apache.tools.ant.DefaultLogger</a></code></td>
68 <td width="33%">The logger used implicitly unless overridden with the
69 <code>-logger</code> command-line switch.</td>
70 <td width="34%">BuildLogger</td>
71 </tr>
72 <tr>
73 <td width="33%"><code><a href="#NoBannerLogger">
74 org.apache.tools.ant.NoBannerLogger</a></code></td>
75 <td width="33%">This logger omits output of empty target output.</td>
76 <td width="34%">BuildLogger</td>
77 </tr>
78 <tr>
79 <td width="33%"><code><a href="#MailLogger">
80 org.apache.tools.ant.listener.MailLogger</a></code></td>
81 <td width="33%">Extends DefaultLogger such that output is still generated
82 the same, and when the build is finished an e-mail can be sent.</td>
83 <td width="34%">BuildLogger</td>
84 </tr>
85 <tr>
86 <td width="33%"><code><a href="#AnsiColorLogger">
87 org.apache.tools.ant.listener.AnsiColorLogger</a></code></td>
88 <td width="33%">Colorifies the build output.</td>
89 <td width="34%">BuildLogger</td>
90 </tr>
91 <tr>
92 <td width="33%"><code><a href="#Log4jListener">
93 org.apache.tools.ant.listener.Log4jListener</a></code></td>
94 <td width="33%">Passes events to Log4j for highly customizable logging.</td>
95 <td width="34%">BuildListener</td>
96 </tr>
97 <tr>
98 <td width="33%"><code><a href="#XmlLogger">org.apache.tools.ant.XmlLogger</a></code></td>
99 <td width="33%">Writes the build information to an XML file.</td>
100 <td width="34%">BuildLogger</td>
101 </tr>
102 <tr>
103 <td width="33%"><code><a href="#TimestampedLogger">org.apache.tools.ant.TimestampedLogger</a></code></td>
104 <td width="33%">Prints the time that a build finished</td>
105 <td width="34%">BuildLogger</td>
106 </tr>
107
108</table>
109<h3><a name="DefaultLogger">DefaultLogger</a></h3>
110
111<p>Simply run Ant normally, or:</p>
112
113<blockquote>
114
115<p><code>ant -logger org.apache.tools.ant.DefaultLogger</code></p>
116
117</blockquote>
118
119<h3><a name="NoBannerLogger">NoBannerLogger</a></h3>
120
121<p>Removes output of empty target output.</p>
122
123<blockquote>
124
125<p><code>ant -logger org.apache.tools.ant.NoBannerLogger</code></p>
126
127</blockquote>
128
129<h3><a name="MailLogger">MailLogger</a></h3>
130
131<p>The MailLogger captures all output logged through DefaultLogger (standard Ant
132output) and will send success and failure messages to unique e-mail lists, with
133control for turning off success or failure messages individually.</p>
134<p>Properties controlling the operation of MailLogger:</p>
135<table border="1" cellspacing="1" width="100%" id="AutoNumber2">
136 <tr>
137 <th width="337">Property</th>
138 <th width="63%">Description</th>
139 <th width="63%">Required</th>
140 </tr>
141 <tr>
142 <td width="337">MailLogger.mailhost </td>
143 <td width="63%">Mail server to use</td>
144 <td width="63%">No, default &quot;localhost&quot;</td>
145 </tr>
146 <tr>
147 <td width="337">MailLogger.port </td>
148 <td width="63%">SMTP Port for the Mail server</td>
149 <td width="63%">No, default &quot;25&quot;</td>
150 </tr>
151 <tr>
152 <td width="337">MailLogger.user</td>
153 <td width="63%">user name for SMTP auth</td>
154 <td width="63%">Yes, if SMTP auth is required on your SMTP server<br>
155 the email message will be then sent using Mime and requires JavaMail</td>
156 </tr>
157 <tr>
158 <td width="337">MailLogger.password</td>
159 <td width="63%">password for SMTP auth</td>
160 <td width="63%">Yes, if SMTP auth is required on your SMTP server<br>
161 the email message will be then sent using Mime and requires JavaMail</td>
162 </tr>
163 <tr>
164 <td width="337">MailLogger.ssl</td>
165 <td width="63%">on or true if ssl is needed<br>
166 This feature requires JavaMail</td>
167 <td width="63%">
168 no</td>
169 </tr>
170 <tr>
171 <td width="337">MailLogger.from</td>
172 <td width="63%">Mail &quot;from&quot; address</td>
173 <td width="63%">Yes, if mail needs to be sent</td>
174 </tr>
175 <tr>
176 <td width="337">MailLogger.replyto</td>
177 <td width="63%">Mail &quot;replyto&quot; address(es), comma-separated</td>
178 <td width="63%">No</td>
179 </tr>
180 <tr>
181 <td width="337">MailLogger.failure.notify </td>
182 <td width="63%">Send build failure e-mails?</td>
183 <td width="63%">No, default &quot;true&quot;</td>
184 </tr>
185 <tr>
186 <td width="337">MailLogger.success.notify </td>
187 <td width="63%">Send build success e-mails?</td>
188 <td width="63%">No, default &quot;true&quot;</td>
189 </tr>
190 <tr>
191 <td width="337">MailLogger.failure.to </td>
192 <td width="63%">Address(es) to send failure messages to, comma-separated</td>
193 <td width="63%">Yes, if failure mail is to be sent</td>
194 </tr>
195 <tr>
196 <td width="337">MailLogger.success.to </td>
197 <td width="63%">Address(es) to send success messages to, comma-separated</td>
198 <td width="63%">Yes, if success mail is to be sent</td>
199 </tr>
200 <tr>
201 <td width="337">MailLogger.failure.subject </td>
202 <td width="63%">Subject of failed build</td>
203 <td width="63%">No, default &quot;Build Failure&quot;</td>
204 </tr>
205 <tr>
206 <td width="337">MailLogger.success.subject </td>
207 <td width="63%">Subject of successful build</td>
208 <td width="63%">No, default &quot;Build Success&quot;</td>
209 </tr>
210 <tr>
211 <td width="337">MailLogger.properties.file </td>
212 <td width="63%">Filename of properties file that will override other values.</td>
213 <td width="63%">No</td>
214 </tr>
215</table>
216<blockquote>
217
218<p><code>ant -logger org.apache.tools.ant.listener.MailLogger</code></p>
219
220</blockquote>
221
222<h3><a name="AnsiColorLogger">AnsiColorLogger</a></h3>
223
224<p>The AnsiColorLogger adds color to the standard Ant output
225by prefixing and suffixing ANSI color code escape sequences to
226it. It is just an extension of <a href="#DefaultLogger">DefaultLogger</a>
227and hence provides all features that DefaultLogger does.</p>
228<p>AnsiColorLogger differentiates the output by assigning
229different colors depending upon the type of the message.</p>
230<p>If used with the -logfile option, the output file
231will contain all the necessary escape codes to
232display the text in colorized mode when displayed
233in the console using applications like cat, more, etc.</p>
234<p>This is designed to work on terminals that support ANSI
235color codes. It works on XTerm, ETerm, Win9x Console
236(with ANSI.SYS loaded.), etc.</p>
237<p><Strong>NOTE:</Strong>
238It doesn't work on WinNT even when a COMMAND.COM console loaded with
239ANSI.SYS is used.</p>
240<p>If the user wishes to override the default colors
241with custom ones, a file containing zero or more of the
242custom color key-value pairs must be created. The recognized keys
243and their default values are shown below:</p><code><pre>
244AnsiColorLogger.ERROR_COLOR=2;31
245AnsiColorLogger.WARNING_COLOR=2;35
246AnsiColorLogger.INFO_COLOR=2;36
247AnsiColorLogger.VERBOSE_COLOR=2;32
248AnsiColorLogger.DEBUG_COLOR=2;34</pre></code>
249<p>Each key takes as value a color combination defined as
250<b>Attribute;Foreground;Background</b>. In the above example, background
251value has not been used.</p>
252<p>This file must be specfied as the value of a system variable
253named ant.logger.defaults and passed as an argument using the -D
254option to the <b>java</b> command that invokes the Ant application.
255An easy way to achieve this is to add -Dant.logger.defaults=
256<i>/path/to/your/file</i> to the ANT_OPTS environment variable.
257Ant's launching script recognizes this flag and will pass it to
258the java command appropriately.</p>
259<p>Format:</p><pre>
260AnsiColorLogger.*=Attribute;Foreground;Background
261
262Attribute is one of the following:
2630 -&gt; Reset All Attributes (return to normal mode)
2641 -&gt; Bright (Usually turns on BOLD)
2652 -&gt; Dim
2663 -&gt; Underline
2675 -&gt; link
2687 -&gt; Reverse
2698 -&gt; Hidden
270
271Foreground is one of the following:
27230 -&gt; Black
27331 -&gt; Red
27432 -&gt; Green
27533 -&gt; Yellow
27634 -&gt; Blue
27735 -&gt; Magenta
27836 -&gt; Cyan
27937 -&gt; White
280
281Background is one of the following:
28240 -&gt; Black
28341 -&gt; Red
28442 -&gt; Green
28543 -&gt; Yellow
28644 -&gt; Blue
28745 -&gt; Magenta
28846 -&gt; Cyan
28947 -&gt; White</pre>
290
291<blockquote>
292
293<p><code>ant -logger org.apache.tools.ant.listener.AnsiColorLogger</code></p>
294
295</blockquote>
296
297<h3><a name="Log4jListener">Log4jListener</a></h3>
298
299<p>Passes build events to Log4j, using the full classname's of the generator of
300each build event as the category:</p>
301
302<ul>
303 <li>build started / build finished - org.apache.tools.ant.Project</li>
304 <li>target started / target finished - org.apache.tools.ant.Target</li>
305 <li>task started / task finished - the fully qualified classname of the task</li>
306 <li>message logged - the classname of one of the above, so if a task logs a
307 message, its classname is the category used, and so on.</li>
308</ul>
309
310<p>All start events are logged as INFO.&nbsp; Finish events are either logged as
311INFO or ERROR depending on whether the build failed during that stage. Message
312events are logged according to their Ant logging level, mapping directly to a
313corresponding Log4j level.</p>
314
315<blockquote>
316
317<p><code>ant -listener org.apache.tools.ant.listener.Log4jListener</code></p>
318
319</blockquote>
320
321<p>To use Log4j you will need the Log4j jar file and a 'log4j.properties'
322configuration file. Both should be placed somewhere in your Ant
323classpath. If the log4j.properties is in your project root folder you can
324add this with <i>-lib</i> option:</p>
325
326<blockquote>
327<pre><code>ant -listener org.apache.tools.ant.listener.Log4jListener -lib .</code></pre>
328</blockquote>
329
330<p>If, for example, you wanted to capture the same information output to the
331console by the DefaultLogger and send it to a file named 'build.log', you
332could use the following configuration:</p>
333
334<blockquote>
335
336<pre><code>log4j.rootLogger=ERROR, LogFile
337log4j.logger.org.apache.tools.ant.Project=INFO
338log4j.logger.org.apache.tools.ant.Target=INFO
339log4j.logger.org.apache.tools.ant.taskdefs=INFO
340log4j.logger.org.apache.tools.ant.taskdefs.Echo=WARN
341
342log4j.appender.LogFile=org.apache.log4j.FileAppender
343log4j.appender.LogFile.layout=org.apache.log4j.PatternLayout
344log4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%n
345log4j.appender.LogFile.file=build.log
346</code></pre>
347
348</blockquote>
349
350<p>For more information about configuring Log4J see <a href="http://logging.apache.org/log4j/docs/documentation.html">its
351documentation page</a>.</p>
352
353<h3><a name="XmlLogger">XmlLogger</a></h3>
354
355<p>Writes all build information out to an XML file named log.xml, or the value
356of the <code>XmlLogger.file</code> property if present, when used as a
357listener. When used as a logger, it writes all output to either the
358console or to the value of <code>-logfile</code>. Whether used as a listener
359or logger, the output is not generated until the build is complete, as it
360buffers the information in order to provide timing information for task,
361targets, and the project.
362<p>
363By default the XML file creates
364a reference to an XSLT file "log.xsl" in the current directory; look in
365ANT_HOME/etc for one of these. You can set the property
366<code>ant.XmlLogger.stylesheet.uri</code> to provide a uri to a style sheet.
367this can be a relative or absolute file path, or an http URL.
368If you set the property to the empty string, "", no XSLT transform
369is declared at all.
370</p>
371
372<blockquote>
373
374<p><code>ant -listener org.apache.tools.ant.XmlLogger</code><br>
375<code>ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml</code></p>
376
377</blockquote>
378
379
380<h3><a name="TimestampedLogger">TimestampedLogger</a></h3>
381
382<p>
383 Acts like the default logger, except that the final success/failure message also includes
384 the time that the build completed. For example:
385</p>
386<pre>
387 BUILD SUCCESSFUL - at 16/08/05 16:24
388</pre>
389
390<blockquote>
391
392<code>ant -logger org.apache.tools.ant.listener.TimestampedLogger</code>
393
394</blockquote>
395
396
397<h2><a name="dev">Writing your own</a></h2>
398
399<p>See the <a href="develop.html#buildevents">Build Events</a> section for
400developers.</p>
401
402<p>Notes:</p>
403
404<ul>
405 <li>A listener or logger should not write to standard output or error; Ant
406 captures these internally and may cause an infinite loop.</li>
407</ul>
408
409
410
411</body>
412</html>
Note: See TracBrowser for help on using the repository browser.