Wine

From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
Other languages:

Wine (Wine Is Not an Emulator) is an application compatibility layer that allows Microsoft Windows software to run on Linux and other POSIX-compliant operating systems. This article deals with installing, configuring, and maintaining a general purpose Wine environment on Gentoo.

Wine variants

Choosing a variant

Additional patchsets may introduce bugs that don't exist in vanilla Wine, but they may also fix others that do.

The app-emulation/wine-proton variant is only the Wine fork which is used to build Proton, and is not a stand-alone version of Proton which comes with Steam. If there are any issues with running applications with it, it would be best to test if the issues can be seen with a build of the upstream Wine as well, and then file a report to the upstream Wine project if none exists.

Installation

USE flags

USE flags for virtual/wine Virtual for Wine that supports multiple variants and slotting

proton Enable Valve Software's fork of Wine
staging Enable Wine-Staging's Patchset

USE flags for app-emulation/wine-vanilla Free implementation of Windows(tm) on Unix, without external patchsets

+X Add support for X11
+alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
+fontconfig Support for configuring and customizing font access via media-libs/fontconfig
+gecko Enable mshtml support using app-emulation/wine-gecko
+gstreamer Add support for media-libs/gstreamer (Streaming media)
+mingw Build PE files using a MinGW toolchain for better compatibility
+mono Enable .NET support using app-emulation/wine-mono
+opengl Add support for OpenGL (3D graphics)
+sdl Enable gamepad support using media-libs/libsdl2
+ssl Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
+strip Allow symbol stripping to be performed by the ebuild for special files
+truetype Add support for FreeType and/or FreeType2 fonts
+unwind Add support for call stack unwinding and function name resolution
+vkd3d Enable DirectX 12 support using app-emulation/vkd3d
+vulkan Add support for 3D graphics and computing via the Vulkan cross-platform API
+xcomposite Enable support for the Xorg composite extension
capi Enable ISDN support using net-libs/libcapi
crossdev-mingw Use sys-devel/crossdev for the toolchain rather than dev-util/mingw64-toolchain (requires manual setting up)
cups Add support for CUPS (Common Unix Printing System)
custom-cflags Build with user-specified CFLAGS (unsupported)
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
dos Pull in games-emulation/dosbox to run DOS applications
ffmpeg Enable ffmpeg/libav-based audio/video codec support
gphoto2 Add digital camera support
kerberos Add kerberos support
ldap Add LDAP support (Lightweight Directory Access Protocol)
llvm-libunwind Use llvm-runtimes/libunwind instead of sys-libs/libunwind
netapi Enable support for configuring remote shares using net-fs/samba
nls Add Native Language Support (using gettext - GNU locale utilities)
odbc Add ODBC Support (Open DataBase Connectivity)
openal Add support for the Open Audio Library
opencl Enable OpenCL support (computation on GPU)
osmesa Enable off-screen rendering (OpenGL in bitmaps) support
pcap Support packet capture software (e.g. wireshark)
perl Install helpers that require perl (winedump/winemaker)
pulseaudio Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
samba Pull in net-fs/samba with winbind for NTLM auth support
scanner Add support for scanner hardware (e.g. build the sane frontend in kdegraphics)
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
smartcard Enable smartcard support
udev Enable virtual/udev integration (device discovery, power and storage device support, etc)
udisks Enable storage management support (automounting, volume monitoring, etc)
usb Add USB support to applications that have optional USB support (e.g. cups)
v4l Enable support for video4linux (using linux-headers or userspace libv4l libraries)
wayland Enable dev-libs/wayland backend
wow64 Enable running 32bit applications without 32bit ELF multilib by mapping to 64bit calls (experimental, *may* have worse/unusable OpenGL performance or other issues compared to USE=abi_x86_32, also lacks 16bit support) -- still need dev-util/mingw64-toolchain with abi_x86_32 which itself does not need multilib
xinerama Add support for querying multi-monitor screen geometry through the Xinerama API

USE flags for app-emulation/wine-staging Free implementation of Windows(tm) on Unix, with Wine-Staging patchset

+X Add support for X11
+alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
+fontconfig Support for configuring and customizing font access via media-libs/fontconfig
+gecko Enable mshtml support using app-emulation/wine-gecko
+gstreamer Add support for media-libs/gstreamer (Streaming media)
+mingw Build PE files using a MinGW toolchain for better compatibility
+mono Enable .NET support using app-emulation/wine-mono
+opengl Add support for OpenGL (3D graphics)
+sdl Enable gamepad support using media-libs/libsdl2
+ssl Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
+strip Allow symbol stripping to be performed by the ebuild for special files
+truetype Add support for FreeType and/or FreeType2 fonts
+unwind Add support for call stack unwinding and function name resolution
+vulkan Add support for 3D graphics and computing via the Vulkan cross-platform API
+xcomposite Enable support for the Xorg composite extension
capi Enable ISDN support using net-libs/libcapi
crossdev-mingw Use sys-devel/crossdev for the toolchain rather than dev-util/mingw64-toolchain (requires manual setting up)
cups Add support for CUPS (Common Unix Printing System)
custom-cflags Build with user-specified CFLAGS (unsupported)
dos Pull in games-emulation/dosbox to run DOS applications
ffmpeg Enable ffmpeg/libav-based audio/video codec support
gphoto2 Add digital camera support
kerberos Add kerberos support
llvm-libunwind Use llvm-runtimes/libunwind instead of sys-libs/libunwind
netapi Enable support for configuring remote shares using net-fs/samba
nls Add Native Language Support (using gettext - GNU locale utilities)
odbc Add ODBC Support (Open DataBase Connectivity)
opencl Enable OpenCL support (computation on GPU)
osmesa Enable off-screen rendering (OpenGL in bitmaps) support
pcap Support packet capture software (e.g. wireshark)
perl Install helpers that require perl (winedump/winemaker)
pulseaudio Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
samba Pull in net-fs/samba with winbind for NTLM auth support
scanner Add support for scanner hardware (e.g. build the sane frontend in kdegraphics)
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
smartcard Enable smartcard support
udev Enable virtual/udev integration (device discovery, power and storage device support, etc)
udisks Enable storage management support (automounting, volume monitoring, etc)
usb Add USB support to applications that have optional USB support (e.g. cups)
v4l Enable support for video4linux (using linux-headers or userspace libv4l libraries)
wayland Enable dev-libs/wayland backend
wow64 Enable running 32bit applications without 32bit ELF multilib by mapping to 64bit calls (experimental, *may* have worse/unusable OpenGL performance or other issues compared to USE=abi_x86_32, also lacks 16bit support) -- still need dev-util/mingw64-toolchain with abi_x86_32 which itself does not need multilib
xinerama Add support for querying multi-monitor screen geometry through the Xinerama API

USE flags for app-emulation/wine-proton Valve Software's fork of Wine

+alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
+fontconfig Support for configuring and customizing font access via media-libs/fontconfig
+gecko Enable mshtml support using app-emulation/wine-gecko
+gstreamer Add support for media-libs/gstreamer (Streaming media)
+mono Enable .NET support using app-emulation/wine-mono
+sdl Enable gamepad support using media-libs/libsdl2
+ssl Add support for SSL/TLS connections (Secure Socket Layer / Transport Layer Security)
+strip Allow symbol stripping to be performed by the ebuild for special files
+unwind Add support for call stack unwinding and function name resolution
+vkd3d Enable DirectX 12 support using app-emulation/vkd3d
+xcomposite Enable support for the Xorg composite extension
crossdev-mingw Use sys-devel/crossdev for the toolchain rather than dev-util/mingw64-toolchain (requires manual setting up)
custom-cflags Build with user-specified CFLAGS (unsupported)
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
llvm-libunwind Use llvm-runtimes/libunwind instead of sys-libs/libunwind
nls Add Native Language Support (using gettext - GNU locale utilities)
openal Add support for the Open Audio Library
osmesa Enable off-screen rendering (OpenGL in bitmaps) support
perl Install helpers that require perl (winedump/winemaker)
pulseaudio Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
udev Enable virtual/udev integration (device discovery, power and storage device support, etc)
udisks Enable storage management support (automounting, volume monitoring, etc)
usb Add USB support to applications that have optional USB support (e.g. cups)
v4l Enable support for video4linux (using linux-headers or userspace libv4l libraries)
wow64 Enable running 32bit applications without 32bit ELF multilib by mapping to 64bit calls (experimental, *may* have worse/unusable OpenGL performance or other issues compared to USE=abi_x86_32, also lacks 16bit support) -- still need dev-util/mingw64-toolchain with abi_x86_32 which itself does not need multilib
xinerama Add support for querying multi-monitor screen geometry through the Xinerama API

32-bit vs 64-bit

Note
When compiling Wine with the wow64 USE-flag on a no-multilib system, the kernel config option CONFIG_IA32_EMULATION is required for the 32bit support to function.

More often than not, Windows applications will require 32-bit support. This may be true even in the case of 64-bit applications, because they can still use a 32-bit installer.

This means that a lot of dependencies of Wine will require 32-bit support as well. If not enabled for all the packages globally, using the autounmask option with emerge can be helpful with building the list.

Compiling Wine with the wow64 USE-flag enabled will enable running 32-bit applications without building Wine and its dependencies with 32-bit support enabled, but it is (at the time of writing) more or less experimental. It does work very well with a lot of applications, but is unusable with others.

Note
Some dependencies of Wine need CONFIG_COMPAT_32BIT_TIME set in the kernel config to work. Failing to do so will generate error messages of the kind: “The futex facility returned an unexpected error code.” during build or at runtime. Affected are for example the packages dev-libs/icu[1] and sys-devel/llvm.

Build-time environment variables

The live (9999) ebuilds support setting the repository branch, commit, commit date, and repo via the following environment variables:

  • EGIT_OVERRIDE_BRANCH
  • EGIT_OVERRIDE_COMMIT
  • EGIT_OVERRIDE_COMMIT_DATE
  • EGIT_OVERRIDE_REPO

As an example, one could select the WineHQ tag "wine-2.0-rc5" to emerge the 2.0 RC 5:

root #EGIT_OVERRIDE_COMMIT_WINE_WINE="wine-2.0-rc5" emerge -a '=app-emulation/wine-vanilla-9999'

One could additionally pin Wine Staging to the same release by finding the appropriate tag, "v2.0-rc5", and augmenting the previous as follows:

root #EGIT_OVERRIDE_COMMIT_WINE_WINE="wine-2.0-rc5" EGIT_OVERRIDE_COMMIT_WINE_WINE_STAGING="v2.0-rc5" emerge -a '=app-emulation/wine-staging-9999'

Other variables, which affect Wine at runtime, are discussed below.

Emerge

Enable the USE flags of your choosing on the virtual and then on the variant selected (automatically by the virtual or manually by yourself) and emerge the package:

root #emerge --ask virtual/wine

or

root #emerge --ask app-emulation/wine-${VARIANT}

Only versions classified as "stable" by upstream will be stabilized in Gentoo, and only as the app-emulation/wine-vanilla variant, as external patchsets are not considered stable. Some users may opt to add Wine variants to their package.accept_keywords file to allow for installation of development versions of Wine.

Configuration

Runtime environment variables

The environment variables of the shell that wine is started from are made accessible to the Windows/DOS processes. Some very useful Wine-specific variables include, but are not limited to, WINEPREFIX, WINEARCH, and WINEDEBUG.

See the man wine and man wineserver manual entries for more detailed information concerning Wine's environment variables.

WINEPREFIX

Important
The prefix directory (by default $HOME/.wine) is generated when Wine is executed in any way (by for example, running winecfg). This also means that, if executed as the root user (see WineHQ FAQ - Should I Run Wine as Root), a Wine prefix will (by default) be generated at /root/.wine.

To create a Wine prefix in a custom location (instead of ~/.wine) without affecting the default:

user $WINEPREFIX="$HOME/.wine-someprefix" wineboot

The above would create a Wine prefix at /home/<user>/.wine-someprefix.

Note
Once a prefix has been created, the 'bitness' (arch) can not be changed. As such, the WINEARCH should be defined the when the prefix is created if the user wants to override the default. WINEARCH is meaningless beyond prefix instantiation.

WINEARCH

To create a 32-bit installation instead of the default (when built) 64-bit:

user $WINEARCH="win32" WINEPREFIX="$HOME/.wine-someprefix" wineboot

The Wine executable used could be anything that runs Wine, such as winecfg, which often makes sense while creating a clean, new prefix.

WINEARCH requires that Wine be built with the corresponding abi_x86 flags.

WINEDEBUG

Essential in finding out why an application is misbehaving when the basic terminal output or messages boxes are not enough. See https://wiki.winehq.org/Debug_Channels for examples.

Configuration tools

The following tools include graphical and command line interfaces for managing Wine prefixes:

Graphics drivers

Graphics registry value is comma seperated string and REG_SZ type.

Driver Description
x11 Use the X11 driver
wayland Use the Wayland driver
mac Use the native quartz driver (default on macOS)
null Use the null driver (a virtual screen will be created, but not displayed; available since Wine 5.2)

Default (on linux)

user $wine cmd /c "reg add HKEY_CURRENT_USER\\Software\\Wine\\Drivers /v Graphics /t REG_SZ /d x11 /f"

For enabling only experimental wayland driver:

user $wine cmd /c "reg add HKEY_CURRENT_USER\\Software\\Wine\\Drivers /v Graphics /t REG_SZ /d wayland /f"

Easy Anti Cheat Support

Due to DT_HASH not being enabled by default since glibc 2.36 then the follow needs to be applied to allow EAC games to work

FILE /etc/portage/package.use/glibc
sys-libs/glibc hash-sysv-compat
root #emerge --ask --oneshot sys-libs/glibc

Upstream FAQs

Some upstream FAQ entries that users might find useful:

Troubleshooting

When a user encounters a problem with an application, they should try the latest development version to see if the unwanted behavior still exists. If Wine has been built with options such as -fomit-frame-pointer or --hash-style=both, the Wine developers will likely be unable to help with the issue, and reports including output from such builds should not be reported to the Wine Bugzilla.

The strip USE flag should be disabled for debugging MinGW builds.

For more directions on reporting bugs, see Bugzilla and Bugs at wiki.winehq.

Applications Crashing

Some applications such as games may crash on startup giving errors such as "page fault on read access". To mitigate this inside your wine scripts make sure you change directory to inside the game folder instead of running the game by specifying the path for it.

CODE game.sh
# Environment variables
game_dir="/path/to/game/dir/"
WINEPREFIX="${game_dir}/wineprefix/"

cd ${game_dir}
wine "game.exe"

Support

Users may find additional support in the #gentoo-wine (webchat) channel on Libera.Chat.

See also

  • DOSEMU — an application compatibility layer for MS-DOS geared more towards running MS-DOS applications than running games.
  • Game emulators — list of game emulators packaged by Gentoo-
  • Lutris — an open source gaming platform for Linux.
  • Steam — a video game digital distribution service by Valve.
  • Winetricks — an easy way to work around problems in Wine.

External resources

References