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 & Loggers</title>
|
---|
23 | </head>
|
---|
24 |
|
---|
25 | <body>
|
---|
26 | <h1>Listeners & 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:
|
---|
31 | listeners 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
|
---|
132 | output) and will send success and failure messages to unique e-mail lists, with
|
---|
133 | control 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 "localhost"</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 "25"</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 "from" 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 "replyto" 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 "true"</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 "true"</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 "Build Failure"</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 "Build Success"</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
|
---|
225 | by prefixing and suffixing ANSI color code escape sequences to
|
---|
226 | it. It is just an extension of <a href="#DefaultLogger">DefaultLogger</a>
|
---|
227 | and hence provides all features that DefaultLogger does.</p>
|
---|
228 | <p>AnsiColorLogger differentiates the output by assigning
|
---|
229 | different colors depending upon the type of the message.</p>
|
---|
230 | <p>If used with the -logfile option, the output file
|
---|
231 | will contain all the necessary escape codes to
|
---|
232 | display the text in colorized mode when displayed
|
---|
233 | in the console using applications like cat, more, etc.</p>
|
---|
234 | <p>This is designed to work on terminals that support ANSI
|
---|
235 | color codes. It works on XTerm, ETerm, Win9x Console
|
---|
236 | (with ANSI.SYS loaded.), etc.</p>
|
---|
237 | <p><Strong>NOTE:</Strong>
|
---|
238 | It doesn't work on WinNT even when a COMMAND.COM console loaded with
|
---|
239 | ANSI.SYS is used.</p>
|
---|
240 | <p>If the user wishes to override the default colors
|
---|
241 | with custom ones, a file containing zero or more of the
|
---|
242 | custom color key-value pairs must be created. The recognized keys
|
---|
243 | and their default values are shown below:</p><code><pre>
|
---|
244 | AnsiColorLogger.ERROR_COLOR=2;31
|
---|
245 | AnsiColorLogger.WARNING_COLOR=2;35
|
---|
246 | AnsiColorLogger.INFO_COLOR=2;36
|
---|
247 | AnsiColorLogger.VERBOSE_COLOR=2;32
|
---|
248 | AnsiColorLogger.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
|
---|
251 | value has not been used.</p>
|
---|
252 | <p>This file must be specfied as the value of a system variable
|
---|
253 | named ant.logger.defaults and passed as an argument using the -D
|
---|
254 | option to the <b>java</b> command that invokes the Ant application.
|
---|
255 | An easy way to achieve this is to add -Dant.logger.defaults=
|
---|
256 | <i>/path/to/your/file</i> to the ANT_OPTS environment variable.
|
---|
257 | Ant's launching script recognizes this flag and will pass it to
|
---|
258 | the java command appropriately.</p>
|
---|
259 | <p>Format:</p><pre>
|
---|
260 | AnsiColorLogger.*=Attribute;Foreground;Background
|
---|
261 |
|
---|
262 | Attribute is one of the following:
|
---|
263 | 0 -> Reset All Attributes (return to normal mode)
|
---|
264 | 1 -> Bright (Usually turns on BOLD)
|
---|
265 | 2 -> Dim
|
---|
266 | 3 -> Underline
|
---|
267 | 5 -> link
|
---|
268 | 7 -> Reverse
|
---|
269 | 8 -> Hidden
|
---|
270 |
|
---|
271 | Foreground is one of the following:
|
---|
272 | 30 -> Black
|
---|
273 | 31 -> Red
|
---|
274 | 32 -> Green
|
---|
275 | 33 -> Yellow
|
---|
276 | 34 -> Blue
|
---|
277 | 35 -> Magenta
|
---|
278 | 36 -> Cyan
|
---|
279 | 37 -> White
|
---|
280 |
|
---|
281 | Background is one of the following:
|
---|
282 | 40 -> Black
|
---|
283 | 41 -> Red
|
---|
284 | 42 -> Green
|
---|
285 | 43 -> Yellow
|
---|
286 | 44 -> Blue
|
---|
287 | 45 -> Magenta
|
---|
288 | 46 -> Cyan
|
---|
289 | 47 -> 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
|
---|
300 | each 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. Finish events are either logged as
|
---|
311 | INFO or ERROR depending on whether the build failed during that stage. Message
|
---|
312 | events are logged according to their Ant logging level, mapping directly to a
|
---|
313 | corresponding 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'
|
---|
322 | configuration file. Both should be placed somewhere in your Ant
|
---|
323 | classpath. If the log4j.properties is in your project root folder you can
|
---|
324 | add 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
|
---|
331 | console by the DefaultLogger and send it to a file named 'build.log', you
|
---|
332 | could use the following configuration:</p>
|
---|
333 |
|
---|
334 | <blockquote>
|
---|
335 |
|
---|
336 | <pre><code>log4j.rootLogger=ERROR, LogFile
|
---|
337 | log4j.logger.org.apache.tools.ant.Project=INFO
|
---|
338 | log4j.logger.org.apache.tools.ant.Target=INFO
|
---|
339 | log4j.logger.org.apache.tools.ant.taskdefs=INFO
|
---|
340 | log4j.logger.org.apache.tools.ant.taskdefs.Echo=WARN
|
---|
341 |
|
---|
342 | log4j.appender.LogFile=org.apache.log4j.FileAppender
|
---|
343 | log4j.appender.LogFile.layout=org.apache.log4j.PatternLayout
|
---|
344 | log4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%n
|
---|
345 | log4j.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
|
---|
351 | documentation 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
|
---|
356 | of the <code>XmlLogger.file</code> property if present, when used as a
|
---|
357 | listener. When used as a logger, it writes all output to either the
|
---|
358 | console or to the value of <code>-logfile</code>. Whether used as a listener
|
---|
359 | or logger, the output is not generated until the build is complete, as it
|
---|
360 | buffers the information in order to provide timing information for task,
|
---|
361 | targets, and the project.
|
---|
362 | <p>
|
---|
363 | By default the XML file creates
|
---|
364 | a reference to an XSLT file "log.xsl" in the current directory; look in
|
---|
365 | ANT_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.
|
---|
367 | this can be a relative or absolute file path, or an http URL.
|
---|
368 | If you set the property to the empty string, "", no XSLT transform
|
---|
369 | is 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
|
---|
400 | developers.</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>
|
---|