Wine
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
- app-emulation/wine-vanilla: Upstream Wine with no external patchsets.
- app-emulation/wine-staging: Wine with the Wine Staging patchset.
- app-emulation/wine-proton: Wine with the Valve Software patchset.
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 to depend on any app-emulation/wine-* variant
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) |
+dbus
|
Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc) |
+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 dev-util/mingw64-toolchain (more tested) rather than llvm-core/clang (newer) |
+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 |
bluetooth
|
Enable Bluetooth Support |
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 and is mostly unsupported, try disabling if have issues) |
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) |
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) |
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) |
+dbus
|
Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc) |
+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 dev-util/mingw64-toolchain (more tested) rather than llvm-core/clang (newer) |
+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 |
bluetooth
|
Enable Bluetooth Support |
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 and is mostly unsupported, try disabling if have issues) |
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) |
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) |
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) |
+dbus
|
Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc) |
+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 dev-util/mingw64-toolchain (more tested) rather than llvm-core/clang (newer) |
+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 |
+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 and is mostly unsupported, try disabling if have issues) |
custom-cflags
|
Build with user-specified CFLAGS (unsupported) |
llvm-libunwind
|
Use llvm-runtimes/libunwind instead of sys-libs/libunwind |
nls
|
Add Native Language Support (using gettext - GNU locale utilities) |
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) |
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
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.
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/wineor
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
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" winebootThe above would create a Wine prefix at /home/<user>/.wine-someprefix.
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" winebootThe 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:
- app-emulation/q4wine – Qt5 GUI configuration tool for Wine.
- app-emulation/winetricks – Easy way to install DLLs needed to work around problems in Wine.
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
/etc/portage/package.use/glibcsys-libs/glibc hash-sysv-compat
root #emerge --ask --oneshot sys-libs/glibcUpstream FAQs
Some upstream FAQ entries that users might find useful:
- How to uninstall individual applications
- How to remove a Wine prefix
- How to prevent Wine from creating menu items
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.
# 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
- Gentoo bugtracker: known bugs — Wine related bugs.
- Wine Application Database — Search for the game or program to install here to see if it is stable.
- Wine Staging at GitHub
- WineHQ Wiki
- Darling — a Darwin and macOS application comparability layer for Linux.
References
- ↑ Can't emerge dev-libs/icu[abi_x86_32], futex error? [SOLVED], Gentoo Forums. Retrieved on October 17th, 2020.