• Stars
    star
    3,657
  • Rank 12,091 (Top 0.3 %)
  • Language
    C
  • License
    MIT License
  • Created about 4 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Box64 - Linux Userspace x86_64 Emulator with a twist, targeted at ARM64 Linux devices

Official logo

Linux Userspace x86_64 Emulator with a twist

View changelog | 中文 | Українська | Report an error

build stars forks contributors prs issues


Box64 lets you run x86_64 Linux programs (such as games) on non-x86_64 Linux systems, like ARM (host system needs to be 64-bit little-endian).

You can find many Box64 videos on the MicroLinux, Pi Labs or The Byteman YouTube channels.

Since Box64 uses the native versions of some "system" libraries, like libc, libm, SDL, and OpenGL, it's easy to integrate and use with most applications, and performance can be surprisingly high in many cases. Take a look at thoses bench analysis for an example here.

Box64 integrates with DynaRec (dynamic recompiler) for the ARM64 and RV64 platform, providing a speed boost between 5 to 10 times faster than using only the interpreter. Some high level information on how DynaRec works can be found here.

Some x64 internal opcodes use parts of "Realmode X86 Emulator Library", see x64primop.c for copyright details

Logo and Icon made by @grayduck, thanks!


Usage

There are a few environment variables to control the behaviour of Box64.

See here for all the environment variables and what they do.

Note: Box64's Dynarec uses a mechanism with Memory Protection and a SegFault signal handler to handle JIT code. In simpler terms, if you want to use GDB to debug a running program that use JIT'd code (like mono/Unity3D), you will still have many "normal" segfaults triggering. It is suggested to use something like handle SIGSEGV nostop in GDB to not stop at each segfault, and maybe put a breakpoint inside my_memprotectionhandler in signals.c if you want to trap SegFaults.


Compiling/Installation

Compilation instructions can be found here
Instructions for installing Wine for Box64 can be found here


Version history/Change log

The change log is available here.


Notes about 32-bit platforms

Because Box64 works by directly translating function calls from x86_64 to host system, the host system (the one Box64 is running on) needs to have 64-bit libraries. Box64 doesn't include any 64-bit <-> 32-bit translation.

So understand that box64 will only runs 64-bit linux binaries. For 32-bit binaries, you need box86 (with all the multiarch or proot trickery it imply on 64-bit OS). Note that many installer (mojo setup based) will fall back to "x86" when detecting ARM64 OS, and so will try to use box86 for the setup, even if an x86_64 version exist. You can hack your way around with a fake "uname" that return "x86_64" when the argument is "-m"


Notes about Box64 configuration

Box64 now have configurations files. There are 2 files loaded. /etc/box4.box64rc and ~/.box64rc. Both files have the same syntax, and is basicaly an ini files. Section in square brakets define the process name, and the rest is the env. var. to set. Looke at Usage for detail on what parameters can be put. Box64 comes with a default file that should be installed for better stability. The file in in system/box64.box64rc and should be installed to /etc/box64.box64rc If, for some reasons, you don't want to install that file here, at least copy it to ~/.box64rc or some game may not function correctly. Note that the priority is: ~/.box64rc > /etc/box64.box64rc > command line So, your settings in ~/.box64rc may override the setting from your command line...


Notes about Unity game emulation

Running Unity games should just works, but you should also note that many Unity3D games require OpenGL 3+ which can be tricky to provide on ARM SBC (single-board computers). Also many newer Unity3D (like KSP) games use the BC7 compressed textures, wich is not supported on many ARM integrated GPU. Hint: on Pi4, use MESA_GL_VERSION_OVERRIDE=3.2 and with Panfrost use PAN_MESA_DEBUG=gl3 to use higher profile if the game starts then quits before showing anything.


Notes about GTK programs

GTK libraries are now wrapped on box64, both gtk2 and gtk3.


Notes about Steam

Note that Steam is a hybrid 32-bit / 64-bit. You NEED box86 to run Steam, as the client app is a 32-bit binary. It also uses a 64-bit local server binaries, and that steamwebhelper process is now mendatory, even on the "small mode". And that process will eat lots of memory. So machine with less the 6Gb of RAM will need a swapfile tp use Steam.


Notes about Wine

Wine64 is supported on box64. Proton too. Be aware that 64-bit Wine also includes 32-bit components, to be able to run 32-bit Windows programs. The 32-bit apps will need box86 and will not run without it. On a system where both box64 and box86 are present and working, a wine 64-bit setup can run both 32-bit and 64-bit Windows programs (just use wine and wine64 respectively). Note that the new 32bits PE in 64bits process that the Wine time in currently implementing in Wine 7.+ is now supported, but the support is quite young so there might be some residual issues.


Notes about Vulkan

Box64 wraps Vulkan libraries, but note that it as mostly been tested with a AMD RX550 card and on the Freedreno driver, so some extensions may be missing depending on your graphics card.


Final word

I want to thank everyone who has contributed to box64 development. There are many ways to contribute: code contribution, financial, hardware and advertisement! So, in no particular order, I want to thank:

And I also thank the many other people who participated even once in this project.

(If you use Box64 in your project, please don't forget to mention it!)

More Repositories

1

box86

Box86 - Linux Userspace x86 Emulator with a twist, targeted at ARM Linux devices
C
3,264
star
2

gl4es

GL4ES is a OpenGL 2.1/1.5 to GL ES 2.0/1.1 translation library, with support for Pandora, ODroid, OrangePI, CHIP, Raspberry PI, Android, Emscripten and AmigaOS4.
C
687
star
3

hydracastlelabyrinth

A port to Linux (and OpenPandora / DragonBox Pyra / ODroid / PocketCHIP / GameShell / AmigaOS4 / MorphOS / Emscripten) of Hydra Castle Labyrinth (a "metroidvania" kind of game). Status: Working.
C
82
star
4

stuntcarremake

A port of Stunt Car Remake to OpenPandora, Linux and Emscripten. Status: Working
C++
69
star
5

box86-compatibility-list

Box86 Compatibility List (Games and Software)
61
star
6

ctp2

Civ: CTP2 (Call to Power 2) port to Linux, Pandora and Pyra. Status: Working
C++
30
star
7

prototype

ProtoType (RType remake) version for Linux, Pandora, ODroid, AmigaOS4 and Emscripten. Status: Working.
C++
16
star
8

roadfighter

Port of Roadfighter from Brain Games to the OpenPandora, ODroid and Linux - Status: Working
C++
15
star
9

fakemodex

A simple wrapper to allow playing games that use FMODex with FMOD
C
11
star
10

friking-shark

Port of Friking Shark (remake of Flying Shark) on the OpenPandora, Odroid and most Linux. Also with AmigaOS4 support. Status: Working (using gl4es).
C
11
star
11

freespace2

Freespace & Freespace 2 sources code (from Icculus) with added support for Pandora (ARM cpu and GLES rendering). Status: Working
C++
10
star
12

GLU

libGLU for Linux, OpenPandora and Android
C
10
star
13

OpenArenaPandora

OpenArena version for OpenPandora, featuring ARM support and GLES renderer.. Status: Working
C
10
star
14

SDL2

SDL2 (with support for Pandora, and CHIP). Status: Working
C
9
star
15

zandronum

Zandronum, with ARM support. Status: working
C++
7
star
16

mupen64plus-pandora

Mupen64plus v2.0 for Pandora, with larges chunks from mupen64plus-ae from PAULSCODE. Status: Working
C++
6
star
17

SDL_sound

SDL_sound 1.0.3, with tremor support, that can be compiled for SDL 1.2 or SDL2
C
5
star
18

sais

Strange Adventure in Infinite Space for Linux and Pandora. Status: Working.
C++
5
star
19

f1spirit

F1-Spirit from BrainGames adapted to the Pandora (so ARM and GLES). Status : Working.
C++
4
star
20

bloboats

OpenPandora port of Bloboats (Float instead of Double, optional GLES 1.1 support). Status: Working
C++
4
star
21

gravitybone-pandora

Pandora port. Status: Working, Pandora works, other Linux should work with minimal changes.
C
4
star
22

RtCW-OpenPandora

Return to Castle Wolfenstein for OpenPandra (featuring ARM support and GLES renderer). Status: Working
C
4
star
23

libgsalt

Grain of SALT, the Geometry Simplification At Load Time library
C++
3
star
24

WoP-Pandora

Word of Padman for OpenPandora (featuring ARM support and GLES renderer). Status: Working
C
2
star
25

transball

Port of TransballGL to the OpenPandora (using gl4es) - Status: WIP
C++
2
star
26

CandyCrisis

Unofficial Linux and Pandora port for the OpenSource game Candy Crysis. Status: Working
C++
2
star
27

rexwb

Small tool to resample (downsample) *.xwb XNA Wave Banks
C++
1
star
28

starshatter-open

Automatically exported from code.google.com/p/starshatter-open
HTML
1
star
29

trigger-rally-pandora

Trigger Rally for OpenPandora (OpenGLES 1.1 support). Status: Working.
1
star
30

UFO--AI-OpenPandora

UFO: Alien Invasion for OpenPandora (featuring ARM support and GLES renderer). Status: Working (based on 2.4 sources)
C
1
star
31

warsow-pandora

Pandora port. Status: Working on the Pandora.
C
1
star
32

libstreamhlp

Helper Library to use Streaming extension on the OpenPandora. Status: Working
C
1
star
33

Allegro-5

Allegro 5.2 port on OpenPandra, and ODroid - Status: Looks working, need more tests
C
1
star