source: release-kits/lirk3/bin/ant-installer/web/manual1.6.2/manual/listeners.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 11.3 KB
Line 
1<html>
2
3<head>
4<meta http-equiv="Content-Language" content="en-us">
5<title>Listeners &amp; Loggers</title>
6<link rel="stylesheet" type="text/css" href="stylesheets/antmanual.css">
7</head>
8
9<body>
10<h1>Listeners &amp; Loggers</h1>
11
12<h2><a name="Overview">Overview</a></h2>
13
14<p>Ant has two related features to allow the build process to be monitored:
15listeners and loggers.</p>
16
17<h3><a name="Listeners">Listeners</a></h3>
18
19<p>A listener is alerted of the following events:</p>
20
21<ul>
22 <li>build started</li>
23 <li>build finished</li>
24 <li>target started</li>
25 <li>target finished</li>
26 <li>task started</li>
27 <li>task finished</li>
28 <li>message logged</li>
29</ul>
30
31<h3><a name="Loggers">Loggers</a></h3>
32
33<p>Loggers extend the capabilities of listeners and add the following features:</p>
34
35<ul>
36 <li>Receives a handle to the standard output and error print streams and
37 therefore can log information to the console or the -logfile specified file.</li>
38 <li>Logging level (-quiet, -verbose, -debug) aware</li>
39 <li>Emacs-mode aware</li>
40</ul>
41
42<h2><a name="builtin">Built-in Listeners/Loggers</a></h2>
43
44<table border="1" cellspacing="1" width="100%" id="AutoNumber1">
45 <tr>
46 <td width="33%">Classname</td>
47 <td width="33%">Description</td>
48 <td width="34%">Type</td>
49 </tr>
50 <tr>
51 <td width="33%"><code><a href="#DefaultLogger">org.apache.tools.ant.DefaultLogger</a></code></td>
52 <td width="33%">The logger used implicitly unless overridden with the
53 <code>-logger</code> command-line switch.</td>
54 <td width="34%">BuildLogger</td>
55 </tr>
56 <tr>
57 <td width="33%"><code><a href="#NoBannerLogger">
58 org.apache.tools.ant.NoBannerLogger</a></code></td>
59 <td width="33%">This logger omits output of empty target output.</td>
60 <td width="34%">BuildLogger</td>
61 </tr>
62 <tr>
63 <td width="33%"><code><a href="#MailLogger">
64 org.apache.tools.ant.listener.MailLogger</a></code></td>
65 <td width="33%">Extends DefaultLogger such that output is still generated
66 the same, and when the build is finished an e-mail can be sent.</td>
67 <td width="34%">BuildLogger</td>
68 </tr>
69 <tr>
70 <td width="33%"><code><a href="#AnsiColorLogger">
71 org.apache.tools.ant.listener.AnsiColorLogger</a></code></td>
72 <td width="33%">Colorifies the build output.</td>
73 <td width="34%">BuildLogger</td>
74 </tr>
75 <tr>
76 <td width="33%"><code><a href="#Log4jListener">
77 org.apache.tools.ant.listener.Log4jListener</a></code></td>
78 <td width="33%">Passes events to Log4j for highly customizable logging.</td>
79 <td width="34%">BuildListener</td>
80 </tr>
81 <tr>
82 <td width="33%"><code><a href="#XmlLogger">org.apache.tools.ant.XmlLogger</a></code></td>
83 <td width="33%">Writes the build information to an XML file.</td>
84 <td width="34%">BuildLogger</td>
85 </tr>
86</table>
87<h3><a name="DefaultLogger">DefaultLogger</a></h3>
88
89<p>Simply run Ant normally, or:</p>
90
91<blockquote>
92
93<p><code>ant -logger org.apache.tools.ant.DefaultLogger</code></p>
94
95</blockquote>
96
97<h3><a name="NoBannerLogger">NoBannerLogger</a></h3>
98
99<p>Removes output of empty target output.</p>
100
101<blockquote>
102
103<p><code>ant -logger org.apache.tools.ant.NoBannerLogger</code></p>
104
105</blockquote>
106
107<h3><a name="MailLogger">MailLogger</a></h3>
108
109<p>The MailLogger captures all output logged through DefaultLogger (standard Ant
110output) and will send success and failure messages to unique e-mail lists, with
111control for turning off success or failure messages individually.</p>
112<p>Properties controlling the operation of MailLogger:</p>
113<table border="1" cellspacing="1" width="100%" id="AutoNumber2">
114 <tr>
115 <th width="337">Property</th>
116 <th width="63%">Description</th>
117 <th width="63%">Required</th>
118 </tr>
119 <tr>
120 <td width="337">MailLogger.mailhost </td>
121 <td width="63%">Mail server to use</td>
122 <td width="63%">No, default &quot;localhost&quot;</td>
123 </tr>
124 <tr>
125 <td width="337">MailLogger.port </td>
126 <td width="63%">SMTP Port for the Mail server</td>
127 <td width="63%">No, default &quot;25&quot;</td>
128 </tr>
129 <tr>
130 <td width="337">MailLogger.user</td>
131 <td width="63%">user name for SMTP auth</td>
132 <td width="63%">Yes, if SMTP auth is required on your SMTP server<br/>
133 the email message will be then sent using Mime and requires JavaMail</td>
134 </tr>
135 <tr>
136 <td width="337">MailLogger.password</td>
137 <td width="63%">password for SMTP auth</td>
138 <td width="63%">Yes, if SMTP auth is required on your SMTP server<br/>
139 the email message will be then sent using Mime and requires JavaMail</td>
140 </tr>
141 <tr>
142 <td width="337">MailLogger.ssl</td>
143 <td width="63%">on or true if ssl is needed<br/>
144 This feature requires JavaMail</td>
145 <td width="63%">
146 no</td>
147 </tr>
148 <tr>
149 <td width="337">MailLogger.from</td>
150 <td width="63%">Mail &quot;from&quot; address</td>
151 <td width="63%">Yes, if mail needs to be sent</td>
152 </tr>
153 <tr>
154 <td width="337">MailLogger.replyto</td>
155 <td width="63%">Mail &quot;replyto&quot; address(es), comma-separated</td>
156 <td width="63%">No</td>
157 </tr>
158 <tr>
159 <td width="337">MailLogger.failure.notify </td>
160 <td width="63%">Send build failure e-mails?</td>
161 <td width="63%">No, default &quot;true&quot;</td>
162 </tr>
163 <tr>
164 <td width="337">MailLogger.success.notify </td>
165 <td width="63%">Send build success e-mails?</td>
166 <td width="63%">No, default &quot;true&quot;</td>
167 </tr>
168 <tr>
169 <td width="337">MailLogger.failure.to </td>
170 <td width="63%">Address(es) to send failure messages to, comma-separated</td>
171 <td width="63%">Yes, if failure mail is to be sent</td>
172 </tr>
173 <tr>
174 <td width="337">MailLogger.success.to </td>
175 <td width="63%">Address(es) to send success messages to, comma-separated</td>
176 <td width="63%">Yes, if success mail is to be sent</td>
177 </tr>
178 <tr>
179 <td width="337">MailLogger.failure.subject </td>
180 <td width="63%">Subject of failed build</td>
181 <td width="63%">No, default &quot;Build Failure&quot;</td>
182 </tr>
183 <tr>
184 <td width="337">MailLogger.success.subject </td>
185 <td width="63%">Subject of successful build</td>
186 <td width="63%">No, default &quot;Build Success&quot;</td>
187 </tr>
188 <tr>
189 <td width="337">MailLogger.properties.file </td>
190 <td width="63%">Filename of properties file that will override other values.</td>
191 <td width="63%">No</td>
192 </tr>
193</table>
194<blockquote>
195
196<p><code>ant -logger org.apache.tools.ant.listener.MailLogger</code></p>
197
198</blockquote>
199
200<h3><a name="AnsiColorLogger">AnsiColorLogger</a></h3>
201
202<p>The AnsiColorLogger adds color to the standard Ant output
203by prefixing and suffixing ANSI color code escape sequences to
204it. It is just an extension of <a href="#DefaultLogger">DefaultLogger</a>
205and hence provides all features that DefaultLogger does.</p>
206<p>AnsiColorLogger differentiates the output by assigning
207different colors depending upon the type of the message.</p>
208<p>If used with the -logfile option, the output file
209will contain all the necessary escape codes to
210display the text in colorized mode when displayed
211in the console using applications like cat, more, etc.</p>
212<p>This is designed to work on terminals that support ANSI
213color codes. It works on XTerm, ETerm, Win9x Console
214(with ANSI.SYS loaded.), etc.</p>
215<p><Strong>NOTE:</Strong>
216It doesn't work on WinNT even when a COMMAND.COM console loaded with
217ANSI.SYS is used.</p>
218<p>If the user wishes to override the default colors
219with custom ones, a file containing zero or more of the
220custom color key-value pairs must be created. The recognized keys
221and their default values are shown below:</p><code><pre>
222AnsiColorLogger.ERROR_COLOR=2;31
223AnsiColorLogger.WARNING_COLOR=2;35
224AnsiColorLogger.INFO_COLOR=2;36
225AnsiColorLogger.VERBOSE_COLOR=2;32
226AnsiColorLogger.DEBUG_COLOR=2;34</pre></code>
227<p>Each key takes as value a color combination defined as
228<b>Attribute;Foreground;Background</b>. In the above example, background
229value has not been used.</p>
230<p>This file must be specfied as the value of a system variable
231named ant.logger.defaults and passed as an argument using the -D
232option to the <b>java</b> command that invokes the Ant application.
233An easy way to achieve this is to add -Dant.logger.defaults=
234<i>/path/to/your/file</i> to the ANT_OPTS environment variable.
235Ant's launching script recognizes this flag and will pass it to
236the java command appropriately.</p>
237<p>Format:</p><pre>
238AnsiColorLogger.*=Attribute;Foreground;Background
239
240Attribute is one of the following:
2410 -&gt; Reset All Attributes (return to normal mode)
2421 -&gt; Bright (Usually turns on BOLD)
2432 -&gt; Dim
2443 -&gt; Underline
2455 -&gt; link
2467 -&gt; Reverse
2478 -&gt; Hidden
248
249Foreground is one of the following:
25030 -&gt; Black
25131 -&gt; Red
25232 -&gt; Green
25333 -&gt; Yellow
25434 -&gt; Blue
25535 -&gt; Magenta
25636 -&gt; Cyan
25737 -&gt; White
258
259Background is one of the following:
26040 -&gt; Black
26141 -&gt; Red
26242 -&gt; Green
26343 -&gt; Yellow
26444 -&gt; Blue
26545 -&gt; Magenta
26646 -&gt; Cyan
26747 -&gt; White</pre>
268
269<blockquote>
270
271<p><code>ant -logger org.apache.tools.ant.listener.AnsiColorLogger</code></p>
272
273</blockquote>
274
275<h3><a name="Log4jListener">Log4jListener</a></h3>
276
277<p>Passes build events to Log4j, using the full classname's of the generator of
278each build event as the category:</p>
279
280<ul>
281 <li>build started / build finished - org.apache.tools.ant.Project</li>
282 <li>target started / target finished - org.apache.tools.ant.Target</li>
283 <li>task started / task finished - the fully qualified classname of the task</li>
284 <li>message logged - the classname of one of the above, so if a task logs a
285 message, its classname is the category used, and so on.</li>
286</ul>
287
288<p>All start events are logged as INFO.&nbsp; Finish events are either logged as
289INFO or ERROR depending on whether the build failed during that stage. Message
290events are logged according to their Ant logging level, mapping directly to a
291corresponding Log4j level.</p>
292
293<blockquote>
294
295<p><code>ant -listener org.apache.tools.ant.listener.Log4jListener</code></p>
296
297</blockquote>
298
299<h3><a name="XmlLogger">XmlLogger</a></h3>
300
301<p>Writes all build information out to an XML file named log.xml, or the value
302of the <code>XmlLogger.file</code> property if present, when used as a
303listener. When used as a logger, it writes all output to either the
304console or to the value of <code>-logfile</code>. Whether used as a listener
305or logger, the output is not generated until the build is complete, as it
306buffers the information in order to provide timing information for task,
307targets, and the project.
308<p>
309By default the XML file creates
310a reference to an XSLT file "log.xsl" in the current directory; look in
311ANT_HOME/etc for one of these. You can set the property
312<code>ant.XmlLogger.stylesheet.uri</code> to provide a uri to a style sheet.
313this can be a relative or absolute file path, or an http URL.
314If you set the property to the empty string, "", no XSLT transform
315is declared at all.
316
317
318
319
320</p>
321
322<blockquote>
323
324<p><code>ant -listener org.apache.tools.ant.XmlLogger</code><br/>
325<code>ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml</code></p>
326
327</blockquote>
328
329<h2><a name="dev">Writing your own</a></h2>
330
331<p>See the <a href="develop.html#buildevents">Build Events</a> section for
332developers.</p>
333
334<p>Notes:</p>
335
336<ul>
337 <li>A listener or logger should not write to standard output or error - Ant
338 captures these internally and may cause an infinite loop.</li>
339</ul>
340
341<hr>
342<p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
343Reserved.</p>
344
345</body>
346</html>
Note: See TracBrowser for help on using the repository browser.