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