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 -->