Remember (do not reset) font size and style parameters in the initial
[wine] / documentation / debugging.sgml
1   <chapter id="debugging">
2     <title>Debug Logging</title>
3
4         <para>
5           To better manage the large volume of debugging messages that
6           Wine can generate, we divide the messages on a component basis, 
7           and classify them based on the severity of the reported problem.
8           Therefore a message belongs to a <emphasis>channel</emphasis>
9           and a <emphasis>class</emphasis> respectively.
10         </para>
11         <para>
12           This section will describe the debugging classes, how you can 
13           create a new debugging channel, what the debugging API is,
14           and how you can control the debugging output. A picture is
15           worth a thousand words, so here are a few examples of the
16           debugging API in action:
17           <screen>
18 ERR("lock_count == 0 ... please report\n");
19 FIXME("Unsupported RTL style!\n");
20 WARN(": file seems to be truncated!\n");
21 TRACE("[%p]: new horz extent = %d\n", hwnd, extent );
22 MESSAGE( "Could not create graphics driver '%s'\n", buffer );
23           </screen>
24         </para>
25
26       <sect1 id="dbg-classes">
27         <title>Debugging classes</title>
28
29         <para>
30           A debugging class categorizes a message based on the severity
31           of the reported problem. There is a fixed set of classes, and
32           you must carefully choose the appropriate one for your messages.
33           There are five classes of messages:
34         </para>
35         <variablelist>
36           <varlistentry>
37             <term><literal>FIXME</literal></term>
38             <listitem>
39               <para>
40                 Messages in this class are meant to signal unimplemented
41                 features, known bugs, etc. They serve as a constant and
42                 active reminder of what needs to be done.
43               </para>
44             </listitem>
45           </varlistentry>
46           <varlistentry>
47             <term><literal>ERR</literal></term>
48             <listitem>
49               <para>
50                 Messages in this class indicate serious errors in
51                 Wine, such as as conditions that should never happen
52                 by design.
53               </para>
54             </listitem>
55           </varlistentry>
56           <varlistentry>
57             <term><literal>WARN</literal></term>
58             <listitem>
59               <para>
60                 These are warning messages. You should report a
61                 warning when something unwanted happens, and the
62                 function can not deal with the condition. This
63                 is seldomly used since proper functions can usually
64                 report failures back to the caller. Think twice before
65                 making the message a warning.
66               </para>
67             </listitem>
68           </varlistentry>
69           <varlistentry>
70             <term><literal>TRACE</literal></term>
71             <listitem>
72               <para>
73                 These are detailed debugging messages that are mainly
74                 useful to debug a component. These are turned off unless
75                 explicitly enabled.
76               </para>
77             </listitem>
78           </varlistentry>
79           <varlistentry>
80             <term><literal>MESSAGE</literal></term>
81             <listitem>
82               <para>
83                 There messages are intended for the end user. They do not
84                 belong to any channel. As with warnings, you will seldomly
85                 need to output such messages.
86               </para>
87             </listitem>
88           </varlistentry>
89         </variablelist>
90       </sect1>
91
92       <sect1 id="dbg-channels">
93         <title>Debugging channels</title>
94
95         <para>
96           Each component is assigned a debugging channel. The
97           identifier of the channel must be a valid C identifier 
98           (reserved word like <type>int</type> or <type>static</type>
99           are premitted). To use a new channel, simply use it in
100           your code. It will be picked up automatically by the build process.
101         </para>
102
103         <para>
104         Typically, a file contains code pertaining to only one component,
105         and as such, there is only one channel to output to. You can declare
106         a default chanel for the file using the 
107         <symbol>WINE_DEFAULT_DEBUG_CHANNEL()</symbol> macro:
108         <programlisting>
109 #include "wine/debug.h"
110
111 WINE_DEFAULT_DEBUG_CHANNEL(xxx);
112 ...
113
114     FIXME("some unimplemented feature", ...);
115 ...
116     if (zero != 0)
117         ERR("This should never be non-null: %d", zero);
118 ...
119         </programlisting>
120         </para>
121         <para>
122           In rare situations there is a need to output to more than one
123           debug channel per file. In such cases, you need to declare
124           all the additional channels at the top of the file, and
125           use the _-version of the debugging macros:
126         <programlisting>
127 #include "wine/debug.h"
128
129 WINE_DEFAULT_DEBUG_CHANNEL(xxx);
130 WINE_DECLARE_DEBUG_CHANNEL(yyy);
131 WINE_DECLARE_DEBUG_CHANNEL(zzz);
132 ...
133
134     FIXME("this one goes to xxx channel");
135 ...
136     FIXME_(yyy)("Some other msg for the yyy channel");
137 ...
138     WARN_(zzz)("And yet another msg on another channel!");
139 ...
140         </programlisting>
141         </para>
142
143       </sect1>
144
145       <sect1 id="dbg-checking">
146         <title>Are we debugging?</title>
147
148         <para>
149           To test whether the debugging channel <literal>xxx</literal> is
150           enabled, use the <symbol>TRACE_ON</symbol>, <symbol>WARN_ON</symbol>,
151           <symbol>FIXME_ON</symbol>, or <symbol>ERR_ON</symbol> macros. For
152           example:
153         <programlisting>
154 if(TRACE_ON(atom)){
155     ...blah...
156 }
157         </programlisting>
158           You should normally need to test only if <literal>TRACE_ON</literal>, 
159           all the others are very seldomly used. With careful coding, you
160           can avoid the use of these macros, which is generally desired.
161         </para>
162       </sect1>
163
164       <sect1 id="dbg-helpers">
165         <title>Helper functions</title>
166
167         <para>
168           Resource identifiers can be either strings or numbers. To
169           make life a bit easier for outputting these beasts (and to
170           help you avoid the need to build the message in memory), I
171           introduced a new function called <function>debugres</function>.
172         </para>
173         <para>
174           The function is defined in <filename>wine/debug.h</filename>
175           and has the following prototype:
176         </para>
177         <programlisting>
178 LPSTR debugres(const void *id);
179         </programlisting>
180         <para>
181           It takes a pointer to the resource id and returns a nicely
182           formatted string of the identifier (which can be a string or
183           a number, depending on the value of the high word).
184           Numbers are formatted as such:
185         </para>
186         <programlisting>
187 #xxxx
188         </programlisting>
189         <para>
190           while strings as:
191         </para>
192         <programlisting>
193 'some-string'
194         </programlisting>
195         <para>
196           Simply use it in your code like this:
197         </para>
198         <programlisting>
199 #include "wine/debug.h"
200
201 ...
202
203    TRACE("resource is %s", debugres(myresource));
204         </programlisting>
205
206         <para>
207         Many times strings need to be massaged before output:
208         they may be <literal>NULL</literal>, contain control 
209         characters, or they may be too long. Similarly, Unicode
210         strings need to be converted to ASCII for usage with
211         the debugging API. For all this, you can use the
212         <function>debugstr_[aw]n?</function> familly of functions:
213           <programlisting>
214 HANDLE32 WINAPI YourFunc(LPCSTR s)
215 {
216     FIXME("(%s): stub\n", debugstr_a(s));
217 }
218           </programlisting>
219         </para>
220
221       </sect1>
222
223       <sect1 id="dbg-control">
224         <title>Controlling the debugging output</title>
225
226         <para>
227           It is possible to turn on and off debugging output from
228           within the debugger using the set command. Please see the
229           WineDbg Command Reference section for how to do this.
230         </para>
231
232         <para>
233           The <parameter>--debugmsg</parameter> command line
234           option controls the output of the debug messages.
235           It has the following syntax:
236           <parameter>--debugmsg [yyy]#xxx[,[yyy1]#xxx1]*</parameter>
237         </para>
238         <itemizedlist>
239           <listitem>
240             <para>
241               where
242               <literal>#</literal> is either <literal>+</literal> or
243               <literal>-</literal>
244             </para>
245           </listitem>
246           <listitem>
247             <para>
248               when the optional class argument (<literal>yyy</literal>)
249               is not present, then the statement will
250               enable(<literal>+</literal>)/disable(<literal>-</literal>)
251               all messages for the given channel (<literal>xxx</literal>)
252               on all classes. For example:
253             </para>
254             <programlisting>
255 --debugmsg +reg,-file
256             </programlisting>
257             <para>
258               enables all messages on the <literal>reg</literal>
259               channel and disables all messages on the
260               <literal>file</literal> channel.
261             </para>
262           </listitem>
263           <listitem>
264             <para>
265               when the optional class argument (<literal>yyy</literal>)
266               is present,  then the statement will enable
267               (<literal>+</literal>)/disable(<literal>-</literal>)
268               messages for the given channel (<literal>xxx</literal>)
269               only on the given class. For example:
270             </para>
271             <programlisting>
272 --debugmsg trace+reg,warn-file
273             </programlisting>
274             <para>
275               enables trace messages on the <literal>reg</literal>
276               channel and disables warning messages on the
277               <literal>file</literal> channel.
278             </para>
279           </listitem>
280           <listitem>
281             <para>
282               also, the pseudo-channel all is also supported and it
283               has the  intuitive semantics:
284             </para>
285             <screen>
286     --debugmsg +all      -- enables all debug messages
287     --debugmsg -all      -- disables all debug messages
288     --debugmsg yyy+all   -- enables debug messages for class yyy on all
289                            channels.
290     --debugmsg yyy-all   -- disables debug messages for class yyy on all
291                            channels.
292             </screen>
293             <para>
294               So, for example:
295             </para>
296             <screen>
297     --debugmsg warn-all  -- disables all warning messages.
298             </screen>
299           </listitem>
300         </itemizedlist>
301
302         <para>
303           Also, note that at the moment:
304         </para>
305         <itemizedlist>
306           <listitem>
307             <para>
308               the <literal>FIXME</literal> and <literal>ERR</literal>
309               classes are enabled by default
310             </para>
311           </listitem>
312           <listitem>
313             <para>
314               the <literal>TRACE</literal> and <literal>WARN</literal>
315               classes are disabled by default
316             </para>
317           </listitem>
318         </itemizedlist>
319       </sect1>
320
321       <sect1 id="dbg-compiling">
322         <title>Compiling Out Debugging Messages</title>
323
324         <para>
325           To compile out the debugging messages, provide
326           <command>configure</command> with the following options:
327         </para>
328         <screen>
329     --disable-debug      -- turns off TRACE, WARN, and FIXME (and DUMP).
330     --disable-trace      -- turns off TRACE only.
331         </screen>
332         <para>
333           This will result in an executable that, when stripped, is
334           about 15%-20% smaller.  Note, however, that you will not be
335           able to effectively debug Wine without these messages.
336         </para>
337         <para>
338           This feature has not been extensively tested--it may subtly
339           break some things.
340         </para>
341       </sect1>
342
343       <sect1 id="dbg-notes">
344         <title>A Few Notes on Style</title>
345
346         <para>
347           This new scheme makes certain things more consistent but
348           there is still room for improvement by using a common style
349           of debug messages. Before I continue, let me note that the
350           output format is the following:
351         </para>
352         <screen>
353 yyy:xxx:fff &lt;message>
354
355 where:
356   yyy = the class (fixme, err, warn, trace)
357   xxx = the channel (atom, win, font, etc)
358   fff = the function name
359         </screen>
360         <para>
361           these fields are output automatically. All you have to
362           provide is the &lt;message> part.
363         </para>
364         <para>
365           So here are some ideas:
366         </para>
367
368         <itemizedlist>
369           <listitem>
370             <para>
371               do not include the name of the function: it is included automatically
372             </para>
373           </listitem>
374           <listitem>
375             <para>
376               if you want to output the parameters of the function, do
377               it as the first thing and include them in parentheses,
378               like this:
379               <programlisting>
380 TRACE("(%d, %p, ...)\n", par1, par2, ...);
381               </programlisting>
382             </para>
383           </listitem>
384           <listitem>
385             <para>
386               for stubs, you should output a <literal>FIXME</literal>
387               message. I suggest this style:
388               <programlisting>
389 FIXME("(%x, %d, ...): stub\n", par1, par2, ...);
390               </programlisting>
391             </para>
392           </listitem>
393           <listitem>
394             <para>
395               try to output one line per message. That is, the format
396               string should contain only one <literal>\n</literal> and it
397               should always appear at the end of the string. (there are
398               many reasons  for this requirement, one of them is that
399               each debug macro adds things to the beginning of the line)
400             </para>
401           </listitem>
402           <listitem>
403             <para>
404               if you want to name a parameter, use <literal>=</literal> :
405               <programlisting>
406 FIXME("(fd=%d, file=%s): stub\n", fd, name);
407               </programlisting>
408             </para>
409           </listitem>
410         </itemizedlist>
411       </sect1>
412
413   </chapter>
414
415 <!-- Keep this comment at the end of the file
416 Local variables:
417 mode: sgml
418 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
419 End:
420 -->