Difference between revisions of "Building Wine"

From WineHQ Wiki
Jump to: navigation, search
(Initial import)
Line 10: Line 10:
To grab the source code to wine itself, just enter the following command, replacing the directory path at the end with whatever folder you want to download the source tree into:
To grab the source code to wine itself, just enter the following command, replacing the directory path at the end with whatever folder you want to download the source tree into:
git clone git://source.winehq.org/git/wine.git ~/wine-dirs/wine-source
(!) If for some reason the git protocol is blocked on your network, try using the http URL instead (http://source.winehq.org/git/wine.git).
git clone git://source.winehq.org/git/wine.git ~/wine-dirs/wine-source
If for some reason the git protocol is blocked on your network, try using the http URL instead (http://source.winehq.org/git/wine.git).
== Satisfying Build Dependencies ==
== Satisfying Build Dependencies ==

Revision as of 13:05, 16 January 2016

Interested in compiling wine from source? Want to submit some patches, run a bisection, or maybe just install a patch to make your favorite game work? You've come to the right place.



Before you compile a single line of ANSI C, there are a few things you need in order to build wine successfully.

Getting the Wine Source

You can download the Wine source code as a tarball from several places (including the Wine FTP server), but if you plan to do any actual testing or developing, you'll want to use git. For more information and some useful hints, see GitWine and the SourceCode wiki page.

To grab the source code to wine itself, just enter the following command, replacing the directory path at the end with whatever folder you want to download the source tree into:

git clone git://source.winehq.org/git/wine.git ~/wine-dirs/wine-source

If for some reason the git protocol is blocked on your network, try using the http URL instead (http://source.winehq.org/git/wine.git).

Satisfying Build Dependencies

Once you have the source code, it's time to grab all of the necessary build tools and libraries. If you have a unix with package management, probably the quickest way to find most of the software you need is to use whatever "build dependency" command your package manager offers.

Unfortunately, that by itself probably won't get everything. Dependencies for features you want may be marked as optional or not even packaged in your distro's repository. Wine is still evolving as a project too and might switch over to different libraries between versions, something that especially comes into play if you use a stable distro with spaced out releases.

(!) Check out the CategoryDistributions page to see if your distro has its own page. If it does, there are probably more tips about dependencies and compiling there.

After using package management, the surest way to figure out exactly what dependencies you still need is to start the build process & run the configure script from wine's source directory: {{{ ./configure --options }}} (or from within a distinct build directory, but more about that in the next section): {{{ relative-path/to-wine-source/configure --options }}}

If you're missing a library or program wine needs to build, the script should output a message specifically telling you what you still need to install. Ideally one run through the configure script would list all the missing software, but at least for now, the script terminates at the first check it fails. If you persist through the cycle (tedious, I know) of configure, install missing software, repeat, the script should finish and display a success message.

{i} By the way, some features of wine (legacy, experimental, etc.) aren't enabled by default but can still be built into wine with the right libraries. On a successful run, the configure script should list all disabled features and which libraries enable them. To include those features, simply install the relevant libraries, then run the configure script one more time.

Runtime Dependencies

If you actually want to run wine after you build it, you'll also need to install runtime dependencies too. The simplest way to do this for most systems is to install the wine release provided by your distro, along with all of its dependencies.

<!> If you use a very old distro, this might not work without forcing an upgrade for many of the dependencies.

At that point, as long as you give your custom wine build its own wine-prefix, you should be able to run it (from inside the build directory) alongside the official repo version without conflicts.

If you would rather uninstall your distro's version of wine, you have a few options for what to do after uninstalling it:

* Just leave the dependencies alone. The main problem with this is your package manager might mark them as unnecessary, orphaned, autoremovable, etc.
* Mark the dependencies as manually installed through your package manager. This approach only causes problems if you want to entirely remove wine and its dependencies from your system later; a command such as autoremove won't uninstall packages marked as manually installed.
* Package your custom version of wine for installation. This definitely involves the most work, but should keep your package database consistent.

Plain Vanilla Compiling

If you plan to run Wine on the same 32-bit architecture that you're building it on, then you're in luck; things should be very simple.

{i} If you just want to build Wine on common hardware with a 64-bit distro, odds are you want a [#head-51fce0c42b765db8e28b8e2d26a1ca2ea7d3c0a9 shared WoW64] build.

With all the build requirements installed:

1. Change into whatever directory you would like to build wine inside
1. From there, invoke the configure script in your wine source directory
1. After that, run {{{make}}} inside your build directory
1. If make finishes successfully, you can install wine into your system with {{{make install}}}

{{{ cd ~/wine-dirs/wine-build/ ../wine-source/configure make make install }}}

{i} The last step is purely at your discretion; you can run wine entirely from within the build directory without installation. If you do install wine through make, just be sure that you don't have a version of wine already installed. Overlapping installations shouldn't break your system, but they might seriously tangle up your libraries and package management.

Configure Options

{i} If you're on a 64-bit system, all you need to do to build a 64-bit wine is pass {{{--enable-win64}}} to the configure script when you run the above commands: {{{ ../wine-source/configure --enable-win64 }}} The problem is that by itself, that build will only run applications compiled for 64-bit Windows. Since the vast majority of Windows applications are 32-bit, you very likely want to follow the [#head-51fce0c42b765db8e28b8e2d26a1ca2ea7d3c0a9 WoW64-build] instructions below.

{i} If you want to explicitly leave out an optional feature, even if you have its dependencies installed, the configure script has many options ({{{--without-PACKAGE}}}) to disable certain libraries. There are also some options to force including libraries that normally aren't by default ({{{--with-PACKAGE}}}). A second class of options can be used to disable or enable general features in wine ({{{--disable-FEATURE}}} and {{{--enable-FEATURE}}}).

{i} If you plan on cross-compiling to a completely different architecture (not just 32-bit wine on a 64-bit system), you'll definitely want the {{{--with-wine-tools=}}} option. When you type it, just add the relative path to the tools subdirectory of a wine build compiled for your host system. Unless you include this option (or a copy of the tools are cached where the build scripts can see them), the configure script will abort with an error if you also pass a cross-compiling option.

(!) The configure script has a help flag ({{{-h}}}) that lists all relevant options and environment variables, along with a short description. The script also recognizes tab-completion so for a simple list of supported options, just type two hyphens after the {{{configure}}} command and hit tab a couple times.

{i} If for any reason you need to pass flags to the compiler while building wine, you can set them with the CFLAGS environment variable during configuration.

General Compiling Hints

(!) You're perfectly free to build and install wine from within the source directory, but using a separate build directory has many advantages. It keeps the source code uncluttered, makes testing distinct builds easier, allows for much cleaner cross-compilation, simplifies chroots or linux containers, etc.

{i} Just getting started with building software on unix? You might have heard of {{{make clean}}}. The wine makefiles also include this rule, which will automatically clean out all the intermediate object files from the build directory. However, those same object files are how {{{make}}} knows what steps it can skip if you change the source code and recompile. So if you don't want to recompile all of wine from scratch after every patch, don't disturb the object files.

{i} Maybe you've got one of those (so radically winning) solid-state drives, and you're wondering if compiling on your solid-state drive helps at all. A cruise around the internet shows mixed opinions. If you do see improvements, they'll likely be insignificant and mostly come from faster read times on the source files (processing power is the main bottleneck for compilers). At the same time, while it's not as much an issue as it used to be, solid-state drives are capable of a fixed number of write operations before wearing out. If you really want to, there are ways to have your compiler read the source code from SSD, write the temporary build files into a directory on hard-disk (or even RAM), and even move the finished program back onto the SSD (see how cool separate build directories are? B-) )

(!) Instead of looking for a SSD to speedup your compile times, consider installing ccache if you'll be building from source repeatedly. Even with {{{make}}}, it adds more sophisticated caching that can be shared across directories. For a small time penalty during your first build, it can cut compile times significantly. Unless you're using another wrapper to your compiler (which makes things more complicated), you only need to set the CC environment variable to call your compiler from ccache, which can also be done specifically for your wine build when calling the configure script. For example, if you're using GCC: {{{ ../wine-source/configure --options CC="ccache gcc" }}}

(!) If you have a multi-core processor, the {{{make}}} command has a couple of flags you might like.

* The {{{-j}}} flag tells {{{make}}} to try running independent recipes on different cores with maximum parallelism; an alternate form {{{-jN}}} will start up to N recipes in parallel:

{{{ make -j5 }}}

* Another option is the {{{-l F.F}}} flag, which only starts more recipes in parallel so long as the average system load doesn't exceed the floating-point number F.F.
* These features don't work for all projects, but they're designed to fail gracefully and revert to serial building when that happens.
* If you don't want to use your computer for anything else while building, a common rule-of-thumb is to set the N in {{{-jN}}} to the number of cores on your system + 1 (the idea behind the extra job is to keep all cores running even when one pauses for IO requests).
* Make's parallelism usually shows diminishing marginal speed-up so if you want to work on your computer while building, don't hesitate to save yourself several cores.


So compiling on the target 32-bit system is easy enough, but what if you're on a 64-bit system, or you're targeting a different architecture from your host system? Well... things get a little messier. The general idea is that you'll need to cross-compile wine for the target system, and the core problem is keeping multiple versions of the same libraries from colliding. Each architecture's version of a library needs to be kept separate from the others. Luckily, there are several techniques for doing this.

Multi-Arch and Multilib

If your first thought about cross-compilation is something like, "Why can't I just install libraries for another architecture through my package manager, then build with those?" then you aren't alone. Many unix distributions have begun adjusting how packages are installed to allow for precisely that, but there are a few different approaches.

A distribution with "multi-arch" compatibility can have several versions of a library, sorted by architecture, installed on the same system. All the tools and software provided by the distribution should also be able to correctly determine which version to use, based on context or explicit parameters from the user.

There's also a more limited form of this capability called "multilib," which only distinguishes between ABIs for a single architecture (i686 libraries on amd64 are perhaps the most prominent). A common approach to multilib is to have separate library directories for different versions (e.g. "/usr/lib32" for i686 libraries on an amd64 system), then pass parameters to a multilib-capable compiler (such as GCC or Clang) at build time.

While most up-to-date distros have multilib capabilities, multi-arch is a work in progress, and outside of the Debian Linux family, most projects don't seem to consider it a priority. If your distro can handle your specific case though, multilib/multi-arch could be the quickest and cleanest way to cross-compile. Look for your distro on the CategoryDistributions page for more info.

{i} If you've installed the necessary libraries, wine's configure script should handle multilib compiler flags for you.

{i} For developers on Debian-based distros, check out the WineMultiArch page for a list of wine dependencies that still aren't multi-arch compatible. Every package you can make multi-arch compatible helps Wine, Debian, its offspring (and probably any other distro that adopts multi-arch down the road).


If the host system can't keep track of different library versions itself, the next option is to cordon off part of the system and keep conflicting files and processes there. Over the past decade or so, kernel and filesystem-based containers have proven to be a very effective way of doing that.

This technique (also known as OS-level virtualization) strongly isolates sessions in different parts of the filesystem, while conserving resources by sharing kernel-space files and processes. While they can't contain completely different platforms, you can even theoretically run different distros in separate containers as long as they're all compatible with the same kernel (this usually takes a little tweaking though). Another major advantage of containers is that they're relatively simple to setup and use, with much fewer moving parts than a full virtual machine.

For example, to install LXC (Linux containers) on a Debian-based system and create a 32-bit Ubuntu container:

1. Install the lxc package first
1. Create a container from an i386 Ubuntu template, with your existing username and password and your home directory bind-mounted
1. Then start the container

{{{ sudo apt-get install lxc sudo lxc-create -t ubuntu -n my32bitbox -- --bindhome $LOGNAME -a i386 sudo lxc-start -n my32bitbox }}}

* If your container has the same user-space as the host, you can also copy over the apt configuration from the host (before starting the container). Otherwise, you'll probably need to manually edit those files inside the container:

{{{ sudo cp -R /etc/apt /var/lib/lxc/my32bitbox/rootfs/etc }}}

* Also, if a login prompt doesn't automatically appear when you start the container, just start a second terminal, then attach to the container and login with your normal credentials:

{{{ sudo lxc-attach -n my32bitbox login }}}

From there, all you need to do is grab the development software (e.g. git) and build dependencies, just like you did to build on the host system. Once you've set everything up, just compile wine while still inside the container.

Perhaps the main disadvantage of containers is that they typically require a whole new image of user-space for each container. As long as you have a typical computer and stable access to broadband internet, getting a system image shouldn't pose a problem though.

<!> One issue with containers, if you're just on a PC or laptop, is the way low-level processes are handled by the host. It might take some work to setup things like wi-fi, which can be a real pain if you need to install packages.

Popular Container Software:

* LXC (Linux Containers)
* Solaris/!OpenIndiana Zones
* FreeBSD Jails
* Docker


A chroot (from "change root") is the classic way of handling this problem. In fact, the virtual containers described in the last section are essentially just evolved forms of chroot. A chroot uses a minimal yet complete environment that is isolated within a subtree of the filesystem. When the chroot is activated, a session begins that is sandboxed inside the chroot part of the file system. With the exception of mounting directories outside the chroot or processes with root permissions, the session can neither see nor access the wider host system.

Chroots are sort of low-level, and like most low-level things, can be a double-edged sword... extremely flexible, but sometimes not the easiest to use. That's where a program (like schroot) that helps manage and configure all of the chroots on your system can really come in handy. Besides allowing chroot access as a normal user and simple configuration files, schroot automatically bind-mounts certain directories on the host environment for you (including $HOME by default... very convenient).

On an Ubuntu system, you can use schroot and debootstrap to install a chroot for building 32-bit wine like so:

1. Install the schroot and debootstrap packages
1. Create a schroot config file
1. Make a chroot folder and install a bare-bones version of Ubuntu in it
1. Setup the chroot's APT repository and enter the chroot
1. Install some basic packages that debootstrap skips

{{{ sudo apt-get install schroot debootstrap }}} {{{ sudo nano (or other editor) /etc/schroot/chroot.d/ubuntu_i386.conf }}}

The config file should look something like this, substituting your username on the host system, preferred chroot directory, etc.:

[ubuntu_i386] description=Ubuntu Release 32-Bit personality=linux32 directory=/srv/chroot/ubuntu_i386 root-users=your_usernamec type=directory users=your_username


{{{ sudo mkdir -p /srv/chroot/ubuntu_i386 sudo debootstrap --variant=buildd --arch=i386 vivid (or other release) /srv/chroot/ubuntu_i386 http://archive.ubuntu.com/ubuntu/ }}} {{{ sudo cp /etc/apt/sources.list /srv/chroot/ubuntu_i386/etc/apt/ schroot -c ubuntu_i386 -u root }}} {{{ apt-get update apt-get install ubuntu-minimal sudo apt-get install software-properties-common }}}

After that, just like in a container, download the necessary libraries and tools, then follow the same instructions you would to build wine on the host system.

Although there's a bit of a learning curve, chroots are a powerful technique to learn (and not just for cross-compiling). They're also lighter than virtual machines or containers because only parts of the filesystem are isolated; the chroot session can share everything else, including the kernel instance, with the host session.

However, chroots do have a couple more disadvantages. In many cases, a significant system image needs to be loaded into the chroot directory so you'll have to acquire a distro image just like you would with a container. While it's not much of an issue for cross-compiling trusted code, chroots aren't nearly as secure as other methods of sandboxing either.

Virtual Machines

As long as you have an image of your target platform, with all the build tools and libraries, you should be able to compile wine within your favorite virtual machine. You can control many virtual machines at a higher-level than containers or chroots, plus this route also leaves you with an instance of the target environment to test in, even if it's a totally different platform from your host system.

However, keep in mind that virtualization can be imperfect and introduce new bugs. If nothing interferes in the build process though, the primary downside to a virtual machine will be the performance penalty during compilation (and execution if you test wine within the virtual machine). You'll also have to account for the inconvenience of getting an image of the distro you want.

<!> Even if you can build and run wine in a VM, please don't report bugs you find unless you also see them on a native platform. Without data from a native system, we just have to assume by default that the bug is introduced by the VM. Building and running wine can be a very effective way to debug the VM software itself though.

Popular Platform Virtualization Software:

* Xen
* VirtualBox (Wine Wiki page)
* VMware (proprietary)

Shared WoW64

When Windows began targeting 64-bit architectures, Microsoft decided to include a compatibility layer to support the massive universe of lega