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.

Now that you have Wine built, try running it:

    $ ./wine.win64/wine winecfg

This should pop up a winecfg dialog. If not, something has gone wrong.

The wine executable in the 64-bit build directory is your primary interface for running Wine. Use it to install whatever software you are trying to get functional:

    $ cd ~/software/MyFavoriteApp/
    $ ~/src/wine.win64/wine Setup.exe

Wine prefixes

On first run, Wine sets up a virtual Windows filesystems containing a C: drive and a bunch of other files to mimic a real Windows installation. The virtual Windows filesystem is called a "prefix." The default Wine prefix is located at $HOME/.wine/. You can override this location with the WINEPREFIX environment variable. This can be useful to set up experimental prefixes which you can destroy later without affecting other prefixes.

A typical Wine prefix looks like this:

    ./dosdevices/
                 c: -> ../drive_c
                 com1 -> /dev/ttyS0
                 com2 -> /dev/ttyS1
                 com3 -> /dev/ttyS2
                 com4 -> /dev/ttyS3
                 d:: -> /dev/sr0
                 z: -> /
    ./drive_c/
              Program Files/
              users/
              windows/
    ./system.reg
    ./userdef.reg
    ./user.reg

The dosdevices folder contains DOS drives in the form of symlinks to folders or special devices. When an application tries to open C:\some_file.txt, the c: symlink here will cause Wine to instead open $WINEPREFIX/dosdevices/../drive_c/some_file.txt.

The drive_c folder is where the contents of a typical Windows installation live, like the Windows folder and the Program Files folders.

The .reg files contain Wine's representation of the Windows registry. These are stored in a format similar to the Windows regedit .reg format. Rather than use regedit, you can actually edit these files with a text editor directly to modify the registry (though you shouldn't do that while Wine is running).

The application you installed is probably located in Program Files. You can change into that directory and go poke around its files, just like you could on Windows. You can also run Wine from that directory:

    $ cd ~/.wine/drive_c/"Program Files (x86)"/Steam/
    $ ~/src/wine.win64/wine Steam.exe

If you are running applications directly like this, be mindful of your working directory. While many applications aren't sensitive to this, some assume that you launched it from the directory specified in the shortcut file that it created. This is not always the same directory in which the executable lives.

Running Wine from a build directory

If you run Wine from a build directory, like we have been here, then Wine will look up its library files from that build directory. This is as opposed to running from a system installation, where it will look up libraries in /usr/lib/wine, for example. This means that you can make changes to one Wine component, build just that one component, and then run Wine and observe the changes. No need for a top-level make or an install round trip.

Native vs built-in components

By now, you should understand that Wine is capable of running arbitrary software that was written for Windows. This includes software and libraries that Microsoft has written. Many of the components that Windows applications depend on are distributed with the application in the form of "redistributables," which contain Microsoft-written libraries. While these weren't intended for Wine, they are Windows applications like any other, so they do work in Wine.

Typically these redistributables drop DLLs into C:\windows\system32. When Wine is asked to load some DLL from system32, it will notice that these libraries are not Wine DLLs and will determine what to do on a per-library basis. The technical details of this are beyond the scope of this guide, but you can control whether Wine will prefer the Microsoft-owned DLLs (called "native") or the Wine-created DLLs (called "built-in") by using winecfg.

Since Wine tries to reimplement Microsoft code, these native libraries are by definition "correct." And unfortunately, Wine is not yet perfect. As a result, software running against native libraries will often work better than when running against Wine DLLs. This can be useful for end-users who just want to run their software.

However, you must be very careful when using native DLLs as a developer. Wine developers must never reverse-engineer actual Microsoft-owned code, and that includes using native libraries and using Wine's debugging features to determine what they are doing. There are no exceptions to this rule, so please understand the native vs built-in state of any libraries you are working on or debugging. Any developer found to be reverse-engineering in this manner may be banned from contributing to Wine. The correct way to determine the behavior of native components is to write software like any other application developer and test the behavior of those components as a black box. This will be discussed more later in these guides.

Fake DLLs and .dll.so files

On a Windows system, system libraries are installed into C:\windows\system32 (and C:\windows\syswow64 for 32-bit DLLs on a 64-bit system). Wine also installs DLLs into this directory. Some applications actually open these files directly and expect them to be valid Windows DLLs. However, Wine does not actually use the DLL file format for most of its own libraries. Instead these "fake DLLs" simply instruct Wine to load its real libraries, in whatever format is native to the underlying operating system (e.g. ELF).

As discussed above, Wine's libraries live in the build tree if you are running Wine from the build tree. They are named with the .dll.so extension. If Wine was installed someplace, then they will live in the lib/wine directory, for example in /usr/lib/wine and /usr/lib32/wine/. If you make changes to a Wine library and want to replace a single component in an existing Wine installation, you can just copy the .dll.so file into the appropriate location. Modifying the fake DLL in the Wine prefix will do nothing useful.

Tip: Virtual Desktop

Wine can be configured to run inside of a "virtual desktop." This is a single window, inside of which all of the Windows applications run. This can be extremely useful when testing fullscreen games, as this will prevent them changing the display resolution and you can still access other windows on your desktop. See the Graphics tab in winecfg.

Next: Part 4 - Debugging Wine

Now that you know how to build and run Wine, let's move on to debugging a problem you found in your application in Part 4 - Debugging Wine.

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.