Wine-Staging Debug

From WineHQ Wiki
Jump to: navigation, search

Debug Output

Wine consists of a lot of different modules and provides ways to control debug output for each of the modules independently. In order to enable or disable the debug output for one these debug channels, you need to set the WINEDEBUG environment variable while starting a program. The WINEDEBUG variable needs to be specified in the following format:

WINEDEBUG=[+process:][class]+channel,[-process:][class]-channel,...

You need to specify at least the channel for which you would like to change the debug level. This usually matches the name of a dll provided by Wine, but there are also exceptions (see list at the end of the page). If you want to see all debug messages from ntdll, you would use the following line:

WINEDEBUG=+ntdll wine test.exe

In order to suppress all messages by ntdll you would simply use '-' instead of '+':

WINEDEBUG=-ntdll wine test.exe

Besides turning off/on all debug messages, you can also control different classes of debug levels. The supported classes are:

  • err (critical errors, turned ON by default)
  • fixme (warnings about unimplemented features, turned ON by default)
  • warn (non critical errors, turned OFF by default)
  • trace (all functions calls, turned OFF by default)

In case you want to see all warnings from ntdll (additionally to errors and fixmes), you could use the following line:

WINEDEBUG=warn+ntdll wine test.exe

Wine Staging also provides a way to control the debug settings for each (child) process independently. This is especially useful if you want to debug a game which needs to be started by a launcher or programs like Uplay. The following line will disable the debug output for all programs for which the executable image filename does not match game.exe:

WINEDEBUG=-game.exe:-all wine launcher.exe

If you also want to turn on relay for the game, you can use the following command line:

WINEDEBUG=-game.exe:-all,+game.exe:+relay wine launcher.exe

Usually you would write the debug messages into a file as the output can get quite big depending on the enabled debug channels. Several hundred megabytes or multiple gigabytes are not unusual when +relay is enabled for example. Another problem you may encounter are overlapped debug messages when a program uses multiple threads or sub processes. You can prevent this by using the append mode in the following way:

WINEDEBUG=... wine game.exe >> debug.log 2>&1

Now you should know everything required to create proper debug logs.

Debug Channels

As mentioned earlier the possible debug channels usually match the name of the dlls provided by Wine, but there are also exceptions and special debug channels. Those special debug channels do not control a single module but affect all modules or all debug messages. The most important ones are:

  • tid prints the thread id before all debug messages
  • timestamp prints the timestamp in front of all debug messages
  • relay prints all functions calls to wine dlls and their return values
  • seh show more detailed information about exceptions

You should use +tid if you are debugging multiple threads or processes and it generally doesn't hurt to enable it all the time. If you are searching for a bug and don't have a clue what is going wrong, the +relay channel might be useful. It prints a lot of information about all regular function calls and will often also contain a hint where the problem might be, but you should be aware that calls to COM interfaces are not logged with this method. You will not, for example, be able to find an error in d3d9 interfaces this way.

The +seh channel prints information about exceptions like invalid memory accesses. You should always take a look at it if the application crashes, especially when the application catches the exception and shows it's own crash dialog.

You can find more information about these special debug channels at Debug Channels.