jeremyd2019/hangover

Hangover runs simple Win32 applications on arm64 Linux

Make sure to leave a ⭐ :)

Hangover

This is Hangover, a project started by André Zwing and Stefan Dösinger in 2016 that currently can run x86_32 Windows applications on aarch64 Wine.

How it works

Hangover uses various emulators as DLLs (pick one that suits your needs, e.g. works for you) to only emulate the application you want to run instead of emulating a complete Wine installation.

As soon as the application does a Windows/Wine system call, say NtUserCreateWindowEx, it's executed outside the emulator (read non-emulated, fast, native). Even better, everything Unix related is never emulated.

In short, we break out of emulation at the win32 syscall or wine unix call level for performance reasons, which is enabled by the WoW64 support in Wine.

Status

While the overall stability was improved, expect issues.

For Benchmarks see here. They show that the Hangover approach works as expected, as only emulating the application instead of a complete Wine installation has benefits. It's especially visible with box64cpu vs. Wine running under Box64.

Current main focus is to run i386 Windows applications on ARM64 Linux, but it's also possible to run ARM32 Windows applications on x86_64 Linux. I also started working on a branch for RISC-V 64-bit Linux.

PPC64le isn't supported anymore and won't be added back in the near future. Same for running x86_64 applications, though it might be added back as soon as the ARM64EC support in Wine is ready. If you need those features, have a look at older releases before 0.8.x.

Emulator integrations:

• QEMU: Has the most issues and is by far the slowest option
• FEX: Upstream PE version plus some conveniences
• Box64: Mostly done, but depends on the early 32-bit emulation of Box64
• Blink: started, not part of this repository yet

Discord

A Discord Server is available for contributors and previous financial supporters (see "Financial Contributiors" below). It provides advanced user support, development discussions and more.

Packages

Debian 11 & 12 (also usable for Raspbian, Armbian, ...) and Ubuntu 22.04 & 23.10 & 24.04 are attached to the Github Release.

Termux packages can be found in the Termux User Repository.

Alpine package can be found in the Alpine Testing Repository. It's only hangover-wine without box64cpu.dll for now, but you can copy over box64cpu.dll and/or libwow64fex.dll from extracted debian packages or compile them yourself.

How to build

For build instructions see here.

Running

You can add the following environment variables:

• HODLL to select the emulator dll:
  • wow64cpu.dll for "native" i386 mode on x86_64
  • wowarmhw.dll for ARM emulation (Qemu)
  • xtajit.dll for i386 emulation (Qemu)
  • libwow64fex.dll for i386 emulation (FEX)
  • box64cpu.dll for i386 emulation (Box64)
• HOLIB to set full path of the library, e.g. HOLIB=/path/to/libqemu-i386.so
• QEMU_LOG to set QEMU log channels, find some options here.

Box64

box64cpu.dll currently is the default for i386 emulation, so it's simply:

$ wine your_x86_application.exe

If you have issues with the default, please try one of the other emulators below.

QEMU

Until the critical section issue is solved it is highly recomended to limit execution to 1 core with "taskset -c 1" for Qemu emulation:

$ HODLL=xtajit.dll   taskset -c 1 wine your_x86_application.exe
$ HODLL=wowarmhw.dll taskset -c 1 wine your_arm_application.exe

FEX

$ HODLL=libwow64fex.dll wine your_x86_application.exe

Known issues

• QEMU: CriticalSection doesn't work reliably and other instabilities
• FEX: Doesn't support CLI applications, as it can't handle writing to the console

Financial Contributors

I have decided to end my activities on Patreon and other platforms. It won't be the end of the project, my plan is to keep working on it, delivering new releases and updates. However, I will probably invest less time, except for the RISC-V port.