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           Another way to conditionally log debug output (e.g. in case of
 234           very large installers which may create gigabytes of log
 235           output) is to create a pipe:
 236         </para>
 237         <screen>
 238         <prompt>$</prompt> <userinput>mknod /tmp/debug_pipe p</userinput>
 239         </screen>
 240
 241         <para>
 242           and then to run wine like that:
 243         </para>
 244         <screen>
 245         <prompt>$</prompt> <userinput>wine --debugmsg +relay,+snoop setup.exe &>/tmp/debug_pipe</userinput>
 246         </screen>
 247
 248         <para>
 249           Since the pipe is initially blocking (and thus wine as a whole),
 250           you have to activate it by doing:
 251         </para>
 252         <screen>
 253         <prompt>$</prompt> <userinput>cat /tmp/debug_pipe</userinput>
 254         </screen>
 255         <para>
 256           (press Ctrl-C to stop pasting the pipe content)
 257         </para>
 258         <para>
 259           Once you are about to approach the problematic part of the program,
 260           you just do:
 261         </para>
 262         <screen>
 263         <prompt>$</prompt> <userinput>cat /tmp/debug_pipe >/tmp/wine.log</userinput>
 264         </screen>
 265         <para>
 266           to capture specifically the part that interests you from the
 267           pipe without wasting excessive amounts of HDD space and
 268           slowing down installation considerably.
 269         </para>
 270         <para>
 271           The <parameter>WINEDEBUG</parameter> environment variable
 272           controls the output of the debug messages.
 273           It has the following syntax:
 274           <parameter>WINEDEBUG= [yyy]#xxx[,[yyy1]#xxx1]*</parameter>
 275         </para>
 276         <itemizedlist>
 277           <listitem>
 278             <para>
 279               where
 280               <literal>#</literal> is either <literal>+</literal> or
 281               <literal>-</literal>
 282             </para>
 283           </listitem>
 284           <listitem>
 285             <para>
 286               when the optional class argument (<literal>yyy</literal>)
 287               is not present, then the statement will
 288               enable(<literal>+</literal>)/disable(<literal>-</literal>)
 289               all messages for the given channel (<literal>xxx</literal>)
 290               on all classes. For example:
 291             </para>
 292             <programlisting>
 293 WINEDEBUG=+reg,-file
 294             </programlisting>
 295             <para>
 296               enables all messages on the <literal>reg</literal>
 297               channel and disables all messages on the
 298               <literal>file</literal> channel.
 299             </para>
 300           </listitem>
 301           <listitem>
 302             <para>
 303               when the optional class argument (<literal>yyy</literal>)
 304               is present,  then the statement will enable
 305               (<literal>+</literal>)/disable(<literal>-</literal>)
 306               messages for the given channel (<literal>xxx</literal>)
 307               only on the given class. For example:
 308             </para>
 309             <programlisting>
 310 WINEDEBUG=trace+reg,warn-file
 311             </programlisting>
 312             <para>
 313               enables trace messages on the <literal>reg</literal>
 314               channel and disables warning messages on the
 315               <literal>file</literal> channel.
 316             </para>
 317           </listitem>
 318           <listitem>
 319             <para>
 320               also, the pseudo-channel all is also supported and it
 321               has the  intuitive semantics:
 322             </para>
 323             <screen>
 324     WINEDEBUG=+all      -- enables all debug messages
 325     WINEDEBUG=-all      -- disables all debug messages
 326     WINEDEBUG=yyy+all   -- enables debug messages for class yyy on all
 327                            channels.
 328     WINEDEBUG=yyy-all   -- disables debug messages for class yyy on all
 329                            channels.
 330             </screen>
 331             <para>
 332               So, for example:
 333             </para>
 334             <screen>
 335     WINEDEBUG=warn-all  -- disables all warning messages.
 336             </screen>
 337           </listitem>
 338         </itemizedlist>
 339
 340         <para>
 341           Also, note that at the moment:
 342         </para>
 343         <itemizedlist>
 344           <listitem>
 345             <para>
 346               the <literal>FIXME</literal> and <literal>ERR</literal>
 347               classes are enabled by default
 348             </para>
 349           </listitem>
 350           <listitem>
 351             <para>
 352               the <literal>TRACE</literal> and <literal>WARN</literal>
 353               classes are disabled by default
 354             </para>
 355           </listitem>
 356         </itemizedlist>
 357       </sect1>
 358
 359       <sect1 id="dbg-compiling">
 360         <title>Compiling Out Debugging Messages</title>
 361
 362         <para>
 363           To compile out the debugging messages, provide
 364           <command>configure</command> with the following options:
 365         </para>
 366         <screen>
 367     --disable-debug      -- turns off TRACE, WARN, and FIXME (and DUMP).
 368     --disable-trace      -- turns off TRACE only.
 369         </screen>
 370         <para>
 371           This will result in an executable that, when stripped, is
 372           about 15%-20% smaller.  Note, however, that you will not be
 373           able to effectively debug Wine without these messages.
 374         </para>
 375         <para>
 376           This feature has not been extensively tested--it may subtly
 377           break some things.
 378         </para>
 379       </sect1>
 380
 381       <sect1 id="dbg-notes">
 382         <title>A Few Notes on Style</title>
 383
 384         <para>
 385           This new scheme makes certain things more consistent but
 386           there is still room for improvement by using a common style
 387           of debug messages. Before I continue, let me note that the
 388           output format is the following:
 389         </para>
 390         <screen>
 391 yyy:xxx:fff &lt;message>
 392
 393 where:
 394   yyy = the class (fixme, err, warn, trace)
 395   xxx = the channel (atom, win, font, etc)
 396   fff = the function name
 397         </screen>
 398         <para>
 399           these fields are output automatically. All you have to
 400           provide is the &lt;message> part.
 401         </para>
 402         <para>
 403           So here are some ideas:
 404         </para>
 405
 406         <itemizedlist>
 407           <listitem>
 408             <para>
 409               do not include the name of the function: it is included automatically
 410             </para>
 411           </listitem>
 412           <listitem>
 413             <para>
 414               if you want to output the parameters of the function, do
 415               it as the first thing and include them in parentheses,
 416               like this:
 417               <programlisting>
 418 TRACE("(%d, %p, ...)\n", par1, par2, ...);
 419               </programlisting>
 420             </para>
 421           </listitem>
 422           <listitem>
 423             <para>
 424               for stubs, you should output a <literal>FIXME</literal>
 425               message. I suggest this style:
 426               <programlisting>
 427 FIXME("(%x, %d, ...): stub\n", par1, par2, ...);
 428               </programlisting>
 429             </para>
 430           </listitem>
 431           <listitem>
 432             <para>
 433               try to output one line per message. That is, the format
 434               string should contain only one <literal>\n</literal> and it
 435               should always appear at the end of the string. (there are
 436               many reasons  for this requirement, one of them is that
 437               each debug macro adds things to the beginning of the line)
 438             </para>
 439           </listitem>
 440           <listitem>
 441             <para>
 442               if you want to name a parameter, use <literal>=</literal> :
 443               <programlisting>
 444 FIXME("(fd=%d, file=%s): stub\n", fd, name);
 445               </programlisting>
 446             </para>
 447           </listitem>
 448         </itemizedlist>
 449       </sect1>
 450
 451   </chapter>
 452
 453 <!-- Keep this comment at the end of the file
 454 Local variables:
 455 mode: sgml
 456 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
 457 End:
 458 -->