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.

What is Wine?

Wine is an open source reimplementation of Microsoft's Windows operating system on top of various Unix operating systems. It primarily targets Linux and macOS, but can also be run on other systems like FreeBSD, NetBSD, and Solaris. What this means for users is that they can run software that was made for Windows on other operating systems.

Wine does not contain any Microsoft-owned code, so there is no need for a Windows license to run Wine. Instead, the Wine developers have rewritten components of the Windows operating system such that software run in Wine will think it is running on Windows, even though it is actually running on Linux, for example.

As a simple example, consider the Windows CreateFile API. On Windows, an application could call:

    CreateFileA(
        "C:\\some_file.txt",   //lpFileName
        GENERIC_WRITE,         //dwDesiredAccess
        0,                     //dwShareMode
        NULL,                  //lpSecurityAttributes
        CREATE_ALWAYS,         //dwCreationDisposition
        FILE_ATTRIBUTE_NORMAL, //dwFlagsAndAttributes
        NULL                   //hTemplateFile
    );

Wine will take that CreateFileA call and turn it into a Unix open call:

    open(
        "/home/aeikum/.wine/drive_c/some_file.txt", //path
        O_WRONLY | O_CREAT,                         //oflag
        0644                                        //creation mode
    );

The file handle will be returned back to the application, which can then write to the file with a similar implementation mapping WriteFile to Unix's write. Of course the actual implementation of CreateFileA in Wine is far, far more complicated than this (consider the path conversion, for example), but this gives you the gist of what Wine does.

Wine Forks

Since Wine is an open source project, anyone is free to make copies of it and modify it to suit their needs or the needs of their users. There are hundreds of Wine forks, but a few of them have gained prominence and are described here.

"Upstream" Wine

Website: https://www.winehq.org/

This is the "official" version of Wine, from which all other forks are derived. When someone refers to "Upstream" Wine, they are talking about this project. Wine is primarily focused on correctness. Wine contains extensive unit tests which demonstrate the behavior of Windows, and requires that most patches provide tests. All patches must pass the existing tests to be accepted. There is also a strong focus on code quality. Wine is a very large project (it is literally an entire operating system, including a GUI), so technical debt is strongly avoided to keep the project maintainable going forward.

Wine Staging

Website: https://wiki.winehq.org/Wine-Staging

However, Wine's strict patch acceptance requirements means that lots of patches that are unproven, wrong, or dangerous, but useful for users today, would languish in private forks or on the bug tracker. The Wine Staging project (also spelled "wine-staging") is an attempt to gather and maintain these useful patches so users can easily take advantage of them. The Wine Staging community also works to upstream these patches into Wine, so their benefits become available for all Wine users and forks, while also lowering Wine Staging's own maintenance burden. It can also serve as a "testing grounds" for patches which are difficult to prove with unit tests before they are accepted upstream.

CrossOver

Website: https://www.codeweavers.com/

CrossOver is a commercial fork of Wine sold by the CodeWeavers company. It contains many patches that are application-specific hacks and not appropriate for upstreaming. CodeWeavers also maintains an application compatibility database which will pre-install some software components and otherwise modify the Wine environment so that certain applications work better. However, CodeWeavers strongly prefers to implement features correctly and send that work to upstream Wine. CodeWeavers employees perform a significant portion of the work done on Wine.

Proton

Website: https://github.com/ValveSoftware/Proton/

Proton is a fork of Wine created by the Valve software company, which is integrated with their Steam software, a major video game and software distribution platform. Proton is focused on providing a seamless experience for Steam users to run Windows titles on Linux. Like with CrossOver, most of the contributions to Proton are also sent to upstream Wine.

Other forks

There are many, many other forks of Wine. Some are packaged with commercial software and sold as macOS and Linux software. Others are one-off forks created by users for a specific application.

Developing for Wine

Wine isn't perfect, and it's likely you will run into an inadequacy or a bug in your day-to-day Wine usage. Perhaps you are interested in fixing Wine so it will run your application or game, or maybe your employer would like to use Wine and pay you to fix it. This guide will introduce you to how you can build, debug, and fix Wine, and how to send those fixes upstream.

Next: Part 2 - Wine's Build Process

You will learn how to build Wine in Part 2 - Wine's Build Process.

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 has been a Wine developer at CodeWeavers since 2009. He works on all parts of Wine, but specifically supports Wine's audio. He's also a developer on many of CodeWeavers's software ports.

About CodeWeavers
Founded in 1996 as a general software consultancy, CodeWeavers focuses on the development of Wine – the core technology found in all of its CrossOver products. The company's goal is to bring expanded market opportunities for Windows software developers by making it easier, faster and more painless to port Windows software to Mac and Linux. CodeWeavers is recognized as a leader in open-source Windows porting technology, and maintains development offices in Minnesota, the United Kingdom and elsewhere around the world. The company is privately held.