Debug Logging

Written by Dimitrie O. Paun , 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.

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

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.