Box64 Documentation

Box64 is an x86_64 Linux userspace emulator designed to run x86_64 Linux programs (such as games) on non-x86_64 Linux systems, such as ARM (provided the host system has a 64-bit endianness).

Key features:

• Uses native versions of system libraries (e.g., libc, libm, SDL, and OpenGL) for high performance and easy integration.
• Integrates with DynaRec (a dynamic recompiler) on ARM64 and RV64 platforms, providing a 5-10x speed increase over pure interpretation.
• Supports Wine64 and Proton.

If you require a debug build instead of the default RelWithDebInfo build, modify the PKGBUILD file by replacing the build type string using sed before running makepkg.

sed -i 's/RelWithDebInfo/Debug/g' ./PKGBUILD

To cross-compile Box64 (e.g., compiling for RISC-V on an x86 machine), follow these steps:

1. Set up the Cross-Compiler: Obtain a prebuilt GNU toolchain for your target architecture (e.g., from riscv-gnu-toolchain).
2. Configure CMake: Run CMake with the appropriate cross-compiler specified via -DCMAKE_C_COMPILER. Ensure the compiler version is compatible with your target's glibc version. You can check the target's glibc version by running ldd --version on the target machine.
3. Verify with QEMU (Optional): You can run the compiled binary under QEMU to verify it works. You will need to provide the path to your target's sysroot.

To run CTest-based tests under QEMU, use ctest.

Box64 supports Wine64 and Proton.

• 64-bit Windows programs: Can be run directly with Box64.
• 32-bit Windows components: Require Box86 to be installed alongside Box64.
• Experimental WOW64: You can use a Wine WOW64 build to run x86 Windows programs in Box64-only environments, which works in most cases.

To build Box64 from source, clone the repository, create a build directory, run cmake with your desired options, and then compile using make. After installation, you may need to restart systemd-binfmt to enable kernel-level executable recognition.

Note: Use make -j1 or make -j2 if you are running low on memory. If you are on a Linux kernel mixed with Android (e.g., RK3588), add -DBAD_SIGNAL=ON to your cmake command.

git clone https://github.com/ptitSeb/box64
cd box64
mkdir build; cd build; cmake .. ${OPTIONS}
make -j4
sudo make install
sudo systemctl restart systemd-binfmt

Running Unity3D games may require OpenGL 3+ and support for compressed textures like BC7 (which many ARM integrated GPUs lack).

Optimization for Raspberry Pi 4 and Pi 5: To prevent hangs and enable strong memory mode, use the following environment variables:

MESA_GL_VERSION_OVERRIDE=3.2 BOX64_DYNAREC_STRONGMEM=1

If the game starts but crashes before displaying anything, try using the Panfrost higher profile:

PAN_MESA_DEBUG=gl3

When cross-compiling, make install does not run on the target machine. Therefore, you must manually install the Box64 shared libraries required for emulation.

After cross-compiling, copy the x64lib (for x86_64) or x86lib (for i386) folder from the Box64 repository to your target device, rename it, and place it in a library search path like /usr/lib.

# For x86_64 targets:
$ mv x64lib box64-x86_64-linux-gnu
$ mv box64-x86_64-linux-gnu /usr/lib

# For i386 targets:
$ mv x86lib box64-i386-linux-gnu
$ mv box64-i386-linux-gnu /usr/lib

If you are using the regular Linux build, Box64 supports configuration files (rcfiles). Settings are applied based on priority: ~/.box64rc (highest) > /etc/box64.box64rc > environment variables.

In WowBox64 (Wine WOW64 build), the configuration file is only checked at %USERPROFILE%/.box64rc.

You can specify a custom configuration file location using the BOX64_RCFILE environment variable.

[factorio]
BOX64_DYNAREC_SAFEFLAGS=0
BOX64_DYNAREC_BIGBLOCK=2
BOX64_DYNAREC_FORWARD=1024
BOX64_DYNAREC_CALLRET=1

[*]
# Global settings apply to all applications
BOX64_DYNAREC_FASTNAN=1

Many Unity games require OpenGL 3+, which can be challenging on SBCs. Use the following environment variables to improve compatibility and stability:

• For Raspberry Pi 4 and Pi 5 users: Set MESA_GL_VERSION_OVERRIDE=3.2 and BOX64_DYNAREC_STRONGMEM=1 to prevent freezes and enable strong memory mode.
• For Panfrost users: Set PAN_MESA_DEBUG=gl3 to force a higher OpenGL Profile if games crash before displaying content.