About This Guide

This is a series of guides intended to introduce software developers to the Wine ecosystem. It will cover what Wine is, how to use Wine, how to debug Wine, how to fix Wine, and what to do with your fix once you've made it.

• Part 1 describes what Wine is and provides a short description of various popular forks of Wine.
• Part 2 describes Wine's build process.
• Part 3 describes how to use Wine as a developer.
• Part 4 describes how to debug Wine in general.
• Part 5 describes Wine's source tree layout and how to edit the source.
• Part 6 describes how you can send your work upstream.

Once you've got some idea of what is causing the problem with your application, it's time to go understand how those APIs are implemented in Wine so you can fix it. You may also need to change Wine's code to debug the application in the first place.

Search for existing bugs

Before digging into the source, it's always useful to first search for existing bugs. You can search Wine's Bugzilla for your application, or for the symptoms you're seeing. As you begin to debug your issue, you may find other search terms to try. If you find a bug, you may find some useful analysis or work has already been done for the issue.

You may also want to look through the Wine Staging patches, especially once you have some idea of what the problem is. You may find someone has already written a patch to fix this problem, but it isn't ready to go upstream yet. You can pick up the torch and try to upstream the work.

Wine source layout

Wine implements the Windows operating system, which is composed of libraries, programs, and kernel functionality. You can find the code for Wine's implementation of each of those components in dlls, programs, and server, respectively. To give you some idea of how different components of Wine work together, some important, core components are listed here.

• dlls/ntdll – This is where many of the core OS APIs are implemented, like file handling, thread creation and synchronization, timing, and much more. Applications typically use kernel32 instead of ntdll directly.

• dlls/kernel32 – This is the application-facing interface for the core ntdll APIs mentioned above.

• dlls/user32 – This is where much of the Windows GUI handling lives, like window creation, message handling, terminal services, and so on.

• dlls/winex11.drv and dlls/winemac.drv – These libraries map the Windows GUI interfaces, and some other platform-specific functions, to the native platform. user32 calls into these platform drivers.

• dlls/d3d* and dlls/wined3d – These libraries implement the Direct3D graphics API on top of the platform's OpenGL implementation.

• programs/services – This program manages background services, both those created by Wine and those provided by installed applications.

• programs/wineboot – This program kicks off initial prefix creation and other tasks when a prefix is booted.

• programs/winecfg – This is Wine's configuration program.

• server – The Wine server implements all cross-process functionality, including message routing, multi-process synchronization primitives, registry handling, and much more. The Wine server is always running if an application is running.

While debug channels are often named after the component in which they are declared (e.g. the dsound channel is declared in dlls/dsound), this is not always the case. You can use git grep to find the relevant debug trace line if it isn't obvious.

Writing tests

In most cases, your work should be driven by tests. Study the documentation for the relevant APIs and write tests first to confirm that Windows's implementation behaves how you expect it to. Then, change Wine's source to pass the tests that you wrote.

Wine has an extensive suite of unit tests. The unit tests comprise well over one million lines of code as of this writing. Any patch you submit must pass all of these tests. Patches should contain more tests proving that the new behavior is correct.

In general, you should focus your work on what a real application actually does. That is, you don't need to implement a bunch of unrelated functionality if the application doesn't actually need it. You should write tests to show how an application is using an API, and how Wine fails to meet its expectations. Then fix Wine to also pass those tests without breaking any existing tests. Any change to Wine has the potential to break other applications. Simply passing tests that you wrote is insufficient reason to change Wine.

You can find the tests for a given component in the tests subdirectory. For example, the tests for dsound live in dlls/dsound/tests. You will find .c files in that directory. The tests start in the START_TEST function and exercise the component being tested. The ok function demonstrates correct behavior. Again, "correct" is defined to mean "like Windows." For example:

    hr = IDirectSound_CreateSoundBuffer(ds, &bufdesc, &primary, NULL);
    ok(hr == S_OK, "CreateSoundBuffer failed: %08x\n", hr);

Here you can see the return value from IDirectSound::CreateSoundBuffer is expected to be S_OK. If it is not S_OK, then the test will fail.

Your tests should demonstrate how your application behaves when interacting with that API. Since you are fixing a bug in Wine's implementation of the API, your tests should demonstrate that Wine will fail without your fix. It isn't necessary, or even recommended, to fully exercise all inputs to an API in the Wine tests. Instead, be thoughtful about how your application might use the API given different inputs from the user, and write tests that reflect those possibilities.

Your tests should be self-contained. They should initialize the necessary functions, test the APIs, and then clean up before continuing. If you need to create files on disk, create them in a temporary location and/or clean them up afterwards. If your test may leave changes to the system, expect to have to clean up after a previous run that crashed, before you run your tests.

After you have written some tests, you need to verify that they pass when run on Windows. To do this locally, run make crosstest, which will use your system's mingw-w64 compiler to build a Windows executable. Run this executable on Windows in the command prompt to verify Windows's behavior. If you do not have a Windows system or VM available, you can upload your patch or test binary to the Wine Test Bot.

Once your tests pass on Windows, run them in Wine with make test. If your tests meaningfully demonstrate a Wine bug, they should fail. Now it is time to fix Wine to pass those tests, as well as all existing tests.

Working with Wine's source

As you develop your fix, there are some rules you should know if you intend to send your work upstream.

For better or worse, Wine does not have a coding style standard and likely never will. The rule is to try to match the surrounding code as best as possible. Especially in older code, you will find a horrible mish-mash of tabs and spaces and brace styles. Do your best to make the code no worse than it was. However, extraneous changes are discouraged as they make review difficult and looking up the source history in Git more cumbersome. If you are changing a line, or even one line in a short code block, it can be re-formatted to be less ugly than it was. But don't reformat an entire function to fit some style, no matter how ugly it is.

Wine only accepts code that adheres to the C89 standard, because some compilers that Wine cares about don't support anything later. The three most common snags here are that your code must declare its variables at the top of the block, you cannot use //-style comments, and function declarations with no arguments must be declared with void arguments:

    int some_function(void);

Resist the urge to gut an entire function or module and re-write it. Small, discrete changes that can be easily understood are the right way to fix Wine. Wine is more than two decades old. There is a lot of hard-won knowledge in much of Wine's source, and throwing out all of that history because it's easier than working in the existing code is not likely to pass review.

Make your changes as obviously correct as possible. Unrelated changes must be placed into their own commits. You should not introduce unused code in an early patch, which begins to be used in a later patch.

Write your patches with the reviewer in mind. It may be unintuitive, but understand that it is more important for your patch to be easy to review than make Wine's code perfect. Reviewer time is one of Wine's most valuable assets. Patches that are easier to review are more likely to pass that review.

Be aware that some tests are "flaky." This is an unfortunate reality of a system as complex as Wine. Ideally all tests would pass on all Windows and Wine environments, but due to bugs, differing platform behavior (especially window managers) and timing differences, they don't. Most modules have well-written tests that should always pass. Some, like the user32 messaging tests, and some audio and graphics tests, fail with some frequency, even on Windows.

Next: Part 6 - Sending Your Work Upstream

Once you've developed your fix, and your application now works, it's time to send it upstream. That's the topic of Part 6 - Sending Your Work Upstream.

The text of this blog post is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

>>> CodeWeavers is a major contributor to the Wine project. Read More.

About Andrew Eikum
Andrew was a former Wine developer at CodeWeavers from 2009 to 2022. He worked on all parts of Wine, but specifically supported Wine's audio. He was also a developer on many of CodeWeavers's PortJumps.