WineHQ
WineHQ

Chapter 2. Debug Logging

To better manage the large volume of debugging messages that Wine can generate, we divide the messages on a component basis, and classify them based on the severity of the reported problem. Therefore a message belongs to a channel and a class respectively.

This section will describe the debugging classes, how you can create a new debugging channel, what the debugging API is, and how you can control the debugging output. A picture is worth a thousand words, so here are a few examples of the debugging API in action:

ERR("lock_count == 0 ... please report\n");
FIXME("Unsupported RTL style!\n");
WARN(": file seems to be truncated!\n");
TRACE("[%p]: new horz extent = %d\n", hwnd, extent );
MESSAGE( "Could not create graphics driver '%s'\n", buffer );

2.1. Debugging classes

A debugging class categorizes a message based on the severity of the reported problem. There is a fixed set of classes, and you must carefully choose the appropriate one for your messages. There are five classes of messages:

FIXME

Messages in this class are meant to signal unimplemented features, known bugs, etc. They serve as a constant and active reminder of what needs to be done.

ERR

Messages in this class indicate serious errors in Wine, such as as conditions that should never happen by design.

WARN

These are warning messages. You should report a warning when something unwanted happens, and the function cannot deal with the condition. This is seldom used since proper functions can usually report failures back to the caller. Think twice before making the message a warning.

TRACE

These are detailed debugging messages that are mainly useful to debug a component. These are turned off unless explicitly enabled.

MESSAGE

There messages are intended for the end user. They do not belong to any channel. As with warnings, you will seldom need to output such messages.