                              Wine Documentation                               
Prev                                                                       Next
-------------------------------------------------------------------------------

Chapter 8. Debug Logging

Written by Dimitrie O. Paun <dimi@cs.toronto.edu>, 28 Mar 1998

(Extracted from wine/documentation/debug-msgs)

Note The new debugging interface can be considered to be stable, with the      
     exception of the in-memory message construction functions. However, there 
     is still a lot of work to be done to polish things up. To make my life    
     easier, please follow the guidelines described in this document.          

Important Read this document before writing new code. DO NOT USE fprintf (or   
          printf) to output things. Also, instead of writing FIXMEs in the     
          source, output a FIXME message if you can.                           
                                                                               
          At the end of the document, there is a "Style Guide" for debugging   
          messages. Please read it.                                            

8.1. Debugging classes

There are 4 types (or classes) of debugging messages:

FIXME
   
    Messages in this class relate to behavior of Wine that does not correspond
    to standard Windows behavior and that should be fixed.
   
    Examples: stubs, semi-implemented features, etc.
   
ERR
   
    Messages in this class relate to serious errors in Wine. This sort of
    messages are close to asserts -- that is, you should output an error
    message when the code detects a condition which should not happen. In other
    words, important things that are not warnings (see below), are errors.
   
    Examples: unexpected change in internal state, etc.
   
WARN
   
    These are warning messages. You should report a warning when something
    unwanted happen but the function behaves properly. That is, output a
    warning when you encounter something unexpected (ex: could not open a file)
    but the function deals correctly with the situation (that is, according to
    the docs). If you do not deal correctly with it, output a fixme.
   
    Examples: fail to access a resource required by the app, etc.
   
TRACE
   
    These are detailed debugging messages that are mainly useful to debug a
    component. These are usually turned off.
   
    Examples: everything else that does not fall in one of the above mentioned
    categories and the user does not need to know about it.
   
The user has the capability to turn on or off messages of a particular type.
You can expect the following patterns of usage (but note that any combination
is possible):

  * when you debug a component, all types (TRACE, WARN, ERR, FIXME) will be
    enabled.
   
  * during the pre-alpha (maybe alpha) stage of Wine, most likely the TRACE
    class will be disabled by default, but all others (WARN, ERR, FIXME) will
    be enabled by default.
   
  * when Wine will become stable, most likely the TRACE and WARN classes will
    be disabled by default, but all ERRs and FIXMEs will be enabled.
   
  * in some installations that want the smallest footprint and where the debug
    information is of no interest, all classes may be disabled by default.
   
Of course, the user will have the runtime ability to override these defaults.
However, this ability may be turned off and certain classes of messages may be
completely disabled at compile time to reduce the size of Wine.

-------------------------------------------------------------------------------
Prev                                 Home                                  Next
WINE/WINDOWS DLLs                     Up                     Debugging channels
