{"id":13423371,"url":"https://github.com/ptitSeb/box86","last_synced_at":"2025-03-15T17:31:41.581Z","repository":{"id":37271290,"uuid":"164844546","full_name":"ptitSeb/box86","owner":"ptitSeb","description":"Box86 - Linux Userspace x86 Emulator with a twist, targeted at ARM Linux devices","archived":false,"fork":false,"pushed_at":"2024-10-09T18:25:30.000Z","size":16998,"stargazers_count":3336,"open_issues_count":166,"forks_count":230,"subscribers_count":73,"default_branch":"master","last_synced_at":"2024-10-29T15:09:56.447Z","etag":null,"topics":["arm","arm-platforms","dynarec","linux","x86"],"latest_commit_sha":null,"homepage":"https://box86.org","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ptitSeb.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ptitSeb","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":"paypal.me/0ptitSeb"}},"created_at":"2019-01-09T10:49:32.000Z","updated_at":"2024-10-29T12:19:34.000Z","dependencies_parsed_at":"2024-01-03T15:52:18.957Z","dependency_job_id":"ae5d39ab-6bfc-4d24-a0b1-39614bb3e7e1","html_url":"https://github.com/ptitSeb/box86","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptitSeb%2Fbox86","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptitSeb%2Fbox86/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptitSeb%2Fbox86/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptitSeb%2Fbox86/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ptitSeb","download_url":"https://codeload.github.com/ptitSeb/box86/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243766801,"owners_count":20344817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm","arm-platforms","dynarec","linux","x86"],"created_at":"2024-07-31T00:00:33.011Z","updated_at":"2025-03-15T17:31:41.567Z","avatar_url":"https://github.com/ptitSeb.png","language":"C","funding_links":["https://github.com/sponsors/ptitSeb","paypal.me/0ptitSeb"],"categories":["C","Computer emulators","x86 emulators"],"sub_categories":["x86 emulators","Atari Lynx"],"readme":"![Official logo](img/Box86Logo.png \"Official Logo\")\n\nLinux Userspace x86 Emulator with a twist\n\n[View changelog](https://github.com/ptitSeb/box86/blob/master/docs/CHANGELOG.md) | [中文](https://github.com/ptitSeb/box86/blob/master/docs/README_CN.md) | [Українська](https://github.com/ptitSeb/box86/blob/master/docs/README_UK.md) | [Report an error](https://github.com/ptitSeb/box86/issues/new)\n\n![build](https://app.travis-ci.com/ptitSeb/box86.svg?branch=master) ![stars](https://img.shields.io/github/stars/ptitSeb/box86) ![forks](https://img.shields.io/github/forks/ptitSeb/box86) ![contributors](https://img.shields.io/github/contributors/ptitSeb/box86) ![prs](https://img.shields.io/github/issues-pr/ptitSeb/box86) ![issues](https://img.shields.io/github/issues/ptitSeb/box86)\n\n----\n\nBox86 lets you run x86 Linux programs (such as games) on non-x86 Linux systems, like ARM (host system needs to be 32bit little-endian).\n\nYou *NEED* a 32-bit subsystem to run and build Box86. Box86 is useless on 64-bit only systems. Also, you *NEED* a 32-bit toolchain to build Box86. A toolchain that only supports 64-bit will not compile Box86, and you'll get errors (typically on aarch64, you get \"-marm\" not recognized, and you'll need a multiarch or chroot environment).\n\nBecause Box86 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 those bench analysis for an example [here](https://box86.org/index.php/2021/06/game-performances/). That also means that you will need a 32bits userspace on 64bits OS, like `armhf` on top an `aarch64` 64bits OS.\n\nMost x86 Games need OpenGL, so on ARM platforms a solution like [gl4es](https://github.com/ptitSeb/gl4es) might be necessary. (Some ARM platforms only support OpenGL ES and/or their OpenGL implementation is dodgy. (see OpenGL on Android))\n\nBox86 now integrates a DynaRec (dynamic recompiler) for the ARM platform, providing a speed boost between 5 to 10 times faster than only using the interpreter. Some high level information on how the Dynarec work can be found [here](https://box86.org/2021/07/inner-workings-a-high%e2%80%91level-view-of-box86-and-a-low%e2%80%91level-view-of-the-dynarec/).\n\nMany games just work without much tweaking, for example: WorldOfGoo, Airline Tycoon Deluxe, and FTL. Many of the GameMaker Linux games also run fine. (there's a long list, among them are UNDERTALE, A Risk of Rain, and Cook Serve Delicious). Unity3D games also works fine, but the OpenGL requirement might be an issue on some ARM platforms.\n\nIf you are serious about developing Box86, you should install ccache and build Box86 with it. (Use ccmake for example.)\nTo enable TRACE (i.e. dumping to stdout all individual x86 instructions executed, with dump of registers), you'll also need [Zydis library](https://github.com/zyantific/zydis) available on your system.\n\nSome x86 internal opcodes use parts of \"Realmode X86 Emulator Library\", see [x86primop.c](../src/emu/x86primop.c) for copyright details\n\n----\nCompiling/Installation\n----\n\u003e Compilation instructions can be found [here](https://github.com/ptitSeb/box86/blob/master/docs/COMPILE.md)  \n\u003e Instructions for installing Wine for Box86 can be found [here](https://github.com/ptitSeb/box86/blob/master/docs/X86WINE.md)  \n\n----\n\nHere are 6 videos, the first 2 videos are videos of \"Airline Tycoon Deluxe\" and \"Heretic 2\" running on a GigaHertz OpenPandora (the second one is using  the dynarec), and the next 2 videos are videos of of \"Bit.Trip.Runner\" and \"Neverwinter Night\" running on an ODroid XU4 (without dynarec), and the last 2  videos are on on a Pi4: Shovel Knight (video from @ITotalJustice) and Freedom Planet (video from @djazz), also without dynarec.\n\n[![Play on Youtube](https://img.youtube.com/vi/bLt0hMoFDLk/3.jpg)](https://www.youtube.com/watch?v=bLt0hMoFDLk) [![Play on Youtube](https://img.youtube.com/vi/MM7kWYts7IA/3.jpg)](https://www.youtube.com/watch?v=MM7kWYts7IA) [![Play on Youtube](https://img.youtube.com/vi/8hr71S029Hg/1.jpg)](https://www.youtube.com/watch?v=8hr71S029Hg) [![Play on Youtube](https://img.youtube.com/vi/B4YN37z3-ws/1.jpg)](https://www.youtube.com/watch?v=B4YN37z3-ws) [![Play on Youtube](https://img.youtube.com/vi/xk8Q30mxqPg/1.jpg)](https://www.youtube.com/watch?v=xk8Q30mxqPg) [![Play on Youtube](https://img.youtube.com/vi/_QMRMVvYrqU/1.jpg)](https://www.youtube.com/watch?v=_QMRMVvYrqU)\n\nYou can find many more Box86 videos on the [MicroLinux](https://www.youtube.com/channel/UCwFQAEj1lp3out4n7BeBatQ), [Pi Labs](https://www.youtube.com/channel/UCgfQjdc5RceRlTGfuthBs7g) or [The Byteman](https://www.youtube.com/channel/UCEr8lpIJ3B5Ctc5BvcOHSnA) YouTube channels.\n\nCompatibility list is here: https://github.com/ptitSeb/box86-compatibility-list/issues\n\n\u003cimg src=\"img/Box86Icon.png\" width=\"96\" height=\"96\"\u003e\n\nLogo and Icon made by @grayduck, thanks!\n\nNote that this project is not to be mistaken with [86box](https://github.com/86Box/86Box), a nice \"Full system\" emulator specialized in early (to fairly recent) PC hardware.\n\n----\n\nUsage\n----\n\nThere are a few environment variables to control the behaviour of Box86.\n\nSee [here](USAGE.md) for all environment variables and what they do.\n\nNote: Box86'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_box86signalhandler` in `signals.c` if you want to trap SegFaults.\n\n----\n\nVersion history\n----\n\nThe change log is available [here](CHANGELOG.md)\n\n----\n\nNotes about 64-bit platforms\n----\n\nBecause Box86 works by directly translating function calls from x86 to host system, the host system (the one Box86 is running on) needs to have 32-bit libraries. Box86 doesn't include any 32-bit \u003c-\u003e 64-bit translation. So basically, to run Box86 on, for example, an ARM64 platform, you will need to build Box86 for ARM 32-bit, and also need to have a chroot with 32-bit libraries.\n\nIf you look at a 64bits version of box86, look at [Box64](https://github.com/ptitSeb/box64): this one is able to run x86_64 binaries on 64-bit platforms. But note that you still need Box86 (and a 32-bit chroot) to run x86 binaries (as it also happens on actual x86_64 Linux that need x86 libs and binary on multiarch to run).\n\n----\n\nNotes about Box86 configuration\n----\n\nBox86 now have configurations files. There are 2 files loaded. `/etc/box4.box86rc` and `~/.box86rc`. 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](USAGE.md) for detail on what parameters can be put. Box86 comes with a default file that should be installed for better stability. The file in in `system/box86.box86rc` and should be installed to `/etc/box86.box86rc` If, for some reasons, you don't want to install that file here, at least copy it to `~/.box86rc` or some game may not function correctly.\nNote that the priority is: `~/.box86rc` \u003e `/etc/box86.box86rc` \u003e command line\nSo, your settings in `~/.box86rc` may override the setting from your command line...\n\n----\n\nNotes about Unity game emulation\n----\n\nRunning Unity games should generaly work now, but you should also note that many Unity3D games require OpenGL 3+ which can be tricky to provide on ARM SBC (single-board computers) for now.\nHint: 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.\n\n----\n\nNotes about Steam\n----\n\nLinux Steam's can run now with box86. but you also need box64 for it to completly usable.\nIt is advised to run steam in the Small mode, as it use the less memory, but steamwebhelper (a 64bits process) will still be loaded even if not used.\nThe login screen cannot run without steamwebhelper, and will just show a blank windows without box64 properly setup in the system.\nFile note, Steam will use a lot of memory, and barely fit on system with 4GB of RAM. It will not work anymore on system with less memory (as a workaround, create a swap file, login and check \"remember me\", the use box64rc to disable steamwebhelper and run only in small mode without swap after the 1st login)\nFinal note: the Steam BigPicture will work, but also need steamwebhelper (and so box64), and lots of memory. It will not start on system with only 4GB of RAM without swap.\n- If you have trouble installing Steam, you can find `install_steam.sh` in the root folder of the box86 repo. This simple script will download and install steam in your home folder, and then create a shortcut to steam in `/usr/local/bin` (and for this it will ask for sudo permission). Simply use `steam` to launch once it's installed. Note that the installation, being in the Home folder, will only work for a single user. Don't use this script if you need a multi-user installation.\n- To avoid the \"libc.so.6 is absent\" message, you can use `STEAMOS=1` and `STEAM_RUNTIME=1` as environment variables (it's automatically there if you used the `install_steam.sh` script)\n\nIf you have issue with steam starting, with `steamwebhelper` not starting, you'll need to start steam with `-cef-disable-gpu` or `-cef-disable-gpu-compositor`.\n\n----\n\nNotes about Wine\n----\n\nWine is now supported. Wine integrated program all runs, and many windows programs and games also runs fine. Don't forget most Windows games use Direct3D, this may require a complete OpenGL driver and a as high profile as possible (and gl4es with ES2 backend have issue with Wine for now).\nNote: if you plan to use box86 with Wine on Raspberry Pi 3 or earlier, those models use a default OS that have a kernel with a 2/2 Split (meaning 2G of space for user program, and 2G of space for the Kernel). This is not compatible with Wine programs that needs to access memory \u003e 2Gb address. So you'll need to reconfigure your kernel for a 3G/1G split.\n\n----\n\nNotes about Vulkan\n----\n\nBox86 already wrap Vulkan. If your system has a 32bits Vulkan driver, box86 will use it when needed. Profile 1.0, 1.1, 1.2 and 1.3, with some extensions, should be OK. DXVK, including the 2.0, works. I know some demos work on Pi4 (Sascha Willems demos build for x86 work the same as if build on armhf directly). Note that the Vulkan driver of the Pi4 DOES NOT support dxvk for now (wine DirectX-\u003eVulkan wrapper). It's not a box86 issue, it's missing extensions (hardware support) and a few other things that make dxvk not working on pi4. On Panfrost side, PanVK is a bit young and I haven't tested dxvk with it yet.\n\n----\nFinal word\n----\n\nI want to thank everyone who has contributed to box86 development.\nThere are many ways to contribute: code, financial, hardware and advertisement!\nSo, in no particular order, I want to thank:\n * For their major code contribution: rajdakin, icecream95, M-HT\n * For their major financial contribution: FlyingFathead, stormchaser3000, dennis1248, sll00, [libre-computer-project](https://libre.computer/), [CubeCoders Limited](http://cubecoders.com/)\n * For their hardware contribution: [ADLink](https://www.adlinktech.com/Products/Computer_on_Modules/COM-HPC-Server-Carrier-and-Starter-Kit/Ampere_Altra_Developer_Platform?lang=en), [Radxa](https://rockpi.org/), [Pine64](https://www.pine64.org/), [DragonBox](https://pyra-handheld.com/), [Novaspirit](https://www.youtube.com/channel/UCrjKdwxaQMSV_NDywgKXVmw), [HardKernel](https://www.hardkernel.com/), [TwisterOS team](https://twisteros.com/), [AYN](https://www.ayntec.com/)\n * For their continuous advertisement of box86 project: salva ([microLinux](https://www.youtube.com/channel/UCwFQAEj1lp3out4n7BeBatQ)), [PILab](https://www.youtube.com/channel/UCgfQjdc5RceRlTGfuthBs7g)/[TwisterOS team](https://twisteros.com/), [The Byteman](https://www.youtube.com/channel/UCEr8lpIJ3B5Ctc5BvcOHSnA), [NicoD](https://www.youtube.com/channel/UCpv7NFr0-9AB5xoklh3Snhg)\n\nAnd I also thank the many other people who participated even once in the project.\n\n(If you use Box86 in your project, please don't forget to mention it!)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FptitSeb%2Fbox86","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FptitSeb%2Fbox86","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FptitSeb%2Fbox86/lists"}