← Back to branch summary

~mandel/ubuntuone-windows-installer/fix_null_pointer_start

« back to all changes in this revision

Viewing changes to tools/Nant/doc/help/fundamentals/listeners.html

  • Committer: Manuel de la Pena
  • Date: 2010-07-08 13:22:59 UTC
  • Revision ID: mandel@themacaque.com-20100708132259-y1jgyuyqfe9stt8u
Updated build script to run tests and added all the required tools so far.

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/Nant/doc/help/fundamentals/listeners.html
 
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 
2
<html xmlns="http://www.w3.org/1999/xhtml">
 
3
    <head>
 
4
        <title>NAnt - Loggers &amp; Listeners</title>
 
5
        <meta http-equiv="Content-Language" content="en-ca" />
 
6
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
7
        <meta name="description" content="Loggers &amp; Listeners" />
 
8
        <link rel="stylesheet" type="text/css" href="../style.css" />
 
9
        <style type="text/css">
 
10
            .xmlelement {
 
11
                color: #660000;
 
12
            }
 
13
            
 
14
            .xmlattribute {
 
15
                color: red;
 
16
            }
 
17
 
 
18
            .xmltext {
 
19
                color: blue;
 
20
            }
 
21
 
 
22
            .xmlcomment {
 
23
                color: green;
 
24
            }
 
25
            
 
26
            .xmlcdata {
 
27
                color: #FF00CC;
 
28
            }
 
29
        </style>
 
30
    </head>
 
31
    <body>
 
32
        <table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
 
33
            <tr>
 
34
                <td class="NavBar-Cell">
 
35
                    <a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a> <img src="../images/arrow.gif" alt="->" width="13" height="9" />
 
36
                    <a href="../index.html">Help</a> <img alt="->" src="../images/arrow.gif"/> <a href="index.html">
 
37
                        Fundamentals</a> <img height="9" alt="->" src="../images/arrow.gif" width="13" />
 
38
                    Loggers &amp; Listeners
 
39
                </td>
 
40
                <td class="NavBar-Cell" align="right">
 
41
                    v0.90
 
42
                </td>
 
43
            </tr>
 
44
        </table>
 
45
        <h1>Loggers &amp; Listeners</h1>
 
46
        
 
47
        <h2>Overview</h2>
 
48
        <p>
 
49
            NAnt has two related features to allow the build process to be monitored: 
 
50
            listeners and loggers.
 
51
        </p>
 
52
        <h3>Listeners</h3>
 
53
        <p>
 
54
            A listener is alerted of the following events:
 
55
        </p>
 
56
        <ul>
 
57
            <li>
 
58
            build started
 
59
            </li>
 
60
            <li>
 
61
            build finished
 
62
            </li>
 
63
            <li>
 
64
            target started
 
65
            </li>
 
66
            <li>
 
67
            target finished
 
68
            </li>
 
69
            <li>
 
70
            task started
 
71
            </li>
 
72
            <li>
 
73
            task finished
 
74
            </li>
 
75
            <li>
 
76
                message logged</li>
 
77
        </ul>
 
78
        <h3>Loggers</h3>
 
79
        <p>
 
80
            Loggers extend the capabilities of listeners and add the following features:
 
81
        </p>
 
82
        <ul>
 
83
            <li>
 
84
                Receives a handle to the standard output and error print streams and therefore 
 
85
                can log information to the console or the <code>-logfile</code>
 
86
            specified file.
 
87
            </li>
 
88
            <li>
 
89
                Logging level (<code>-quiet</code>, <code>-verbose</code>, <code>-debug</code>) 
 
90
            aware.
 
91
            </li>
 
92
            <li>
 
93
                Emacs-mode aware. This still needs to be implemented.
 
94
            </li>
 
95
        </ul>
 
96
        <h2>Built-in Listeners/Loggers</h2>
 
97
        <div class="table">
 
98
            <table>
 
99
                <colgroup>
 
100
                    <col />
 
101
                        <col />
 
102
                            <col style="TEXT-ALIGN: center" />
 
103
                </colgroup>
 
104
                <tbody>
 
105
                    <tr>
 
106
                        <th>
 
107
                            Class</th>
 
108
                        <th>
 
109
                            Description</th>
 
110
                        <th>
 
111
                            Type</th>
 
112
                    </tr>
 
113
                    <tr>
 
114
                        <td><a href="#DefaultLogger">NAnt.Core.DefaultLogger</a></td>
 
115
                        <td>
 
116
                            The logger used implicitly unless overridden with the <code>-logger</code> command-line 
 
117
                            switch.
 
118
                        </td>
 
119
                        <td>IBuildLogger</td>
 
120
                    </tr>
 
121
                    <tr>
 
122
                        <td><a href="#MailLogger">NAnt.Core.MailLogger</a></td>
 
123
                        <td>
 
124
                            Extends <a href="#DefaultLogger">DefaultLogger</a> such that output is still 
 
125
                            generated the same, and when the build is finished an e-mail can be sent.
 
126
                        </td>
 
127
                        <td>IBuildLogger</td>
 
128
                    </tr>
 
129
                    <tr>
 
130
                        <td><a href="#XmlLogger">NAnt.Core.XmlLogger</a></td>
 
131
                        <td>
 
132
                            Generates output in XML format.
 
133
                        </td>
 
134
                        <td>IBuildLogger</td>
 
135
                    </tr>
 
136
                </tbody>
 
137
            </table>
 
138
        </div>
 
139
        <h3><a id="DefaultLogger" />DefaultLogger</h3>
 
140
        <p>Simply run NAnt normally, or:</p>
 
141
        <blockquote>
 
142
            <p><code>NAnt.exe -logger:NAnt.Core.DefaultLogger</code></p>
 
143
        </blockquote>
 
144
        <h3><a id="MailLogger" />MailLogger</h3>
 
145
        <p>
 
146
            The MailLogger captures all output logged through DefaultLogger (standard NAnt 
 
147
            output) and will send success and failure messages to unique e-mail lists, with 
 
148
            control for turning off success or failure messages individually.
 
149
        </p>
 
150
        <p>Properties controlling the operation of MailLogger are:</p>
 
151
        <div class="table">
 
152
            <table>
 
153
                <colgroup>
 
154
                    <col />
 
155
                    <col />
 
156
                    <col />
 
157
                </colgroup>
 
158
                <tbody>
 
159
                    <tr>
 
160
                        <th>
 
161
                            Property</th>
 
162
                        <th>
 
163
                            Description</th>
 
164
                        <th>
 
165
                            Required</th>
 
166
                    </tr>
 
167
                    <tr>
 
168
                        <td>MailLogger.mailhost</td>
 
169
                        <td>The SMTP server to use.</td>
 
170
                        <td>No, default is "localhost"</td>
 
171
                    </tr>
 
172
                    <tr>
 
173
                        <td>MailLogger.from</td>
 
174
                        <td>The address of the e-mail sender.</td>
 
175
                        <td>Yes, if mail needs to be sent.</td>
 
176
                    </tr>
 
177
                    <tr>
 
178
                        <td>MailLogger.failure.notify</td>
 
179
                        <td>Send build failure e-mails ?</td>
 
180
                        <td>No, default is "true".</td>
 
181
                    </tr>
 
182
                    <tr>
 
183
                        <td>MailLogger.success.notify</td>
 
184
                        <td>Send build success e-mails ?</td>
 
185
                        <td>No, default is "true".</td>
 
186
                    </tr>
 
187
                    <tr>
 
188
                        <td>MailLogger.failure.to</td>
 
189
                        <td>The address to send build failure messages to.</td>
 
190
                        <td>Yes, if failure mail is to be sent.</td>
 
191
                    </tr>
 
192
                    <tr>
 
193
                        <td>MailLogger.success.to</td>
 
194
                        <td>The address to send build success messages to.</td>
 
195
                        <td>Yes, if success mail is to be sent.</td>
 
196
                    </tr>
 
197
                    <tr>
 
198
                        <td>MailLogger.failure.subject</td>
 
199
                        <td>The subject of build failure messages.</td>
 
200
                        <td>No, default is "Build Failure".</td>
 
201
                    </tr>
 
202
                    <tr>
 
203
                        <td>MailLogger.success.subject</td>
 
204
                        <td>The subject of build success messages.</td>
 
205
                        <td>No, default is "Build Success".</td>
 
206
                    </tr>
 
207
                    <tr>
 
208
                        <td>MailLogger.failure.attachments</td>
 
209
                        <td>The ID of a fileset representing a set of files to attach when the build fails.</td>
 
210
                        <td>No.</td>
 
211
                    </tr>
 
212
                    <tr>
 
213
                        <td>MailLogger.success.attachments</td>
 
214
                        <td>The ID of a fileset representing a set of files to attach when the build is successful.</td>
 
215
                        <td>No.</td>
 
216
                    </tr>
 
217
                    <tr>
 
218
                        <td>MailLogger.body.encoding</td>
 
219
                        <td>The encoding type of the body of the e-mail message.</td>
 
220
                        <td>No, default is system's ANSI code page.</td>
 
221
                    </tr>
 
222
                    <tr>
 
223
                        <td>MailLogger.smtp.username<sup>1</sup></td>
 
224
                        <td>The name of the user to login to the SMTP server.</td>
 
225
                        <td>No.</td>
 
226
                    </tr>
 
227
                    <tr>
 
228
                        <td>MailLogger.smtp.password<sup>1</sup></td>
 
229
                        <td>The password of the specified user.</td>
 
230
                        <td>No.</td>
 
231
                    </tr>
 
232
                    <tr>
 
233
                        <td>MailLogger.smtp.enablessl<sup>1</sup></td>
 
234
                        <td>Specifies whether to use SSL to encrypt the connection.</td>
 
235
                        <td>No, default is "false".</td>
 
236
                    </tr>
 
237
                    <tr>
 
238
                        <td>MailLogger.smtp.port<sup>1</sup></td>
 
239
                        <td>The SMTP server port to connect to.</td>
 
240
                        <td>No, default is "25".</td>
 
241
                    </tr>
 
242
                </tbody>
 
243
            </table>
 
244
            <p><sup>1</sup> Only available when NAnt is built targeting .NET Framework 1.1 (or equivalent) or higher.</p>            
 
245
        </div>
 
246
        <p>Usage:</p>
 
247
        <blockquote>
 
248
            <p><code>NAnt.exe -logger:NAnt.Core.MailLogger</code></p>
 
249
        </blockquote>
 
250
        <p>Example:</p>
 
251
        <pre class="code">
 
252
    <span class="xmltext">&lt;</span><span class="xmlelement">project</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger Test"</span> <span class="xmlattribute">default</span><span class="xmltext">="build"&gt;</span>
 
253
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.mailhost"</span> <span class="xmlattribute">value</span><span class="xmltext">="smtp.wherever.be" /&gt;</span>
 
254
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.from"</span> <span class="xmlattribute">value</span><span class="xmltext">="me@telenet.be" /&gt;</span>
 
255
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.notify"</span> <span class="xmlattribute">value</span><span class="xmltext">="true" /&gt;</span>
 
256
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.notify"</span> <span class="xmlattribute">value</span><span class="xmltext">="true" /&gt;</span>
 
257
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.to"</span> <span class="xmlattribute">value</span><span class="xmltext">="support@home.be" /&gt;</span>
 
258
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.to"</span> <span class="xmlattribute">value</span><span class="xmltext">="support@home.be" /&gt;</span>
 
259
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.subject"</span> <span class="xmlattribute">value</span><span class="xmltext">="Nightly build failure !" /&gt;</span>
 
260
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.subject"</span> <span class="xmlattribute">value</span><span class="xmltext">="Nightly build successful" /&gt;</span>
 
261
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.failure.attachments"</span> <span class="xmlattribute">value</span><span class="xmltext">="MailLogger.failure.files" /&gt;</span>
 
262
        <span class="xmltext">&lt;</span><span class="xmlelement">property</span> <span class="xmlattribute">name</span><span class="xmltext">="MailLogger.success.attachments"</span> <span class="xmlattribute">value</span><span class="xmltext">="MailLogger.success.files" /&gt;</span>
 
263
 
 
264
        <span class="xmlcomment">&lt;!-- set of files to attach when build fails --&gt;</span>
 
265
        <span class="xmltext">&lt;</span><span class="xmlelement">fileset</span> <span class="xmlattribute">id</span><span class="xmltext">="MailLogger.failure.files"&gt;</span>
 
266
            <span class="xmltext">&lt;</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="dump.log" /&gt;</span>
 
267
            <span class="xmltext">&lt;</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="trace.txt" /&gt;</span>
 
268
        <span class="xmltext">&lt;/</span><span class="xmlelement">fileset</span><span class="xmltext">&gt;</span>
 
269
 
 
270
        <span class="xmlcomment">&lt;!-- set of files to attach when build is successful --&gt;</span>
 
271
        <span class="xmltext">&lt;</span><span class="xmlelement">fileset</span> <span class="xmlattribute">id</span><span class="xmltext">="MailLogger.success.files"&gt;</span>
 
272
            <span class="xmltext">&lt;</span><span class="xmlelement">include</span> <span class="xmlattribute">name</span><span class="xmltext">="trace.txt" /&gt;</span>
 
273
        <span class="xmltext">&lt;/</span><span class="xmlelement">fileset</span><span class="xmltext">&gt;</span>
 
274
    
 
275
        <span class="xmltext">&lt;</span><span class="xmlelement">target</span> <span class="xmlattribute">name</span><span class="xmltext">="build"&gt;</span>
 
276
            <span class="xmltext">&lt;</span><span class="xmlelement">echo</span> <span class="xmlattribute">message</span><span class="xmltext">=&quot;Starting build&quot; /&gt;</span>
 
277
            ....
 
278
            <span class="xmltext">&lt;</span><span class="xmlelement">echo</span> <span class="xmlattribute">message</span><span class="xmltext">=&quot;Finished build&quot; /&gt;</span>
 
279
        <span class="xmltext">&lt;/</span><span class="xmlelement">target</span><span class="xmltext">&gt;</span>
 
280
    <span class="xmltext">&lt;/</span><span class="xmlelement">project</span><span class="xmltext">&gt;</span>
 
281
        </pre>
 
282
        <h3><a id="XmlLogger" />XmlLogger</h3>
 
283
        <p>
 
284
            Writes all build information out to an XML file named <code>log.xml</code>, or 
 
285
            the value of the <code>XmlLogger.file</code> property if present, when used as 
 
286
            a listener. When used as a logger, it writes all output to either the console 
 
287
            or to the value of <code>-logfile</code>.
 
288
        </p>
 
289
        <p>
 
290
            Whether used as a listener or logger, the output is not generated until the 
 
291
            build is complete.
 
292
        </p>
 
293
        <p>Usage:</p>
 
294
        <blockquote>
 
295
            <p>
 
296
                <code>NAnt.exe -listener:NAnt.Core.XmlLogger</code><br />
 
297
                <code>NAnt.exe -logger:NAnt.Core.XmlLogger -logfile:buildlog.xml</code>
 
298
            </p>
 
299
        </blockquote>
 
300
        <p>Example:</p>
 
301
        <pre class="code">
 
302
    <span class="xmltext">&lt;</span><span class="xmlelement">buildresults</span> <span class="xmlattribute">project</span><span class="xmltext">="test"&gt;</span>
 
303
        <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Buildfile: file:///D:/nant-test/xmlpeek/default.build]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
 
304
        <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Target framework: Microsoft .NET Framework 1.1]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
 
305
        <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Target<span class="xmltext">(</span>s<span class="xmltext">)</span> specified: build]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
 
306
        <span class="xmltext">&lt;</span><span class="xmlelement">target</span> <span class="xmlattribute">name</span><span class="xmltext">="build"&gt;</span>
 
307
            <span class="xmltext">&lt;</span><span class="xmlelement">task</span> <span class="xmlattribute">name</span><span class="xmltext">="xmlpeek"&gt;</span>
 
308
                <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Peeking at <span class="xmltext">'D:\nant-test\xmlpeek\input.xml'</span> with XPath expression <span class="xmltext">'x:parameters/x:param'</span>.]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
 
309
                <span class="xmltext">&lt;</span><span class="xmlelement">message</span> <span class="xmlattribute">level</span><span class="xmltext">="Info"&gt;&lt;![</span><span class="xmlcdata">CDATA[Found <span class="xmltext">'1'</span> nodes with the XPath expression <span class="xmltext">'x:parameters/x:param'</span>.]]</span><span class="xmltext">&gt;&lt;/</span><span class="xmlelement">message</span><span class="xmltext">&gt;</span>
 
310
                <span class="xmltext">&lt;</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span><span style="color: black;">15.625</span><span class="xmltext">&lt;/</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span>
 
311
            <span class="xmltext">&lt;/</span><span class="xmlelement">task</span><span class="xmltext">&gt;</span>
 
312
            <span class="xmltext">&lt;</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span><span style="color: black;">15.625</span><span class="xmltext">&lt;/</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span>
 
313
        <span class="xmltext">&lt;/</span><span class="xmlelement">target</span><span class="xmltext">&gt;</span>
 
314
        <span class="xmltext">&lt;</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span><span style="color: black;">31.25</span><span class="xmltext">&lt;/</span><span class="xmlelement">duration</span><span class="xmltext">&gt;</span>
 
315
    <span class="xmltext">&lt;/</span><span class="xmlelement">buildresults</span><span class="xmltext">&gt;</span>
 
316
        </pre>
 
317
    </body>
 
318
</html>