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.
The guide will be published throughout January.
- 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.
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 installprocess 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.
configurewill 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.
configurescript 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
WARNINGtext. You are strongly suggested to install these missing packages before continuing, or your Wine may be missing critical features.
$ 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
Continue installing packages and re-running
configureuntil 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
-jNflag 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
makeand go grab lunch. When it's done, you will now be able to run 64- and 32-bit Windows applications in Wine.
The last stumbling block is cross-compiling the tests so that they can be run on Windows. This isn't technically required the Wine testbot will build a patch file and run it on Windows for you—but it will greatly speed up your development process if you can build the tests locally and run them in a Windows VM that you control.
To build the crosstests, you must have mingw-w64 installed at configure-time. Availability will vary by distro. Run
make crosstestat the top-level of the Wine tree to build all of the crosstests.