Mostly we code...sometimes we write. Every once in a while, we podcast.

Working on Wine Part 1 - The Wine Ecosystem

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.

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:

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

        "/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


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


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 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 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.

Creative Commons License
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.

The following comments are owned by whoever posted them. We are not responsible for them in any way.

Thank you very much for releasing this text under a CC-License. I have adopted this license to do a German translation which is at:

I also encourage all international wine-fans to do a translation in their native language.

Thank you for making this series. For the Wine compiling article, please be very detailed. I was unable to figure out how to set up a build environment for Wine. The only thing I want to do with Wine is to be able to download and test other people's patches.

Bonus idea: It would be useful if there was some kind of WineHQ or CodeWeavers service where you could upload a patch for Wine and the servers could build it for you and spit out packages. That would make it much easier for users to test Wine patches.

CodeWeavers or its third-party tools process personal data (e.g. browsing data or IP addresses) and use cookies or other identifiers, which are necessary for its functioning and required to achieve the purposes illustrated in our Privacy Policy. You accept the use of cookies or other identifiers by clicking the Acknowledge button.
Please Wait...