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.

Wine is effectively an operating system, including all of the libraries that a Windows system provides, such as support for 3D graphics, networking, audio, and a graphical user interface, as well as dozens of support libraries that software can use like XML parsers, file format readers and writers, multimedia playback, and much more. As such, it is a very complex piece of software. Building Wine is not a trivial task.

Much of this process depends on your particular operating system, and operating system version. This guide will not get into particulars for every operating system, but instead describe the process in general. Specific guides are available at the WineHQ Wiki.

Acquiring Wine

While you can grab the Wine source from many places, the only useful place for Wine developers is to clone the Wine Git repository.

Wine uses the typical configure && make && make install process of other autoconf-based software projects.

Choosing 32-bit or 64-bit

Microsoft Windows started shipping support for 64-bit software in the mid-2000s. Wine also has support for running 64-bit Windows software. The way this works in Wine is you effectively build it twice: once for 64-bit software and again for 32-bit software. Wine will choose the correct library architecture for a given executable at runtime.

Unfortunately, building for both architectures can be complicated on Linux. Many Linux distros have poor support for installing software for multiple architectures. Since most of the software that distros support is open source, and since open source software can be built for any architecture, there is little reason to support alternate architectures. However, the Windows software that you want to run is likely to require 32-bit support. Distros that do provide multi-arch support often do it only for Wine. To be blunt, that's a fairly small usecase, and so these 32-bit libraries are often treated as second class citizens.

macOS is even worse. Apple is dropping 32-bit support entirely sometime in 2019. No one knows exactly what this will mean for users of unsupported, 32-bit-only software, including Wine users, but it doesn't look good.

In any case, 32-bit support is required to run most Windows software, so it is effectively required if you want to build Wine. It is also strongly recommended that you build 64-bit Wine as well, since more and more Windows software is being built for the 64-bit architecture. This guide will show you how to build both.

Building modern (after 7.0) Wine requires having mingw-w64 installed at configure-time. Availability of mingw-w64 will vary by distribution. This allows Wine to build its libraries in PE format, similar to how Windows does. You can build without it, but this is strongly not recommended.

Building Wine

By default, configure will run in 32-bit-only mode. To support both 64- and 32-bit software (called "WoW64"), we want to first build 64-bit Wine and then make a build of 32-bit Wine which references the 64-bit Wine.

Wine's configure script will search your system for the libraries Wine needs to run Windows software. It takes a while to run. At the bottom of the output, it will warn you about any missing packages. Any missing packages that are critical will be marked with WARNING text. You are strongly suggested to install these missing packages before continuing, or your Wine may be missing critical features.

For example:

    $ cd src/
    $ mkdir wine.win64
    $ cd wine.win64
    $ ../wine/configure --enable-win64
    [ much truncated output ]
    configure: vkd3d 64-bit development files not found, Direct3D 12 won't be supported.
    configure: WARNING: libjpeg 64-bit development files not found, JPEG won't be supported.

You can see my system is missing the 64-bit VKD3D package. This is OK, since I don't care about Direct3D 12 support for the applications that I want to run. On the other hand, if I did want to run some Direct3D 12 games, then I would need to fix this problem and re-run configure.

However, it is also missing the libjpeg package. This is bad news. Lots of applications will require JPEG support and may behave badly if it fails, so Wine gives me a big WARNING. I should install 64-bit libjpeg and re-run configure.

Continue installing packages and re-running configure until you are happy with the missing package state. Then build Wine with make. A typical Wine build for a single architecture can take between 20 and 60 minutes, depending on the speed of your CPU and hard drive. It is strongly recommended to run make with a -jN flag appropriate to your CPU count. ccache will also significantly speed up future Wine builds. You can build Wine with ccache using CC='ccache gcc' at configure-time.

Hopefully your build will complete without errors. At this point, you can run 64-bit Windows applications. However, most Windows software does require 32-bit support at some point, often for the installer or some background process and services. So let's get a 32-bit build started, using the same process:

    cd ../
    mkdir wine.win32
    cd wine.win32
    ../wine/configure --with-wine64=../wine.win64
    [ much truncated output ]
    configure: vkd3d 32-bit development files not found, Direct3D 12 won't be supported.
    configure: WARNING: libjpeg 32-bit development files not found, JPEG won't be supported.
    configure: WARNING: libpng 32-bit development files not found, PNG won't be supported.
    configure: WARNING: libxml2 32-bit development files not found (or too old), XML won't be supported.

Oh my, far more errors here. You need to install the 32-bit versions of all of the same packages. How to do this, and what packages are available in 32-bit, is going to vary widely between distros, and we won't cover this here. Refer to the Wine Wiki for your particular distro.

Again, when you are happy with the state of your packages, run make and go grab lunch. When it's done, you will now be able to run 64- and 32-bit Windows applications in Wine.

Next: Part 3 - Using Wine as a Developer

Now that you have built Wine, it's time to move on to Part 3 - Using Wine as a Developer.

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.