diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 000000000..07838e4e7 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,74 @@ +name: Lint + +on: + push: + pull_request: + types: [assigned, opened, synchronize, reopened] + +jobs: + check-line-endings: + name: Check for CRLF line endings + runs-on: ubuntu-slim + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Detect CRLF line endings + run: | + # Known CRLF files that are excluded from this check (see issue #3605) + EXCLUDED_FILES=( + "src/dynarec/arm64/arm64_printer.c" + "src/dynarec/arm64/dynarec_arm64_0f.c" + "src/dynarec/arm64/dynarec_arm64_66.c" + "src/dynarec/arm64/dynarec_arm64_660f.c" + "src/dynarec/arm64/dynarec_arm64_f20f.c" + "src/dynarec/arm64/dynarec_arm64_f30f.c" + "src/dynarec/dynarec_arch.h" + "src/dynarec/dynarec_helper.h" + "src/dynarec/native_lock.h" + "src/emu/modrm.h" + "src/emu/x64run0f.c" + "src/emu/x64run66.c" + "src/emu/x64run660f.c" + "src/emu/x64run66d9.c" + "src/emu/x64run66dd.c" + "src/emu/x64rund8.c" + "src/emu/x64rund9.c" + "src/emu/x64runda.c" + "src/emu/x64rundb.c" + "src/emu/x64rundd.c" + "src/emu/x64rundf.c" + "src/emu/x64runf0.c" + "src/emu/x64runf20f.c" + "src/emu/x64runf30f.c" + "src/include/dictionnary.h" + "src/include/globalsymbols.h" + "src/librarian/dictionnary.c" + "src/librarian/globalsymbols.c" + "src/wrapped/wrappedandroidshmem.c" + "src/wrapped/wrappedandroidshmem_private.h" + "tests/test15.c" + ) + + # Build a grep exclusion pattern + EXCLUDE_PATTERN="" + for f in "${EXCLUDED_FILES[@]}"; do + if [ -z "$EXCLUDE_PATTERN" ]; then + EXCLUDE_PATTERN="$f" + else + EXCLUDE_PATTERN="$EXCLUDE_PATTERN|$f" + fi + done + + # Find all tracked text files with CRLF, excluding known files + CRLF_FILES=$(git grep -rlI $'\r' -- . | grep -Ev "^($EXCLUDE_PATTERN)$" || true) + + if [ -n "$CRLF_FILES" ]; then + echo "::error::The following files have DOS (CRLF) line endings. Please convert them to Unix (LF) line endings:" + echo "$CRLF_FILES" + echo "" + echo "You can fix this with: sed -i 's/\r$//' or dos2unix " + exit 1 + fi + + echo "No unexpected CRLF line endings found." diff --git a/README.md b/README.md index 59debeeb8..8d3f81fc9 100644 --- a/README.md +++ b/README.md @@ -1,109 +1,109 @@ -![Official logo](docs/img/Box64Logo.png "Official Logo") - -# Box64: Linux Userspace x86-64 Emulator with a Twist - -[Website](https://box86.org/) | [Changelog](https://github.com/ptitSeb/box64/blob/main/docs/CHANGELOG.md) | [中文](https://github.com/ptitSeb/box64/blob/main/README_CN.md) | [Українська](https://github.com/ptitSeb/box64/blob/main/README_UK.md) | [Report an Error](https://github.com/ptitSeb/box64/issues/new) - -![Build Status](https://github.com/ptitSeb/box64/actions/workflows/release.yml/badge.svg) ![Stars](https://img.shields.io/github/stars/ptitSeb/box64) ![Forks](https://img.shields.io/github/forks/ptitSeb/box64) ![Contributors](https://img.shields.io/github/contributors/ptitSeb/box64) ![Pull Requests](https://img.shields.io/github/issues-pr/ptitSeb/box64) ![Issues](https://img.shields.io/github/issues/ptitSeb/box64) - ---- - -**Check out our game compatibility list at [https://box86.org/app/](https://box86.org/app/), please help us [improve it](https://github.com/ptitSeb/box86-compatibility-list/issues)!** - ---- - -Box64 enables running x86_64 Linux programs, including games, on non-x86_64 Linux systems such as Arm (64-bit little-endian host system required). - -Box64 leverages native system libraries (libc, libm, SDL, OpenGL), offering ease of integration and surprising performance in many applications. For performance benchmarks, check [this analysis](https://box86.org/index.php/2021/06/game-performances/). - -With DynaRec for Arm, RISC-V and LoongArch platforms, Box64 achieves a speed boost 5-10x faster than the interpreter alone. For a deeper look at DynaRec, see [Inner workings](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/). - -Box64 Icon - -_Logo and icon by @grayduck - Thank you!_ - ---- - -## Usage - -- `$ box64 ./program [args]` to run Linux x86_64 programs. -- `$ box64 -k` to kill all the emulated processes. -- `$ box64-bash` to have an x86_64 bash environment. -- Want to use wine? see [Wine Documentation](docs/WINE.md). - -Box64 also offers environment variables and rcfile to control its behavior. For details, see [Usage Documentation](docs/USAGE.md). - ---- - -## Compiling and Installation - -- [Compilation Instructions](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md) -- [Bundle x86 Libraries](https://github.com/ptitSeb/box64/blob/main/docs/BUNDLE-X86-LIBS.md) -- [Wine Installation for Box64](https://github.com/ptitSeb/box64/blob/main/docs/WINE.md) - ---- - -## Version History - -See the [Changelog](docs/CHANGELOG.md) for version updates. - ---- - -## Platform Compatibility Notes - -Box64 requires 64-bit libraries on the host system, as it directly translates x86_64 function calls. For 32-bit binaries, use Box86 or Box32. - -**Notes** - -1. Box32 is still experimental. -2. Some shell scripts (such as the GOG game installer) may rely on `uname -m` to determine the current architecture. Please run them as `box64 script.sh` to allow Box64 to take over. - ---- - -## Configuration - -Box64 has configuration files located in `/etc/box64.box64rc` and `~/.box64rc`, both formatted as `.ini` files. If you don’t want to use the default `/etc/box64.box64rc` file, copy it to `~/.box64rc` to ensure compatibility. - -Settings priority: `~/.box64rc` > `/etc/box64.box64rc` > Command line. - -For more information, check [Usage Documentation](docs/USAGE.md). - ---- - -## Additional Platform-Specific Notes - -### Unity Game Emulation - -- Many Unity games require OpenGL 3+, which may be challenging on ARM/RISC-V SBCs. -- **Tip for Pi4 and Pi5 Users**: Set `MESA_GL_VERSION_OVERRIDE=3.2` with `BOX64_DYNAREC_STRONGMEM=1` to prevent freezes and enable strong memory mode. -- **Using Panfrost**: For better compatibility on ARM, enable `PAN_MESA_DEBUG=gl3` to force higher OpenGL profiles. This can help if a game starts but quits unexpectedly before showing any content. - -### Steam - -See [Steam Documentation](docs/STEAM.md). - -### Wine - -Box64 supports Wine64 and Proton. For 32-bit components, Box86 is required. Systems with both Box64 and Box86 can run 32- and 64-bit Windows programs. - -**Note**: You can use Wine WOW64 build to run x86 Windows programs in Box64-only environments, this is still experimental, but it works in most cases. - -For more information, check [Wine Documentation](docs/WINE.md). - ----- -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: - * For their major code contribution: rajdakin, mogery, ksco, xctan - * For their major financial contribution: [Playtron](https://playtron.one), tohodakilla, FlyingFathead, stormchaser3000, dennis1248, sll00, [libre-computer-project](https://libre.computer/), [CubeCoders Limited](http://cubecoders.com/) - * For hardware contribution and LoongArch migration: [xiaoji](https://www.linuxgame.cn/), Deepin Beijing Develop Team - * 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) with [Ampere](https://amperecomputing.com/home/edge), [SOPHGO](https://www.sophon.ai/), [Radxa](https://rockpi.org/), [StarFive](https://rvspace.org/), [Pine64](https://www.pine64.org/), [AYN](https://www.ayntec.com/), [AYANEO](https://ayaneo.com/), [jiangcuo](https://github.com/jiangcuo) - * For their continuous advertisements for the box64 project: salva ([microLinux](https://www.youtube.com/channel/UCwFQAEj1lp3out4n7BeBatQ)), [PILab](https://www.youtube.com/channel/UCgfQjdc5RceRlTGfuthBs7g)/[TwisterOS](https://twisteros.com/) team, [The Byteman](https://www.youtube.com/channel/UCEr8lpIJ3B5Ctc5BvcOHSnA), [NicoD](https://www.youtube.com/channel/UCpv7NFr0-9AB5xoklh3Snhg), ekianjo ([Boilingsteam](https://boilingsteam.com/)) - -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!) - +![Official logo](docs/img/Box64Logo.png "Official Logo") + +# Box64: Linux Userspace x86-64 Emulator with a Twist + +[Website](https://box86.org/) | [Changelog](https://github.com/ptitSeb/box64/blob/main/docs/CHANGELOG.md) | [中文](https://github.com/ptitSeb/box64/blob/main/README_CN.md) | [Українська](https://github.com/ptitSeb/box64/blob/main/README_UK.md) | [Report an Error](https://github.com/ptitSeb/box64/issues/new) + +![Build Status](https://github.com/ptitSeb/box64/actions/workflows/release.yml/badge.svg) ![Stars](https://img.shields.io/github/stars/ptitSeb/box64) ![Forks](https://img.shields.io/github/forks/ptitSeb/box64) ![Contributors](https://img.shields.io/github/contributors/ptitSeb/box64) ![Pull Requests](https://img.shields.io/github/issues-pr/ptitSeb/box64) ![Issues](https://img.shields.io/github/issues/ptitSeb/box64) + +--- + +**Check out our game compatibility list at [https://box86.org/app/](https://box86.org/app/), please help us [improve it](https://github.com/ptitSeb/box86-compatibility-list/issues)!** + +--- + +Box64 enables running x86_64 Linux programs, including games, on non-x86_64 Linux systems such as Arm (64-bit little-endian host system required). + +Box64 leverages native system libraries (libc, libm, SDL, OpenGL), offering ease of integration and surprising performance in many applications. For performance benchmarks, check [this analysis](https://box86.org/index.php/2021/06/game-performances/). + +With DynaRec for Arm, RISC-V and LoongArch platforms, Box64 achieves a speed boost 5-10x faster than the interpreter alone. For a deeper look at DynaRec, see [Inner workings](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/). + +Box64 Icon + +_Logo and icon by @grayduck - Thank you!_ + +--- + +## Usage + +- `$ box64 ./program [args]` to run Linux x86_64 programs. +- `$ box64 -k` to kill all the emulated processes. +- `$ box64-bash` to have an x86_64 bash environment. +- Want to use wine? see [Wine Documentation](docs/WINE.md). + +Box64 also offers environment variables and rcfile to control its behavior. For details, see [Usage Documentation](docs/USAGE.md). + +--- + +## Compiling and Installation + +- [Compilation Instructions](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md) +- [Bundle x86 Libraries](https://github.com/ptitSeb/box64/blob/main/docs/BUNDLE-X86-LIBS.md) +- [Wine Installation for Box64](https://github.com/ptitSeb/box64/blob/main/docs/WINE.md) + +--- + +## Version History + +See the [Changelog](docs/CHANGELOG.md) for version updates. + +--- + +## Platform Compatibility Notes + +Box64 requires 64-bit libraries on the host system, as it directly translates x86_64 function calls. For 32-bit binaries, use Box86 or Box32. + +**Notes** + +1. Box32 is still experimental. +2. Some shell scripts (such as the GOG game installer) may rely on `uname -m` to determine the current architecture. Please run them as `box64 script.sh` to allow Box64 to take over. + +--- + +## Configuration + +Box64 has configuration files located in `/etc/box64.box64rc` and `~/.box64rc`, both formatted as `.ini` files. If you don’t want to use the default `/etc/box64.box64rc` file, copy it to `~/.box64rc` to ensure compatibility. + +Settings priority: `~/.box64rc` > `/etc/box64.box64rc` > Command line. + +For more information, check [Usage Documentation](docs/USAGE.md). + +--- + +## Additional Platform-Specific Notes + +### Unity Game Emulation + +- Many Unity games require OpenGL 3+, which may be challenging on ARM/RISC-V SBCs. +- **Tip for Pi4 and Pi5 Users**: Set `MESA_GL_VERSION_OVERRIDE=3.2` with `BOX64_DYNAREC_STRONGMEM=1` to prevent freezes and enable strong memory mode. +- **Using Panfrost**: For better compatibility on ARM, enable `PAN_MESA_DEBUG=gl3` to force higher OpenGL profiles. This can help if a game starts but quits unexpectedly before showing any content. + +### Steam + +See [Steam Documentation](docs/STEAM.md). + +### Wine + +Box64 supports Wine64 and Proton. For 32-bit components, Box86 is required. Systems with both Box64 and Box86 can run 32- and 64-bit Windows programs. + +**Note**: You can use Wine WOW64 build to run x86 Windows programs in Box64-only environments, this is still experimental, but it works in most cases. + +For more information, check [Wine Documentation](docs/WINE.md). + +---- +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: + * For their major code contribution: rajdakin, mogery, ksco, xctan + * For their major financial contribution: [Playtron](https://playtron.one), tohodakilla, FlyingFathead, stormchaser3000, dennis1248, sll00, [libre-computer-project](https://libre.computer/), [CubeCoders Limited](http://cubecoders.com/) + * For hardware contribution and LoongArch migration: [xiaoji](https://www.linuxgame.cn/), Deepin Beijing Develop Team + * 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) with [Ampere](https://amperecomputing.com/home/edge), [SOPHGO](https://www.sophon.ai/), [Radxa](https://rockpi.org/), [StarFive](https://rvspace.org/), [Pine64](https://www.pine64.org/), [AYN](https://www.ayntec.com/), [AYANEO](https://ayaneo.com/), [jiangcuo](https://github.com/jiangcuo) + * For their continuous advertisements for the box64 project: salva ([microLinux](https://www.youtube.com/channel/UCwFQAEj1lp3out4n7BeBatQ)), [PILab](https://www.youtube.com/channel/UCgfQjdc5RceRlTGfuthBs7g)/[TwisterOS](https://twisteros.com/) team, [The Byteman](https://www.youtube.com/channel/UCEr8lpIJ3B5Ctc5BvcOHSnA), [NicoD](https://www.youtube.com/channel/UCpv7NFr0-9AB5xoklh3Snhg), ekianjo ([Boilingsteam](https://boilingsteam.com/)) + +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!) + diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 424dc4316..27e59f9d1 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,484 +1,484 @@ -v0.4.0 -====== - -Highlights: -* This version added many important refactors: the opcode prefix decoder for Dynarec, libGL and Vulkan, the FSGSBASE support, making segments handling easier and faster. - => Improved compatibility accross all architecture, allowing more DRM protected game to run - => the prefix refactor helped removed lots of redundant source file, simplifying maintenance - => BOX32 is getting more and more stable, even if still not 100% ok. But Steam is more stable than before, runs on all architecture. And some gameoverlay UI works, on OpenGL games. gameoverlay (and fossilize) support for Vulkan is planned for later. - -Version summary: - -* Added new BOX64_ARCH to have settings specific to one of the supported cpu architecture (arm64, rv64, la64) -* Added BAD_PKILL build option, to workaround missing non-mandatory behaviour of pthread_kill (needed on LA64) -* Improved the handling of invalid opcodes -* Refactored handling of Selector, Segments and TLS data -* Added FSGSBASE cpu extension -* Added support for IFUNC relocation type to ElfLoader (64bits & 32bits) -* Refactored some internal behaviour to get better Interpreter only build -* Added BOX64_STEAM_VULKAN to have Vulkan renderer option injected when steamwebhelper is called -* Introduce BOX64_PYTHON3 to force using an X64 version of python (and use that on arm64 steam) -* Fixed signal handling when using Wine v10.19+ -* Added some cache to customMalloc / customFree internal functions -* Some refactor on the cpuid helper function -* Wrapping: most Wayland listener for wider compatibility -* Wrapping: refactored libGL & libVulkan wrapping -* Wrapping: more wrapped functions, reworked some existing one with wrapperhelper -* Wrapping: Added a few more wrapped libs -* Wrapping: Better handling of RTLD_NEXT in dlsym function call -* Wrapping: Reworked wrapping of pthread_one (on Box32 too) -* Wrapping: a few new syscall implemented -* Wrapping: Make BOX64_EMULATED_LIBS to also affect gstreamer hacked loading of plugins -* Wrapping: BOX32: more wrapped function and some fixes to existing ones -* Wrapping: BOX32: a few new syscall implemented -* Interpreter: Added LOCK prefix to the generic opcode prefix handling -* Interpreter: A few fixes to existing opcodes -* Interpreter: Added F3 0F 40..4F opcodes -* Dynarec: Refactored HotPages Detection & Handling -* Dynarec: Introduced DYNAREC_PURGE to allow purging of old (unused?) Dynarec block and save memory -* Dynarec: Refactored prefix decoding, similar to the Interpreter -* Dynarec: ARM64: Added detection of loops and preload of xmm/ymm regs before entering -* Dynarec: ARM64: Refactored the handling of deferred flags -* Dynarec: ARM64: A few optimisation in some existing opcodes -* DYnarec: ARM64: Some fixes to existing opcodes -* Dynarec: LA64: Added x87 opcodes -* Dynarec: LA64: Added a few missing LOCK prefixed opcodes -* Dynarec: LA64: Added some more shift/roll opcodes -* Dynarec: LA64: Added support for native CRC opcodes -* Dynarec: LA64: Many fixes to some AVX opcodes -* Dynarec: LA64: Various fixes to some opcodes -* Dynarec: LA64: Addes a few 66 prefixed opcodes -* Dynarec: LA64: Added some "simple wrapper" support (allowing direct call of wrapped functions) -* Dynarec: LA64: Added some more native flags optimisations -* Dynarec: LA64: optimized REP MOVSB -* Dynarec: RV64: Fixed/Fine tunning flags on existing opcodes -* Dynarec: RV64: Various fixes to some opcodes - -v0.3.8 -====== - -Highlights: - -* This version introduce DynaCache, a disk cache for the generated native code. It's not enabled by default for now (but it will use cache file if present by default). It can dramaticaly speedup the load of program (try with linux factorio for example). This version also improve in the volatile metadata handling. There is a massive compatiblity improvment for box32 and on all dynarec in general too. And few more function wrapping... - - => DynaCache for faster loading of program, and avoid runtime hicups - => Batter box32 compatibility (much less "Out of Memory" error) - => Unity3D games on Wayland are working now - => Volatile Metadata fully supported and handled, making games like Starfield to just work. - => More work on AVX support for RV64 & LA64. LA64 almost there, while RV64 has Scalar only support (no hardware vector support yet for AVX) - -Version summary: - -* Improved and fixed memory tracking -* Improved volatile metadata handling, and some light refactor on StrongMem emulation -* Improved handling of TF flag -* DynaCache: Introducing a way to cache on disk native generated code for faster startup time on subsequent release -* DynaCache: Support for all 3 backends ARM64, RV64 & LA64 -* Interpreter: refactor opcodes decoding to have prefixes handled in a generic way -* Interpreter: many small fixes -* Dynarec: some optimisations in the jump table, to remove one memory fetch on each jump -* Dynarec: create infrastructure to be able to change easily the reg mapping -* Dynarec: optimised defered flag handling to limit cases where UpdateFlags is needed -* Dynarec: Introduced BOX64_DYNAREC_NOHOTPAGE to disable detection of hotpages -* Dynarec: ARM64: A few more opcode added -* Dynarec: ARM64: Some small fixes and better handling of undefined behavior in opcodes, as well as undefined opcodes -* Dynarec: ARM64: Implemented a Dynarec version of UpdateFlags, for improved performances -* Dynarec; ARM64: Fixes/Improved SSE_FLUSHTO0 support -* Dynarec: LA64: Added support for AVX (& friends) opcodes. Still need some debugging so AVX still disabled by default on LA64 -* Dynarec: LA64: Changed register mapping to be closer to the x86_64 ABI -* Dynarec: LA64: RV64: Added limited support to SSE_FLUSHTO0 -* Dynarec: RV64: Many fixes and improvments for MMX opcodes -* Dynarec: RV64: many Scalar version of AVX opcodes added -* Dynarec: Many fixes to various OpCodes, on all 3 backends -* WowBox64: Added minimal runtime, improved overall stability -* BOX32: Wrapper: many new functions added, plus many fixes -* BOX32: Improved memory hadnling, using 32bits personality and other tunning to get more reliable 32bits memory allocations -* BOX64: Wrapper: some more wrapped functions added, including wayland (for Unity games on Wayland) and vulkan (more extensions) -* BOX64: Wrapper: improved handling of some VarArg wrapped functions on non-ARM64 backend -* RCFILE: Fixed MAXCPU not working properly with Wine programs -* RCFILE: Generic Setup profile refined, and more games profile added -* Trace: Added support for current libZydis - -v0.3.6 -====== - -Highlights: - -* This version introduces wowbox64.dll for Hangover; the ability to use the Volatile Metadata of Windows executables for x64 wine; and some better x87/SSE/AVX handling - - => WowBox64 can be built directly from Box64 repo, and can be found in the CI artifacts also - => it also supports a subset of BOX64_XXXX settings, which can be set from command line or via a setting file ".box64rc" in the Wine prefix home - => Volatile Metadata, when present, allows only applying strong memory ordering when needed, as marked by the compiler, giving overall better performances - => The precision control bit of x87 is now handled, allowing some older games to run correctly - => More work has been done in the handling of precise NaN and Round handling in SSE & AVX opcodes - -Version summary: - -* Added/fixed some Syscalls, helping Go programs -* Wrapper: more functions added, and some fixes too. Vulkan is 1.4 now, among other things -* Wrapper: Added a few more wrapped libs (like some avcodec and friends) -* Improve internal memory allocator (with a dedicated allocator for small memory allocations), and fixed some issues around it -* Improve internal mmaped file tracking -* Box32: Some small refactoring around memory management and internal memory allocations -* Box32: More functions wrapped -* Box32: More libraries wrapped -* ARM64: Added support for Atomic extension in many internal functions (not related to Dynarec). -* ARM64: Added support for CRC2 extension for internal CRC functions -* Interp: A few fixes to some opcodes, and better NAN handling on some selected SSE/AVX opcodes -* Interp: Added a few opcodes with exotic prefixes -* Dynarec: Introcude BOX64_DYNAREC_ROUND=2 to handle x87 precision control bit (ARM64 and RV64, LA64 still doesn't handle x87 yet) -* Dynarec: Some small optimizations on Strongmem emulation, making it more efficient -* Dynarec: Some speed optimizations on code that do SMC and waiting slot -* Dynarec: Added CALLRET=2 to improve call/ret optimization compatibility with SMC code -* Dynarec: ARM64: Various optimizations and fixes on some opcodes, especially AVX ones -* Dynarec: ARM64: Added missing FASTNAN=0 handling on some SSE/AVX opcodes -* Dynarec: ARM64: Added some exotic prefixed opcodes -* Dynarec: ARM64: Avoid purging XMM/YMM register on intra-block loop if possible -* Dynarec: RV64: Many fixes and improvments around x87 emulation -* Dynarec: RV64: Added some more missing opcodes, especially some LOCK prefixed ones and many MMX ones -* Dynarec: RV64: Various fixes on some existing opcodes -* Dynarec: RV64: Improved nativeflags handling, allowing for more cases to use it -* Dynarec: LA64: Added some more opcodes and MMX handling -* Dynarec: LA64: Various fixes to some existing opcodes -* Android: Improved signal handling, structure alignment, and transformation -* WowBox64: Created the dll, with RcFile, Env. Var. handling and log printout (both ARM64 Dynarec and Interpreter available) -* Cosim: Various fixes and improvements to limit false negatives and improve readability of logs -* RcFile: A few fixes for some values that would be ignored - -v0.3.4 -====== -* This version is Faster and more compatible: - => The RV64 backend got faster and more stable, with lots of RVV 1.0 / xThreadVector support to emulate SSE/SSE2+ opcode (no AVX yet) - => On ARM64, Box64 now support more DRM types than before. - => BOX32 can run steam now. At least on ARM64 backend, it's still not working on RV64 and LA64 for now. -* Added support to emulate Windows Syscall (needs Proton and a 48bits address space for now) -* Added BOX64_DYNAREC_DIRTY to have a faster (but less safe) way to handle code that write in it's current page -* Added a few rarely used opcodes -* Added experimental support for GDBJIT, that allow an x86/x86_64 program to be debugged on ARM/RV64/LA64 platform with x86 regs and opcode view (might generate a lot of file tho) -* Added support for Perf tools in a similar way if GDBJIT, to have an x86 fine view of the performances -* Reworked undefined flags for common operations, to be similar to real CPU -* Reworked cpuid handling, adding BOX64_CPUTYPE support to select Intel/AMD emulation (no 3DNow! support on AMD for now) -* Reworked ucontext link to be closer to the real thing (and make it more simple) -* Improved memory traking, file descriptor backed memory map, and detect wine loaded dll -* Introduced settings per library and dll (mostly for Dynarec) -* Wrapper: More functions addes, and some fixes too -* BOX32: Many fixes around pthreads wrapping -* BOX32: More functions wrapped. -* BOX32: More libraies wrapped. -* BOX32: Some reworks on how high memory (higher than 32bits) is masked, and can be used for Dynarec blocks. -* Dynarec: The usual batch of fixes, improvments and opcodes additions on all 3 supported backend -* Dynarec: Some fixes to NativeFlags handling, both on ARM64 and RV64 -* Dynarec: Added optimized REP MOVSB (expected for default CPUTYPE=0, according to new cpuid return) -* Dynarec: LA64: more opcoded addes, using hardware extensions like AES -* Dynarec: RV64: More work on using RVV 1.0 and xTheadVector extension to emulate SSE/SSE2+ opcodes -* Dynarec: RV64: Added informations on flags when building blocks, to be used when a signal happens to rebuild a x86 context more accurate -* Dynarec: ARM64: Reworked undefined flags for common operations, to be similar to real CPU -* Dynarec: ARM64: Added informations on flags and xmm/ymm/x87 register when building blocks, to be used when a signal happens to rebuild a x86 context 100% accurate -* TRACE: Reworked how trace for wrapped function call is printed. -* TRACE: Reworked logs to prefix each line with a (optionaly colored) BOX32 or BOX64 -* COSIM: Some rework on cosim to limit false negative, especialy when handling x87 operations -* LA64: Added limited support for ABI 1.0 -* CI: github CI now also generate MiceWine .rat archive, along with Winlator .wcp archive and regular linux builds. -* RCFile: Added many new games profiles (both for speed improvment or for compatibilty) - -v0.3.2 -====== -* Introduced Box32 to run 32bits apps on 64bits OS - => Box32 is a build option for Box64, and is disabled by default - => Optionnal binfmt integration available for Box32 - => Wrapped some basics libs, including graphics and sounds so a few games already works - => Work In Progress, many issues remain to be fixed, but some Linux games are playable -* Introduced Native Flags. Can be controled with BOX64_DYNAREC_NATIVEFLAGS, but enabled by default - => Available on the 3 Dynarec backend, with different implementations - => ARM64 Dynarec build have all AVX/AVX2 extensions enabled by default - +> Can lead to large speedup on certain cases -* Improved Strong Memory Model emulation, with better default options and a more efficiant emulation -* Dynarec: RV64: using RVV (and XThreadVector) to implement SSEx opcodes, with some massive speedup when used! -* Some bugfix and improvment in the Signal handler and internal memory tracking -* Improvment to TRAP signal generation and Handling -* Improved CPUID opcodes again, and the various virtual file in /proc that represent those data -* Improved some x87 operations, like long double handling and infinity comparisons... -* Dynarec: ARM64 fixes to a few opcodes -* Dynarec: RV64 fixes to many opcodes -* Dynarec: LA64 fixes to a few opcodes -* Dynarec: RV64 fixes and improvments on LOCK prefixes opcodes -* Dynarec: Many optimisation on some individual opcodes, an all 3 backends -* WRAPPING: More libs and functions wrapped. Some wrapping fixes too -* WREPPING: New wrapperhelper to help coding new wrapping & fixing/enhancing existing one -* ElfLoader: Improved object fetching -* New build profile for SD865 and ORYON -* Changed the installation folder of x86 libs to avoid conflict with linux distro -* Added a few syscalls -* Some more Vulkan extensions wrapped -* More work on build system, and github CI (generating WCP archive), with some fixes on the Android version (still not 100% operational) - -v0.3.0 -====== -* AVX and AVX2 implemented, along with BMI1, BMI2, ADX, FMA, F16C and RDANDR extension! -* Introduced BOX64_AVX env. var. to enable/disable AVX extension: - => BOX64_AVX=1 enable AVX, BMI1, F16C and VAES extension - => BOX64_AVX=2 also enable AVX2, BMI2, FMA, ADX,VPCLMULQDQ and RDRAND -* Dynarec: Implemented most AVX/AVX2 and friends in ARM64 Dynarec (using only NEON, so available on all ARM64 CPU) - => ARM64 Dynarec build have all AVX/AVX2 extensions enabled by default -* Improved CPUID opcodes, adding a few leaf, fixing same. Returnning an Haswell type of CPU now (was Pentium IV before) -* Dynarec: Small optim in the emit_pf helper, on all 3 backends -* Dynarec: ARM64 some fixes to a few opcodes -* Dynarec: LA64 many new opcodes added, and fixes. -* Dynarec: RV64 some new opcodes added, many fixes. -* Dynarec: RV64 Adding some infrastructure to use RVV (if available) for SIMD emulation. -* Dynarec: Many small changes and fixes around handling of x87, registers and internal jump. -* WRAPPING: Added a workaround on SDL_GetThreadID to fix a race condition that was happening mostly on LA64 and broke many SDL games -* WRAPPING: More libs and functions wrapped. Some wrapping fixes too (including a nasty error on some rare libGL functions) -* WRAPPING: Wayland is now supported. Wine-wayland at least works now -* Dynarec: LA64 improved LOCK CMPXCHG handling, and better 16Byte LOCK handling too (fixes many Unity3D games) -* Dynarec: RV64 improved LOCK CMPXCHG handling -* COSIM: Many fixes and improvment, to make BOX64_DYNAREC_TEST more usable -* Detect when a Wine program use UnityPlayer.dll to atumaticaly use BOX64_DYNAREC_STRONGMEM=1 (unless it's already set), so more games just work -* ElfLoader: Added a new type of relocation - -v0.2.8 -====== -* Wrapping: More libs and function wrapping (gtk3, vulkan...) -* Reworked X11 Callback handling, for better stability -* Reworked exit and the load/unload of libs and symbol resolution -* Some more profiles in box64rc -* Better way to rename executable (including wine ones) so driver like mesa can apply the correct profile -* Reworked memory managment in the Dynarec, limiting amount of dynamic allocation -* Improved memory tracking and managment. Also introduce BOX64_MMAP32 to force 32bits compatible mmap for external libs (like mesa) -=> Allow Vulkan drvier on Wine/WOW64 games to allocate 32bits compatible memory, allowing dxvk on 32bits. -* Reworked memory managment in the Dynarec, limiting amount of dynamic allocation -* Lots of improvments in x87 handling (virtual stack, rounding, ffree, etc.) -=> should improve games stability -* Dynarec: ARM64 some opcodes optimisation, especialy shift and rotation ones -* Dynarec: RV64 lots of opcoded added. -=> Some games on linux now have a good speed. Game on Wine are still a bit slow, and dxvk still have issues -* Dynarec: Added Loogarch backend! Note that Loongarch are 16K pagesize platform by default. -=> Linux games are running, and with good speed, especialy on 3A6000 platforms. Games on Wine are not working yet due to 16k pagesize limitation -* Dynarec: Better handling of large block in the dynarec -* Dynarec: Lots of improvments and fixes to BOX86_DYNAREC_CALLRET optimisation. -=> It can be used on more software now, and combine with BOX64_DYNAREC_BOGBLOCKS 2 or 3 can gives some good speed boosts. - -v0.2.6 -====== -* X64Libs: Updated libstdc++ & libgcc_s -* X64Libs: Use x86_64 vrsion of libunwind (it's needed by wine) -* Dynarec: More opcodes on ARM64 & RV64 -* Dynarec: Fixed some flags propagation issues inside blocks -* Dynarec: Improved Strong Memory Model emulation, introducing a 3rd level -* Dynarec: ARM64: reworked shift and bit opcodes flags handling -* Dynarec: RV64: Many fixes, making Wow64 apps running -* Dynarec: ARM64: Added support for SSE4.2 (with CRC32 if supported by CPU) -* Dynarec: ARM64: Added support for SHA (with hardware support if CPU allows it) -* Dynarec: ARM64: The CALLRET optimisation has been improved and is now default -* CPU: Remoworked how INT, priviliged opcodes and teh Trace flags works -* CPU: Added full support for SSE4.2 -* CPU: Added full support for SHA extension -* ElfLoader: rework how elf memory is handled -* Emulation: Added some more syscalls -* Emulation: Better handling of Signal (also handling SIGMAX correctly) -* Emulation: Better support for POKEUSER/PEEKUSER (helps Windows Unity games) -* Wrapping: More libs and some fixes in function wrapping (gtk3, vulkan...) -* Wrapping: Removed faked libunwind wrapping -* Hardware: Added more profile, with support ADLink Ampere Altra, Qualcomm 8Gen3, and Pi5 machines -* OS: Added profile to build for Android and Termux. -* OS: New option to use mold for a high speed link -=> More hadware support, more functions wrapped for an improve compatibity -=> More CPU extension, with ARM64 hardware support when possible, and improved CALLRET optimisation for an improved speed of emulation -=> Some work also to reduce the memory footprint - -v0.2.4 -====== -* Added Dynarec for RISC-V -* Added partial 32 bits support (WoW64 works) -* Changed cpuid to display box64 -* Fixed steam, again -* Improved hacked version for overridden malloc/free functions -* More wrapped libs -* More wrapped functions and syscalls -* Reduced memory footprint -* Added support for the BIND_NOW flags in ELF files -* Added RTLD_NOLOAD support -* Fixed some typos and general cleanup, again -* Added a cosimulation mode (to compare the behaviour of the dynarec with the interpreter) -* Added FASTNAN/FASTROUND handling for more opcodes -* Better float/double/long double handling -* Better dlopen/dlclose handling -* More games in the rc file -* Added BOX64_DYNAREC_MISSING to show only missing opcode, independantly of the log level -* Added BOX64_RESERVE_HIGH to reserve addresses above 47bits -* Improved multitreading support -* Ukrainian translation of the README -=> Dynarec now support RISC-V, large speedup on RISC-V 64, were games are now playable (like Stardew Valley on a Vision Five 2) -=> Improved compatibility with more fixes in elf handling, more wrapped libs and functiond, more fixed opcodes and refined profile - -v0.2.2 -====== -* Added a hacked version for overridden malloc/free functions, enabling libcef (and derivative) to work. - => Steam Large mode and new BigPicture are working - => Heroic Launcher is working -* Added rcfile handling: box64 now read `/etc/box64.box64rc` and `~/.box64rc` and apply per process parameters - => Every program can be finetuned, for speed or just to make them work -* Added BOX64_DYNAREC_CALLRET to optimized CALL/RET opcode using semi-direct native CALL/RET (get more than 10% speedup) -* Added BOX64_DYNAREC_FORWARD to allow bigger Dynarec block to be build (can get more then 30% of Speedup!) -* Improved memory protection tracking and signal handling, again -* Box64 now return a custom name for the CPU instal of P4, build with Box64 and the cpu name it's running on -* Simplified mutex handling (faster, cleaner) -* Reduce memory used by the memory tracking (memory almost divide by 4 is some critical use case) -* Added d3dadapter9 wrapping - => gallium nine is now supported on box64 too -* More wrapped libs (especially on the gtk familly) -* Improved/fixed some Syscall handling -* Refactored Strong Memory Model emulation (faster and more accurate) -* Added some more opcode to ARM64 Dynarec, and fixed some other -* Some fixes to flags handling in the Dynarec on some special cases -* Refactor library loading/unloading, with refcount. -* Some special cases fixes for dlopen (fixes deadcells, maybe others too) -* Improved mmap mapping, espcially with MAP_32BITS flag -* More wrapped functions and syscalls -* Lots of improvment in the Rounding of float & double (Dynarec and Interpreter), and proper handling of denormals when converting to/from 80 bits long double -* Added specific suppport for RK3588 board (needed some hack in signal handling, probably due to the use of a non mainlined kernel) -* More support on the RV64 port -* More support to build under musl environment - -v0.2.0 -====== -* Wrapped more vulkan function, dxvk 2.0 now works -* Added support for overridden malloc/free functions -* Refactor Dynarec memory management, reducing memory footprint (from 20% to 40% of Dynarec size) -* Improved elf loader -* Improved dlsym handling with RTLD_NEXT -* Added BOX64_DYNAREC_SAFEFLAGS to allow finetuning Dynarec generated code handling of flags accross function calls and returns. -* Added BOX64_BASH to setup x86_64 bash binary, so shell script can be run in x86_64 world -* Added BOX64_ROLLING_LOG to have details log only on crash -* Work on alignment for some of pthread structures -* More wrapped libraries in the gtk family -* Some fixes on the Dynarec x87 code (fixing a bunch of games like ut2004 or Piczle Puzzle) -* Improved TLS Size handling (Unity3D games now works) -* More PageSize Compile options -* Improved `execv` family of function to have better box64 integration -* Added support for wrapped libfuse so AppImage works -* Adjusted the binfmt integration so AppImage are automaticaly picked -* Improved FAudio, SDL2, GL (and more) wrapping -* More wrapped libs, like libEGL.so, to helps emulated Qt4/5 libs to load -* Improved Signal Handling and memory protection traking -* Some signature fixes to some wrapped functions (in libc) -* Added more syscalls -* Added a lot of new opcodes to the ARM64 Dynarec -=> Lot's of new games stat working, to name a few: Surviving Mars, Piczle Cross Adventure (using Proton experimental), UT2004, Obduction, Machinarium, Silicon Zero, Hacknet, Absolute Drift, Art of Rally, Dota2 -=> Some apps also runs now, like TeamSpeak 3 Client and Server or Discord -=> The bash integration is usefull for device with no binfmt integration or for script that check the machine it's running on - -v0.1.8 -====== -* Added an option to get generated -NAN on SSE2 operation -* Many small fixes and improvement to get SteamPlay (i.e. proton) working (along with box86) -* Added some workaround for program calling uname to mimic x86_64 system -* Added some granularity to mmap, and generic memory protection tracking improvment, to mimic x86 system (for wine stagging and proton) -* Better clone syscall and libc implementation -* Improved wrapping of GTK libs -* More wrapped libs (more gtk libs, like gstreamer-1.0 among other non-gtk libs too) -* More wrapped functions(with some tricky one, like dladdr1) -* Some fixes and improvment to some wrapped functions -* Refactor Dynarec: - * better handling of SSE/x87 registers - * optimisation to limit float/double conversion - * better handling of "internal" jump inside a dynablock - * make adding new architecture easier, by sharing as much infrastructure as possible -* Improved elfloader -* Improved some tests -* Improved a bit the "Hotpage" handling and messages -* Added more dynarec opcodes -* A few fixes in some Dynarec opcodes -* A bit more optimisation in some Dynarec opcodes -* Don't quit on unsupported syscall, return -1 / ENOSYS error -* Added some more Syscall -* Wrapped Vulkan library. Vulkan and dxvk now supported! -* Support building on PPC64LE (interpreter only) -* Added support for Risc-V (interpreter only) - -v0.1.6 -====== -* Introduce "HotPage", to temporarily disable Dynarec on a page were writing is also occuring (can help speed up C# code) -* Some work on Dynarec to limit the number of mutex use, and also allow smaller block to be built (for JIT'd programs) -* Introduce BOX64_DYNAREC_STRONGMEM for the (Arm) dynarec to emulate StrngMemory Model (needed by some games, like RimWorld) -* More functions wrapped -* Improve speed of the custom allocator used by dynarec and Hash (speedup loading) -* Added a workaround for streamwebhelper to not load it -* More opcodes added -* More wrapped libraries, including gtk2 -* Added a fix for linking box64 on system using glibc 2.34+ -* Some residual fixes on thread attribute handling -* Better handling of app that want 32bits jumps, like unity3d/mono (thanks mogery) -* More ARM hardware option in CMake (Phytium, NX...) -* Added loongarch64 support (interpreter only) -* Some fixes to elfloader -* Added a mecanism to cancel a Dynarec block construction if it triggers a segfault (instead of a crash) - -v0.1.4 -====== -* Reworked README a bit -* Added some more wrapped libs -* Added some SSE4x opcodes -* Preliminary support for VSyscall (still missing VDSO) -* Added support for AES-NI cpu extension, also in Dynarec (and using ARM extension if present) -* Added some syscall -* Added some more wrapped functions -* Improvment to the handling of longjmp inside signal handlers -* Improved wrapper helpers (from rajdakin) -* Some fixes to opcodes (especially C2 flags for some x87 opcodes) -* Handling of some specific opcode as privileged instruction (instead of NOP) -* Fixed ELF signature detection -* Some fixes to a few env. var. handling - -v0.1.2 -====== -* OpenSource! -* A few more opcode added to the Interpreter and the Dynarec -* Improved Native Function calling -* Added some function to limit allocated memory to 47bits space (for Wine) -* Improved and Fixed the functions to limit allocated memory to 32bits space -* Wine is starting now, but not everything and every version works - -v0.1.0 -====== -* Improvement to ElfLoader -* More opcode added to the Dynarec -* More lib wrapping -* Some fixes to a few function signature -* Improvement to Signal handling, and internal mutex handling -* A few fixes to some dynarec opcodes -* A few fixes to some interpreter opcodes - -v0.0.8 -====== -* Improvement to SSE/x87 handling -* More opcode added to the Dynarec -* More lib wrapping - -v0.0.6 -====== -* Added Dynarec for ARM64 -* Many general CPU opcode added to the Dynarec -* Many SSEx opcodes added to the Dynarec -* Added a few more symbols in libc -* A few changes to the "thread once" handling -* New Logo and Icon from @grayduck - -v0.0.4 -====== -* Added a lot of opcodes -* Added SDL1 and SDL2 wrapping -* OpenGL/GLU wrapping done -* libasound / libpulse wrapping done -* libopenal / libalure / libalut wrapping done -* Many X11 libs wrapped -* Added "install" with binfmt integration -* A few games are actualy starting now (old WorldOfGoo, Into The Breach, VVVVVV and Thimbeweed Park) - -v0.0.2 -====== -* Using box86 as a base, implemented most planned box64 part except dynarec -* Wrapped a few libs -* ELF loader a bit crude, but seems working -* Signal handling implemented -* MMX and x87 are sharing their registers +v0.4.0 +====== + +Highlights: +* This version added many important refactors: the opcode prefix decoder for Dynarec, libGL and Vulkan, the FSGSBASE support, making segments handling easier and faster. + => Improved compatibility accross all architecture, allowing more DRM protected game to run + => the prefix refactor helped removed lots of redundant source file, simplifying maintenance + => BOX32 is getting more and more stable, even if still not 100% ok. But Steam is more stable than before, runs on all architecture. And some gameoverlay UI works, on OpenGL games. gameoverlay (and fossilize) support for Vulkan is planned for later. + +Version summary: + +* Added new BOX64_ARCH to have settings specific to one of the supported cpu architecture (arm64, rv64, la64) +* Added BAD_PKILL build option, to workaround missing non-mandatory behaviour of pthread_kill (needed on LA64) +* Improved the handling of invalid opcodes +* Refactored handling of Selector, Segments and TLS data +* Added FSGSBASE cpu extension +* Added support for IFUNC relocation type to ElfLoader (64bits & 32bits) +* Refactored some internal behaviour to get better Interpreter only build +* Added BOX64_STEAM_VULKAN to have Vulkan renderer option injected when steamwebhelper is called +* Introduce BOX64_PYTHON3 to force using an X64 version of python (and use that on arm64 steam) +* Fixed signal handling when using Wine v10.19+ +* Added some cache to customMalloc / customFree internal functions +* Some refactor on the cpuid helper function +* Wrapping: most Wayland listener for wider compatibility +* Wrapping: refactored libGL & libVulkan wrapping +* Wrapping: more wrapped functions, reworked some existing one with wrapperhelper +* Wrapping: Added a few more wrapped libs +* Wrapping: Better handling of RTLD_NEXT in dlsym function call +* Wrapping: Reworked wrapping of pthread_one (on Box32 too) +* Wrapping: a few new syscall implemented +* Wrapping: Make BOX64_EMULATED_LIBS to also affect gstreamer hacked loading of plugins +* Wrapping: BOX32: more wrapped function and some fixes to existing ones +* Wrapping: BOX32: a few new syscall implemented +* Interpreter: Added LOCK prefix to the generic opcode prefix handling +* Interpreter: A few fixes to existing opcodes +* Interpreter: Added F3 0F 40..4F opcodes +* Dynarec: Refactored HotPages Detection & Handling +* Dynarec: Introduced DYNAREC_PURGE to allow purging of old (unused?) Dynarec block and save memory +* Dynarec: Refactored prefix decoding, similar to the Interpreter +* Dynarec: ARM64: Added detection of loops and preload of xmm/ymm regs before entering +* Dynarec: ARM64: Refactored the handling of deferred flags +* Dynarec: ARM64: A few optimisation in some existing opcodes +* DYnarec: ARM64: Some fixes to existing opcodes +* Dynarec: LA64: Added x87 opcodes +* Dynarec: LA64: Added a few missing LOCK prefixed opcodes +* Dynarec: LA64: Added some more shift/roll opcodes +* Dynarec: LA64: Added support for native CRC opcodes +* Dynarec: LA64: Many fixes to some AVX opcodes +* Dynarec: LA64: Various fixes to some opcodes +* Dynarec: LA64: Addes a few 66 prefixed opcodes +* Dynarec: LA64: Added some "simple wrapper" support (allowing direct call of wrapped functions) +* Dynarec: LA64: Added some more native flags optimisations +* Dynarec: LA64: optimized REP MOVSB +* Dynarec: RV64: Fixed/Fine tunning flags on existing opcodes +* Dynarec: RV64: Various fixes to some opcodes + +v0.3.8 +====== + +Highlights: + +* This version introduce DynaCache, a disk cache for the generated native code. It's not enabled by default for now (but it will use cache file if present by default). It can dramaticaly speedup the load of program (try with linux factorio for example). This version also improve in the volatile metadata handling. There is a massive compatiblity improvment for box32 and on all dynarec in general too. And few more function wrapping... + + => DynaCache for faster loading of program, and avoid runtime hicups + => Batter box32 compatibility (much less "Out of Memory" error) + => Unity3D games on Wayland are working now + => Volatile Metadata fully supported and handled, making games like Starfield to just work. + => More work on AVX support for RV64 & LA64. LA64 almost there, while RV64 has Scalar only support (no hardware vector support yet for AVX) + +Version summary: + +* Improved and fixed memory tracking +* Improved volatile metadata handling, and some light refactor on StrongMem emulation +* Improved handling of TF flag +* DynaCache: Introducing a way to cache on disk native generated code for faster startup time on subsequent release +* DynaCache: Support for all 3 backends ARM64, RV64 & LA64 +* Interpreter: refactor opcodes decoding to have prefixes handled in a generic way +* Interpreter: many small fixes +* Dynarec: some optimisations in the jump table, to remove one memory fetch on each jump +* Dynarec: create infrastructure to be able to change easily the reg mapping +* Dynarec: optimised defered flag handling to limit cases where UpdateFlags is needed +* Dynarec: Introduced BOX64_DYNAREC_NOHOTPAGE to disable detection of hotpages +* Dynarec: ARM64: A few more opcode added +* Dynarec: ARM64: Some small fixes and better handling of undefined behavior in opcodes, as well as undefined opcodes +* Dynarec: ARM64: Implemented a Dynarec version of UpdateFlags, for improved performances +* Dynarec; ARM64: Fixes/Improved SSE_FLUSHTO0 support +* Dynarec: LA64: Added support for AVX (& friends) opcodes. Still need some debugging so AVX still disabled by default on LA64 +* Dynarec: LA64: Changed register mapping to be closer to the x86_64 ABI +* Dynarec: LA64: RV64: Added limited support to SSE_FLUSHTO0 +* Dynarec: RV64: Many fixes and improvments for MMX opcodes +* Dynarec: RV64: many Scalar version of AVX opcodes added +* Dynarec: Many fixes to various OpCodes, on all 3 backends +* WowBox64: Added minimal runtime, improved overall stability +* BOX32: Wrapper: many new functions added, plus many fixes +* BOX32: Improved memory hadnling, using 32bits personality and other tunning to get more reliable 32bits memory allocations +* BOX64: Wrapper: some more wrapped functions added, including wayland (for Unity games on Wayland) and vulkan (more extensions) +* BOX64: Wrapper: improved handling of some VarArg wrapped functions on non-ARM64 backend +* RCFILE: Fixed MAXCPU not working properly with Wine programs +* RCFILE: Generic Setup profile refined, and more games profile added +* Trace: Added support for current libZydis + +v0.3.6 +====== + +Highlights: + +* This version introduces wowbox64.dll for Hangover; the ability to use the Volatile Metadata of Windows executables for x64 wine; and some better x87/SSE/AVX handling + + => WowBox64 can be built directly from Box64 repo, and can be found in the CI artifacts also + => it also supports a subset of BOX64_XXXX settings, which can be set from command line or via a setting file ".box64rc" in the Wine prefix home + => Volatile Metadata, when present, allows only applying strong memory ordering when needed, as marked by the compiler, giving overall better performances + => The precision control bit of x87 is now handled, allowing some older games to run correctly + => More work has been done in the handling of precise NaN and Round handling in SSE & AVX opcodes + +Version summary: + +* Added/fixed some Syscalls, helping Go programs +* Wrapper: more functions added, and some fixes too. Vulkan is 1.4 now, among other things +* Wrapper: Added a few more wrapped libs (like some avcodec and friends) +* Improve internal memory allocator (with a dedicated allocator for small memory allocations), and fixed some issues around it +* Improve internal mmaped file tracking +* Box32: Some small refactoring around memory management and internal memory allocations +* Box32: More functions wrapped +* Box32: More libraries wrapped +* ARM64: Added support for Atomic extension in many internal functions (not related to Dynarec). +* ARM64: Added support for CRC2 extension for internal CRC functions +* Interp: A few fixes to some opcodes, and better NAN handling on some selected SSE/AVX opcodes +* Interp: Added a few opcodes with exotic prefixes +* Dynarec: Introcude BOX64_DYNAREC_ROUND=2 to handle x87 precision control bit (ARM64 and RV64, LA64 still doesn't handle x87 yet) +* Dynarec: Some small optimizations on Strongmem emulation, making it more efficient +* Dynarec: Some speed optimizations on code that do SMC and waiting slot +* Dynarec: Added CALLRET=2 to improve call/ret optimization compatibility with SMC code +* Dynarec: ARM64: Various optimizations and fixes on some opcodes, especially AVX ones +* Dynarec: ARM64: Added missing FASTNAN=0 handling on some SSE/AVX opcodes +* Dynarec: ARM64: Added some exotic prefixed opcodes +* Dynarec: ARM64: Avoid purging XMM/YMM register on intra-block loop if possible +* Dynarec: RV64: Many fixes and improvments around x87 emulation +* Dynarec: RV64: Added some more missing opcodes, especially some LOCK prefixed ones and many MMX ones +* Dynarec: RV64: Various fixes on some existing opcodes +* Dynarec: RV64: Improved nativeflags handling, allowing for more cases to use it +* Dynarec: LA64: Added some more opcodes and MMX handling +* Dynarec: LA64: Various fixes to some existing opcodes +* Android: Improved signal handling, structure alignment, and transformation +* WowBox64: Created the dll, with RcFile, Env. Var. handling and log printout (both ARM64 Dynarec and Interpreter available) +* Cosim: Various fixes and improvements to limit false negatives and improve readability of logs +* RcFile: A few fixes for some values that would be ignored + +v0.3.4 +====== +* This version is Faster and more compatible: + => The RV64 backend got faster and more stable, with lots of RVV 1.0 / xThreadVector support to emulate SSE/SSE2+ opcode (no AVX yet) + => On ARM64, Box64 now support more DRM types than before. + => BOX32 can run steam now. At least on ARM64 backend, it's still not working on RV64 and LA64 for now. +* Added support to emulate Windows Syscall (needs Proton and a 48bits address space for now) +* Added BOX64_DYNAREC_DIRTY to have a faster (but less safe) way to handle code that write in it's current page +* Added a few rarely used opcodes +* Added experimental support for GDBJIT, that allow an x86/x86_64 program to be debugged on ARM/RV64/LA64 platform with x86 regs and opcode view (might generate a lot of file tho) +* Added support for Perf tools in a similar way if GDBJIT, to have an x86 fine view of the performances +* Reworked undefined flags for common operations, to be similar to real CPU +* Reworked cpuid handling, adding BOX64_CPUTYPE support to select Intel/AMD emulation (no 3DNow! support on AMD for now) +* Reworked ucontext link to be closer to the real thing (and make it more simple) +* Improved memory traking, file descriptor backed memory map, and detect wine loaded dll +* Introduced settings per library and dll (mostly for Dynarec) +* Wrapper: More functions addes, and some fixes too +* BOX32: Many fixes around pthreads wrapping +* BOX32: More functions wrapped. +* BOX32: More libraies wrapped. +* BOX32: Some reworks on how high memory (higher than 32bits) is masked, and can be used for Dynarec blocks. +* Dynarec: The usual batch of fixes, improvments and opcodes additions on all 3 supported backend +* Dynarec: Some fixes to NativeFlags handling, both on ARM64 and RV64 +* Dynarec: Added optimized REP MOVSB (expected for default CPUTYPE=0, according to new cpuid return) +* Dynarec: LA64: more opcoded addes, using hardware extensions like AES +* Dynarec: RV64: More work on using RVV 1.0 and xTheadVector extension to emulate SSE/SSE2+ opcodes +* Dynarec: RV64: Added informations on flags when building blocks, to be used when a signal happens to rebuild a x86 context more accurate +* Dynarec: ARM64: Reworked undefined flags for common operations, to be similar to real CPU +* Dynarec: ARM64: Added informations on flags and xmm/ymm/x87 register when building blocks, to be used when a signal happens to rebuild a x86 context 100% accurate +* TRACE: Reworked how trace for wrapped function call is printed. +* TRACE: Reworked logs to prefix each line with a (optionaly colored) BOX32 or BOX64 +* COSIM: Some rework on cosim to limit false negative, especialy when handling x87 operations +* LA64: Added limited support for ABI 1.0 +* CI: github CI now also generate MiceWine .rat archive, along with Winlator .wcp archive and regular linux builds. +* RCFile: Added many new games profiles (both for speed improvment or for compatibilty) + +v0.3.2 +====== +* Introduced Box32 to run 32bits apps on 64bits OS + => Box32 is a build option for Box64, and is disabled by default + => Optionnal binfmt integration available for Box32 + => Wrapped some basics libs, including graphics and sounds so a few games already works + => Work In Progress, many issues remain to be fixed, but some Linux games are playable +* Introduced Native Flags. Can be controled with BOX64_DYNAREC_NATIVEFLAGS, but enabled by default + => Available on the 3 Dynarec backend, with different implementations + => ARM64 Dynarec build have all AVX/AVX2 extensions enabled by default + +> Can lead to large speedup on certain cases +* Improved Strong Memory Model emulation, with better default options and a more efficiant emulation +* Dynarec: RV64: using RVV (and XThreadVector) to implement SSEx opcodes, with some massive speedup when used! +* Some bugfix and improvment in the Signal handler and internal memory tracking +* Improvment to TRAP signal generation and Handling +* Improved CPUID opcodes again, and the various virtual file in /proc that represent those data +* Improved some x87 operations, like long double handling and infinity comparisons... +* Dynarec: ARM64 fixes to a few opcodes +* Dynarec: RV64 fixes to many opcodes +* Dynarec: LA64 fixes to a few opcodes +* Dynarec: RV64 fixes and improvments on LOCK prefixes opcodes +* Dynarec: Many optimisation on some individual opcodes, an all 3 backends +* WRAPPING: More libs and functions wrapped. Some wrapping fixes too +* WREPPING: New wrapperhelper to help coding new wrapping & fixing/enhancing existing one +* ElfLoader: Improved object fetching +* New build profile for SD865 and ORYON +* Changed the installation folder of x86 libs to avoid conflict with linux distro +* Added a few syscalls +* Some more Vulkan extensions wrapped +* More work on build system, and github CI (generating WCP archive), with some fixes on the Android version (still not 100% operational) + +v0.3.0 +====== +* AVX and AVX2 implemented, along with BMI1, BMI2, ADX, FMA, F16C and RDANDR extension! +* Introduced BOX64_AVX env. var. to enable/disable AVX extension: + => BOX64_AVX=1 enable AVX, BMI1, F16C and VAES extension + => BOX64_AVX=2 also enable AVX2, BMI2, FMA, ADX,VPCLMULQDQ and RDRAND +* Dynarec: Implemented most AVX/AVX2 and friends in ARM64 Dynarec (using only NEON, so available on all ARM64 CPU) + => ARM64 Dynarec build have all AVX/AVX2 extensions enabled by default +* Improved CPUID opcodes, adding a few leaf, fixing same. Returnning an Haswell type of CPU now (was Pentium IV before) +* Dynarec: Small optim in the emit_pf helper, on all 3 backends +* Dynarec: ARM64 some fixes to a few opcodes +* Dynarec: LA64 many new opcodes added, and fixes. +* Dynarec: RV64 some new opcodes added, many fixes. +* Dynarec: RV64 Adding some infrastructure to use RVV (if available) for SIMD emulation. +* Dynarec: Many small changes and fixes around handling of x87, registers and internal jump. +* WRAPPING: Added a workaround on SDL_GetThreadID to fix a race condition that was happening mostly on LA64 and broke many SDL games +* WRAPPING: More libs and functions wrapped. Some wrapping fixes too (including a nasty error on some rare libGL functions) +* WRAPPING: Wayland is now supported. Wine-wayland at least works now +* Dynarec: LA64 improved LOCK CMPXCHG handling, and better 16Byte LOCK handling too (fixes many Unity3D games) +* Dynarec: RV64 improved LOCK CMPXCHG handling +* COSIM: Many fixes and improvment, to make BOX64_DYNAREC_TEST more usable +* Detect when a Wine program use UnityPlayer.dll to atumaticaly use BOX64_DYNAREC_STRONGMEM=1 (unless it's already set), so more games just work +* ElfLoader: Added a new type of relocation + +v0.2.8 +====== +* Wrapping: More libs and function wrapping (gtk3, vulkan...) +* Reworked X11 Callback handling, for better stability +* Reworked exit and the load/unload of libs and symbol resolution +* Some more profiles in box64rc +* Better way to rename executable (including wine ones) so driver like mesa can apply the correct profile +* Reworked memory managment in the Dynarec, limiting amount of dynamic allocation +* Improved memory tracking and managment. Also introduce BOX64_MMAP32 to force 32bits compatible mmap for external libs (like mesa) +=> Allow Vulkan drvier on Wine/WOW64 games to allocate 32bits compatible memory, allowing dxvk on 32bits. +* Reworked memory managment in the Dynarec, limiting amount of dynamic allocation +* Lots of improvments in x87 handling (virtual stack, rounding, ffree, etc.) +=> should improve games stability +* Dynarec: ARM64 some opcodes optimisation, especialy shift and rotation ones +* Dynarec: RV64 lots of opcoded added. +=> Some games on linux now have a good speed. Game on Wine are still a bit slow, and dxvk still have issues +* Dynarec: Added Loogarch backend! Note that Loongarch are 16K pagesize platform by default. +=> Linux games are running, and with good speed, especialy on 3A6000 platforms. Games on Wine are not working yet due to 16k pagesize limitation +* Dynarec: Better handling of large block in the dynarec +* Dynarec: Lots of improvments and fixes to BOX86_DYNAREC_CALLRET optimisation. +=> It can be used on more software now, and combine with BOX64_DYNAREC_BOGBLOCKS 2 or 3 can gives some good speed boosts. + +v0.2.6 +====== +* X64Libs: Updated libstdc++ & libgcc_s +* X64Libs: Use x86_64 vrsion of libunwind (it's needed by wine) +* Dynarec: More opcodes on ARM64 & RV64 +* Dynarec: Fixed some flags propagation issues inside blocks +* Dynarec: Improved Strong Memory Model emulation, introducing a 3rd level +* Dynarec: ARM64: reworked shift and bit opcodes flags handling +* Dynarec: RV64: Many fixes, making Wow64 apps running +* Dynarec: ARM64: Added support for SSE4.2 (with CRC32 if supported by CPU) +* Dynarec: ARM64: Added support for SHA (with hardware support if CPU allows it) +* Dynarec: ARM64: The CALLRET optimisation has been improved and is now default +* CPU: Remoworked how INT, priviliged opcodes and teh Trace flags works +* CPU: Added full support for SSE4.2 +* CPU: Added full support for SHA extension +* ElfLoader: rework how elf memory is handled +* Emulation: Added some more syscalls +* Emulation: Better handling of Signal (also handling SIGMAX correctly) +* Emulation: Better support for POKEUSER/PEEKUSER (helps Windows Unity games) +* Wrapping: More libs and some fixes in function wrapping (gtk3, vulkan...) +* Wrapping: Removed faked libunwind wrapping +* Hardware: Added more profile, with support ADLink Ampere Altra, Qualcomm 8Gen3, and Pi5 machines +* OS: Added profile to build for Android and Termux. +* OS: New option to use mold for a high speed link +=> More hadware support, more functions wrapped for an improve compatibity +=> More CPU extension, with ARM64 hardware support when possible, and improved CALLRET optimisation for an improved speed of emulation +=> Some work also to reduce the memory footprint + +v0.2.4 +====== +* Added Dynarec for RISC-V +* Added partial 32 bits support (WoW64 works) +* Changed cpuid to display box64 +* Fixed steam, again +* Improved hacked version for overridden malloc/free functions +* More wrapped libs +* More wrapped functions and syscalls +* Reduced memory footprint +* Added support for the BIND_NOW flags in ELF files +* Added RTLD_NOLOAD support +* Fixed some typos and general cleanup, again +* Added a cosimulation mode (to compare the behaviour of the dynarec with the interpreter) +* Added FASTNAN/FASTROUND handling for more opcodes +* Better float/double/long double handling +* Better dlopen/dlclose handling +* More games in the rc file +* Added BOX64_DYNAREC_MISSING to show only missing opcode, independantly of the log level +* Added BOX64_RESERVE_HIGH to reserve addresses above 47bits +* Improved multitreading support +* Ukrainian translation of the README +=> Dynarec now support RISC-V, large speedup on RISC-V 64, were games are now playable (like Stardew Valley on a Vision Five 2) +=> Improved compatibility with more fixes in elf handling, more wrapped libs and functiond, more fixed opcodes and refined profile + +v0.2.2 +====== +* Added a hacked version for overridden malloc/free functions, enabling libcef (and derivative) to work. + => Steam Large mode and new BigPicture are working + => Heroic Launcher is working +* Added rcfile handling: box64 now read `/etc/box64.box64rc` and `~/.box64rc` and apply per process parameters + => Every program can be finetuned, for speed or just to make them work +* Added BOX64_DYNAREC_CALLRET to optimized CALL/RET opcode using semi-direct native CALL/RET (get more than 10% speedup) +* Added BOX64_DYNAREC_FORWARD to allow bigger Dynarec block to be build (can get more then 30% of Speedup!) +* Improved memory protection tracking and signal handling, again +* Box64 now return a custom name for the CPU instal of P4, build with Box64 and the cpu name it's running on +* Simplified mutex handling (faster, cleaner) +* Reduce memory used by the memory tracking (memory almost divide by 4 is some critical use case) +* Added d3dadapter9 wrapping + => gallium nine is now supported on box64 too +* More wrapped libs (especially on the gtk familly) +* Improved/fixed some Syscall handling +* Refactored Strong Memory Model emulation (faster and more accurate) +* Added some more opcode to ARM64 Dynarec, and fixed some other +* Some fixes to flags handling in the Dynarec on some special cases +* Refactor library loading/unloading, with refcount. +* Some special cases fixes for dlopen (fixes deadcells, maybe others too) +* Improved mmap mapping, espcially with MAP_32BITS flag +* More wrapped functions and syscalls +* Lots of improvment in the Rounding of float & double (Dynarec and Interpreter), and proper handling of denormals when converting to/from 80 bits long double +* Added specific suppport for RK3588 board (needed some hack in signal handling, probably due to the use of a non mainlined kernel) +* More support on the RV64 port +* More support to build under musl environment + +v0.2.0 +====== +* Wrapped more vulkan function, dxvk 2.0 now works +* Added support for overridden malloc/free functions +* Refactor Dynarec memory management, reducing memory footprint (from 20% to 40% of Dynarec size) +* Improved elf loader +* Improved dlsym handling with RTLD_NEXT +* Added BOX64_DYNAREC_SAFEFLAGS to allow finetuning Dynarec generated code handling of flags accross function calls and returns. +* Added BOX64_BASH to setup x86_64 bash binary, so shell script can be run in x86_64 world +* Added BOX64_ROLLING_LOG to have details log only on crash +* Work on alignment for some of pthread structures +* More wrapped libraries in the gtk family +* Some fixes on the Dynarec x87 code (fixing a bunch of games like ut2004 or Piczle Puzzle) +* Improved TLS Size handling (Unity3D games now works) +* More PageSize Compile options +* Improved `execv` family of function to have better box64 integration +* Added support for wrapped libfuse so AppImage works +* Adjusted the binfmt integration so AppImage are automaticaly picked +* Improved FAudio, SDL2, GL (and more) wrapping +* More wrapped libs, like libEGL.so, to helps emulated Qt4/5 libs to load +* Improved Signal Handling and memory protection traking +* Some signature fixes to some wrapped functions (in libc) +* Added more syscalls +* Added a lot of new opcodes to the ARM64 Dynarec +=> Lot's of new games stat working, to name a few: Surviving Mars, Piczle Cross Adventure (using Proton experimental), UT2004, Obduction, Machinarium, Silicon Zero, Hacknet, Absolute Drift, Art of Rally, Dota2 +=> Some apps also runs now, like TeamSpeak 3 Client and Server or Discord +=> The bash integration is usefull for device with no binfmt integration or for script that check the machine it's running on + +v0.1.8 +====== +* Added an option to get generated -NAN on SSE2 operation +* Many small fixes and improvement to get SteamPlay (i.e. proton) working (along with box86) +* Added some workaround for program calling uname to mimic x86_64 system +* Added some granularity to mmap, and generic memory protection tracking improvment, to mimic x86 system (for wine stagging and proton) +* Better clone syscall and libc implementation +* Improved wrapping of GTK libs +* More wrapped libs (more gtk libs, like gstreamer-1.0 among other non-gtk libs too) +* More wrapped functions(with some tricky one, like dladdr1) +* Some fixes and improvment to some wrapped functions +* Refactor Dynarec: + * better handling of SSE/x87 registers + * optimisation to limit float/double conversion + * better handling of "internal" jump inside a dynablock + * make adding new architecture easier, by sharing as much infrastructure as possible +* Improved elfloader +* Improved some tests +* Improved a bit the "Hotpage" handling and messages +* Added more dynarec opcodes +* A few fixes in some Dynarec opcodes +* A bit more optimisation in some Dynarec opcodes +* Don't quit on unsupported syscall, return -1 / ENOSYS error +* Added some more Syscall +* Wrapped Vulkan library. Vulkan and dxvk now supported! +* Support building on PPC64LE (interpreter only) +* Added support for Risc-V (interpreter only) + +v0.1.6 +====== +* Introduce "HotPage", to temporarily disable Dynarec on a page were writing is also occuring (can help speed up C# code) +* Some work on Dynarec to limit the number of mutex use, and also allow smaller block to be built (for JIT'd programs) +* Introduce BOX64_DYNAREC_STRONGMEM for the (Arm) dynarec to emulate StrngMemory Model (needed by some games, like RimWorld) +* More functions wrapped +* Improve speed of the custom allocator used by dynarec and Hash (speedup loading) +* Added a workaround for streamwebhelper to not load it +* More opcodes added +* More wrapped libraries, including gtk2 +* Added a fix for linking box64 on system using glibc 2.34+ +* Some residual fixes on thread attribute handling +* Better handling of app that want 32bits jumps, like unity3d/mono (thanks mogery) +* More ARM hardware option in CMake (Phytium, NX...) +* Added loongarch64 support (interpreter only) +* Some fixes to elfloader +* Added a mecanism to cancel a Dynarec block construction if it triggers a segfault (instead of a crash) + +v0.1.4 +====== +* Reworked README a bit +* Added some more wrapped libs +* Added some SSE4x opcodes +* Preliminary support for VSyscall (still missing VDSO) +* Added support for AES-NI cpu extension, also in Dynarec (and using ARM extension if present) +* Added some syscall +* Added some more wrapped functions +* Improvment to the handling of longjmp inside signal handlers +* Improved wrapper helpers (from rajdakin) +* Some fixes to opcodes (especially C2 flags for some x87 opcodes) +* Handling of some specific opcode as privileged instruction (instead of NOP) +* Fixed ELF signature detection +* Some fixes to a few env. var. handling + +v0.1.2 +====== +* OpenSource! +* A few more opcode added to the Interpreter and the Dynarec +* Improved Native Function calling +* Added some function to limit allocated memory to 47bits space (for Wine) +* Improved and Fixed the functions to limit allocated memory to 32bits space +* Wine is starting now, but not everything and every version works + +v0.1.0 +====== +* Improvement to ElfLoader +* More opcode added to the Dynarec +* More lib wrapping +* Some fixes to a few function signature +* Improvement to Signal handling, and internal mutex handling +* A few fixes to some dynarec opcodes +* A few fixes to some interpreter opcodes + +v0.0.8 +====== +* Improvement to SSE/x87 handling +* More opcode added to the Dynarec +* More lib wrapping + +v0.0.6 +====== +* Added Dynarec for ARM64 +* Many general CPU opcode added to the Dynarec +* Many SSEx opcodes added to the Dynarec +* Added a few more symbols in libc +* A few changes to the "thread once" handling +* New Logo and Icon from @grayduck + +v0.0.4 +====== +* Added a lot of opcodes +* Added SDL1 and SDL2 wrapping +* OpenGL/GLU wrapping done +* libasound / libpulse wrapping done +* libopenal / libalure / libalut wrapping done +* Many X11 libs wrapped +* Added "install" with binfmt integration +* A few games are actualy starting now (old WorldOfGoo, Into The Breach, VVVVVV and Thimbeweed Park) + +v0.0.2 +====== +* Using box86 as a base, implemented most planned box64 part except dynarec +* Wrapped a few libs +* ELF loader a bit crude, but seems working +* Signal handling implemented +* MMX and x87 are sharing their registers diff --git a/docs/COMPILE.md b/docs/COMPILE.md index 0f48e86ff..53fdbcec7 100644 --- a/docs/COMPILE.md +++ b/docs/COMPILE.md @@ -1,403 +1,403 @@ -Compiling/Installing ----- - -If you don't want to compile box64 yourself and prefer to use third-party pre-build version, go to the [end of the document](#pre-built-packages) for alternatives. - -You can also generate your own package using the [instructions below](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md#debian-packaging). - -Additional installation steps may be necessary when copying only the box64 executable file without running make install in cross-build environments. See [Cross-Compiling](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md#Cross-Compiling) - -## Per-platform compiling instructions - -### The general approach - -``` -git clone https://github.com/ptitSeb/box64 -cd box64 -mkdir build; cd build; cmake .. ${OPTIONS} -make -j4 -sudo make install -``` -If it's the first install, you also need: -``` -sudo systemctl restart systemd-binfmt -``` -- You can use `make -j1`, `make -j2` with less jobs to prevent running out of memory -- You can also add `-DBAD_SIGNAL=ON` to the cmake command if you are on a Linux Kernel mixed with Android, like on RK3588. - -### Note about Box32 - -If you want to build Box64 with the Box32 option, you will need to add `-DBOX32=ON` to the cmake command. That will enable 32bits process to be run with Box64. -If you also want binfmt integration on 32bits binaries, you also need to add `-DBOX32_BINFMT=ON` to the cmake command. - -### Note about WowBox64 - -A highly experimantal subproject named WowBox64 has been added as a build option, add `-DWOW64=ON` to the cmake command to enable it. -It will build alongside the regular Box64, and produce a `wowbox64.dll` file in `build/wowbox64-prefix/src/wowbox64-build/` directory. - -### Note about binfmt_misc on Android - -[binfmt_misc](https://en.wikipedia.org/wiki/Binfmt_misc) is a capability of the Linux kernel which allows arbitrary executable file formats to be recognized and passed to certain user space applications such as Box64 usually used with systemd but systems like Android can't run/use systemd so you will need to register Box64 manually, this will also work inside a CHRoot. -``` -sudo mount -t binfmt_misc none /proc/sys/fs/binfmt_misc -sudo echo ':box64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x3e\x00:\xff\xff\xff\xff\xff\xff\xff\x00\x00\x00\x00\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/local/bin/box64:' | sudo tee /proc/sys/fs/binfmt_misc/register -``` - - -#### Example of generic ARM64 build for linux platforms - -``` -git clone https://github.com/ptitSeb/box64 -cd box64 -mkdir build; cd build; cmake .. -D ARM_DYNAREC=ON -D CMAKE_BUILD_TYPE=RelWithDebInfo -make -j4 -sudo make install -sudo systemctl restart systemd-binfmt -``` - -#### Example of generic ARM64 build for linux platforms with full box32 integration - -``` -git clone https://github.com/ptitSeb/box64 -cd box64 -mkdir build; cd build; cmake .. -D ARM_DYNAREC=ON -D CMAKE_BUILD_TYPE=RelWithDebInfo -D BOX32=ON -D BOX32_BINFMT=ON -make -j4 -sudo make install -sudo systemctl restart systemd-binfmt -``` - ----- - -#### for RK3399 - -On a 64bit OS: -``` --D RK3399=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for RK3588 / RK3588S - -On a 64bit OS: -``` --D RK3588=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for Raspberry Pi 3 - -On a 64bit OS: - -If building on the Pi, you will also need a large swap (3 GB+) -[optionally reduce GPU memory to a minimum (e.g. 16 MB) using `raspi-config` -(and reboot) before starting the build]: - -You can use e.g. '`make -j4`' to speed up the build, but on a Pi 3 with 1GB memory you will likely -run out of memory at some point and need to run the build again. -Still, this can be faster if your build is attended. - -``` --D RPI3ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for Raspberry Pi 4 - -On a 64bit OS: - -``` --D RPI4ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for Raspberry Pi 5 - -``` --D RPI5ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for TEGRA X1 - -On a 64bit OS: - -``` --D TEGRAX1=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for Jetson Xavier/T194 - -On a 64bit OS: - -``` --D TEGRA_T194=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for Jetson Orin/T234 - -On a 64bit OS: - -Note: use gcc-11 or higher, older gcc doesn't know cortex-a78ae -``` --D TEGRA_T234=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for DGX Spark/GB10 based devices - -On a 64bit OS: - -Note: Requires GCC 15.2.0 or higher. Older GCC versions do not support gb10, cortex-a725, or cortex-x925. - -For GCC 14 or older, you can use the following march equivalent: -``` --march=armv9.2-a+crc+sve2-aes+sve2-bitperm+sve2-sha3+sve2-sm4+memtag+profile -``` - -With GCC 15.2.0 or higher: -``` --D NVIDIA_GB10=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for ODROID N2/N2+ - -On a 64bit OS: - -``` --D ODROIDN2=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for Snapdragon - -On a 64bit OS: - -Targeting Snapdragon 845: - -``` --D SD845=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -Targeting Snapdragon 888: - -``` --D SD888=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -Targeting Snapdragon 8 Elite Gen 5: - -``` --D SD8EG5=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -Depending on how recent your Snapdragon is - -#### for Phytium - -On a 64bit OS: -``` --D PHYTIUM=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for ADLink machines - -On a 64bit OS: -``` --D ADLINK=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for M1 - -Only test on Asahi with Fedora, using the default "16K page" kernel - -``` --D M1=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for LoongArch - -On a 64bit OS: - -``` --D LARCH64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for RISC-V - -On a 64bit OS: - -``` --D RV64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for PowerPC 64 LE - -On a 64bit OS: - -``` --D PPC64LE=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for LX2160A - -On a 64bit OS: - -``` --D LX2160A=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for Termux - -You must have ARM64 machine to build box64. - -##### in CHRoot/PRoot - -``` --D ARM64=1 -DCMAKE_C_COMPILER=gcc -DBAD_SIGNAL=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo -``` - -##### in Termux (Native) - -Note: Box64 in native termux is experimental and won't run linux binaries! - -You also need `libandroid-sysv-semaphore` and `libandroid-spawn` libraries. - -``` --D TERMUX=1 -DCMAKE_C_COMPILER=clang -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` - -#### for x86_64 Linux - -``` --D LD80BITS=1 -D NOALIGN=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo -``` -If you encounter some linking errors, try using `NOLOADADDR=ON` (`cmake -D NOLOADADDR=ON; make -j$(nproc)`). - ----- - -### Use ccmake - -Alternatively, you can **use the curses-based ccmake (or any other gui frontend for cmake)** to select which platform to use interactively. - -### Customize your build - -#### Use ccache when present - -Add `-DUSE_CCACHE=1` option if you have ccache and plan to touch the sources. - -#### Include debug information - -Add `-DCMAKE_BUILD_TYPE=RelWithDebInfo` option for an optimized build with debug information embedded. That way, if you want to debug a crash or analyze performance, you have symbols. - -#### Build with trace - -To have a trace enabled build (***the interpreter will be slightly slower***), add `-DHAVE_TRACE=1`. You will need the [Zydis library](https://github.com/zyantific/zydis) devel package installed (`apt install libzydis-dev` on Debian for example). - -#### Build DynaRec - -Add `-D ARM_DYNAREC=ON` option to enable DynaRec on ARM machines. -Add `-D RV64_DYNAREC=ON` option to enable DynaRec on RV64 machines. -Add `-D LARCH64_DYNAREC=ON` option to enable DynaRec on LARCH64 machines. - -#### Save memory at run time - -You can use `-DSAVE_MEM` to have a build that will try to save some memory. For now, it only increases the jumptable from 4 levels to 5. The added granularity avoids wasting space, but adds one more read from memory when jumping between blocks. - -#### Build outside of a git repo - -Box64 uses git SHA1 to show last commit in version number, use `-DNOGIT=1` option when building outside of a git repo (for example, downloading a release source code zip from github). - -#### Use faster linker - -Add `-DWITH_MOLD=1` option when GNU ld is extremely slow. Then run `mold -run make -j4` to build (make sure [Mold](https://github.com/rui314/mold) is installed). - -#### Build a statically linked box64 - -You can now build box64 statically linked, with `-DSTATICBUILD` to use inside of a x86_64 chroot. Note that this version of box64 will only have the minimal wrapped libs, such as libc, libm and libpthread. Other libs (like libGL or libvulkan, SDL2, etc...) will use x86_64 versions. A static build is intended to be used in a docker image, or in a headless server. It is highly experimental, but feedback is always welcome. - ----- - -## Testing - -A few tests are included with box64. - -They can be launched using the `ctest` command. - -The tests are very basic and only test some functionality for now. - ----- - -## Debian Packaging - -Box64 can also be packaged into a .deb file ***using the source code zip from the releases page*** with `DEB_BUILD_OPTIONS=nostrip dpkg-buildpackage -us -uc -nc`. Configure any additional cmake options you want in `debian/rules`. - -## Pre-built packages - -### Debian-based Linux - -You can use the [Pi-Apps-Coders apt repository](https://github.com/Pi-Apps-Coders/box64-debs) to install precompiled box64 debs, updated every 24 hours. - -``` -# check if .list file already exists -if [ -f /etc/apt/sources.list.d/box64.list ]; then - sudo rm -f /etc/apt/sources.list.d/box64.list || exit 1 -fi - -# check if .sources file already exists -if [ -f /etc/apt/sources.list.d/box64.sources ]; then - sudo rm -f /etc/apt/sources.list.d/box64.sources || exit 1 -fi - -# download gpg key from specified url -if [ -f /usr/share/keyrings/box64-archive-keyring.gpg ]; then - sudo rm -f /usr/share/keyrings/box64-archive-keyring.gpg -fi -sudo mkdir -p /usr/share/keyrings -wget -qO- "https://pi-apps-coders.github.io/box64-debs/KEY.gpg" | sudo gpg --dearmor -o /usr/share/keyrings/box64-archive-keyring.gpg - -# create .sources file -echo "Types: deb -URIs: https://Pi-Apps-Coders.github.io/box64-debs/debian -Suites: ./ -Signed-By: /usr/share/keyrings/box64-archive-keyring.gpg" | sudo tee /etc/apt/sources.list.d/box64.sources >/dev/null - -sudo apt update -sudo apt install box64-generic-arm -y -``` - -## Cross-Compiling ----- -### Set Up the Cross-Compiler -For example, to compile Box64 for RISC-V on an x86 machine, you can get prebuilt GNU toolchain from the [riscv-gnu-toolchain](https://github.com/riscv-collab/riscv-gnu-toolchain/releases) - -### Run CMake with Cross-Compilation Options -Follow the per-platform compilation instructions to configure the CMake options for your target architecture. -In particular, you must specify the cross-compiler. For example: -``` --DCMAKE_C_COMPILER=riscv64-unknown-linux-gnu-gcc # Or whichever cross-compiler you use -``` - -Be aware of potential glibc capability errors when choosing a cross-compiler. -To avoid this, run `ldd --version` on your target machine to check its glibc version. - -### Running tests with QEMU (optional) -To do a quick check, run: -``` -qemu-riscv64 -L path/to/your/riscv64/sysroot box64 --help -``` -You can run `dirname $(find -name libc.so.6)` to determine whether sysroot is provided by the prebuilt GNU toolchain or not. - -To run CTest-based tests under QEMU: -``` -ctest -j$(nproc) -``` - -### Installing on the Target Machine -After successfully cross-compiling, copy the box64 executable to your RISC-V device. Note that simply copying the binary does not automatically install Box64’s shared libraries. Because `make install` does not run on the target during cross-compilation, libraries required for emulation may be missing. - -To resolve this, copy the shared libraries folder from the Box64 repository (`x64lib` or `x86lib`) to your target device, then rename it and place it in the appropriate library search path (e.g., `/usr/lib`). - -For `x86_64`: -```shell -$ mv x64lib box64-x86_64-linux-gnu -$ mv box64-x86_64-linux-gnu /usr/lib -``` -For `i386`: -```shell -$ mv x86lib box64-i386-linux-gnu -$ mv box64-i386-linux-gnu /usr/lib -``` - +Compiling/Installing +---- + +If you don't want to compile box64 yourself and prefer to use third-party pre-build version, go to the [end of the document](#pre-built-packages) for alternatives. + +You can also generate your own package using the [instructions below](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md#debian-packaging). + +Additional installation steps may be necessary when copying only the box64 executable file without running make install in cross-build environments. See [Cross-Compiling](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md#Cross-Compiling) + +## Per-platform compiling instructions + +### The general approach + +``` +git clone https://github.com/ptitSeb/box64 +cd box64 +mkdir build; cd build; cmake .. ${OPTIONS} +make -j4 +sudo make install +``` +If it's the first install, you also need: +``` +sudo systemctl restart systemd-binfmt +``` +- You can use `make -j1`, `make -j2` with less jobs to prevent running out of memory +- You can also add `-DBAD_SIGNAL=ON` to the cmake command if you are on a Linux Kernel mixed with Android, like on RK3588. + +### Note about Box32 + +If you want to build Box64 with the Box32 option, you will need to add `-DBOX32=ON` to the cmake command. That will enable 32bits process to be run with Box64. +If you also want binfmt integration on 32bits binaries, you also need to add `-DBOX32_BINFMT=ON` to the cmake command. + +### Note about WowBox64 + +A highly experimantal subproject named WowBox64 has been added as a build option, add `-DWOW64=ON` to the cmake command to enable it. +It will build alongside the regular Box64, and produce a `wowbox64.dll` file in `build/wowbox64-prefix/src/wowbox64-build/` directory. + +### Note about binfmt_misc on Android + +[binfmt_misc](https://en.wikipedia.org/wiki/Binfmt_misc) is a capability of the Linux kernel which allows arbitrary executable file formats to be recognized and passed to certain user space applications such as Box64 usually used with systemd but systems like Android can't run/use systemd so you will need to register Box64 manually, this will also work inside a CHRoot. +``` +sudo mount -t binfmt_misc none /proc/sys/fs/binfmt_misc +sudo echo ':box64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x3e\x00:\xff\xff\xff\xff\xff\xff\xff\x00\x00\x00\x00\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/local/bin/box64:' | sudo tee /proc/sys/fs/binfmt_misc/register +``` + + +#### Example of generic ARM64 build for linux platforms + +``` +git clone https://github.com/ptitSeb/box64 +cd box64 +mkdir build; cd build; cmake .. -D ARM_DYNAREC=ON -D CMAKE_BUILD_TYPE=RelWithDebInfo +make -j4 +sudo make install +sudo systemctl restart systemd-binfmt +``` + +#### Example of generic ARM64 build for linux platforms with full box32 integration + +``` +git clone https://github.com/ptitSeb/box64 +cd box64 +mkdir build; cd build; cmake .. -D ARM_DYNAREC=ON -D CMAKE_BUILD_TYPE=RelWithDebInfo -D BOX32=ON -D BOX32_BINFMT=ON +make -j4 +sudo make install +sudo systemctl restart systemd-binfmt +``` + +---- + +#### for RK3399 + +On a 64bit OS: +``` +-D RK3399=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for RK3588 / RK3588S + +On a 64bit OS: +``` +-D RK3588=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for Raspberry Pi 3 + +On a 64bit OS: + +If building on the Pi, you will also need a large swap (3 GB+) +[optionally reduce GPU memory to a minimum (e.g. 16 MB) using `raspi-config` +(and reboot) before starting the build]: + +You can use e.g. '`make -j4`' to speed up the build, but on a Pi 3 with 1GB memory you will likely +run out of memory at some point and need to run the build again. +Still, this can be faster if your build is attended. + +``` +-D RPI3ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for Raspberry Pi 4 + +On a 64bit OS: + +``` +-D RPI4ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for Raspberry Pi 5 + +``` +-D RPI5ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for TEGRA X1 + +On a 64bit OS: + +``` +-D TEGRAX1=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for Jetson Xavier/T194 + +On a 64bit OS: + +``` +-D TEGRA_T194=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for Jetson Orin/T234 + +On a 64bit OS: + +Note: use gcc-11 or higher, older gcc doesn't know cortex-a78ae +``` +-D TEGRA_T234=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for DGX Spark/GB10 based devices + +On a 64bit OS: + +Note: Requires GCC 15.2.0 or higher. Older GCC versions do not support gb10, cortex-a725, or cortex-x925. + +For GCC 14 or older, you can use the following march equivalent: +``` +-march=armv9.2-a+crc+sve2-aes+sve2-bitperm+sve2-sha3+sve2-sm4+memtag+profile +``` + +With GCC 15.2.0 or higher: +``` +-D NVIDIA_GB10=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for ODROID N2/N2+ + +On a 64bit OS: + +``` +-D ODROIDN2=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for Snapdragon + +On a 64bit OS: + +Targeting Snapdragon 845: + +``` +-D SD845=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +Targeting Snapdragon 888: + +``` +-D SD888=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +Targeting Snapdragon 8 Elite Gen 5: + +``` +-D SD8EG5=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +Depending on how recent your Snapdragon is + +#### for Phytium + +On a 64bit OS: +``` +-D PHYTIUM=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for ADLink machines + +On a 64bit OS: +``` +-D ADLINK=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for M1 + +Only test on Asahi with Fedora, using the default "16K page" kernel + +``` +-D M1=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for LoongArch + +On a 64bit OS: + +``` +-D LARCH64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for RISC-V + +On a 64bit OS: + +``` +-D RV64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for PowerPC 64 LE + +On a 64bit OS: + +``` +-D PPC64LE=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for LX2160A + +On a 64bit OS: + +``` +-D LX2160A=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for Termux + +You must have ARM64 machine to build box64. + +##### in CHRoot/PRoot + +``` +-D ARM64=1 -DCMAKE_C_COMPILER=gcc -DBAD_SIGNAL=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo +``` + +##### in Termux (Native) + +Note: Box64 in native termux is experimental and won't run linux binaries! + +You also need `libandroid-sysv-semaphore` and `libandroid-spawn` libraries. + +``` +-D TERMUX=1 -DCMAKE_C_COMPILER=clang -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` + +#### for x86_64 Linux + +``` +-D LD80BITS=1 -D NOALIGN=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo +``` +If you encounter some linking errors, try using `NOLOADADDR=ON` (`cmake -D NOLOADADDR=ON; make -j$(nproc)`). + +---- + +### Use ccmake + +Alternatively, you can **use the curses-based ccmake (or any other gui frontend for cmake)** to select which platform to use interactively. + +### Customize your build + +#### Use ccache when present + +Add `-DUSE_CCACHE=1` option if you have ccache and plan to touch the sources. + +#### Include debug information + +Add `-DCMAKE_BUILD_TYPE=RelWithDebInfo` option for an optimized build with debug information embedded. That way, if you want to debug a crash or analyze performance, you have symbols. + +#### Build with trace + +To have a trace enabled build (***the interpreter will be slightly slower***), add `-DHAVE_TRACE=1`. You will need the [Zydis library](https://github.com/zyantific/zydis) devel package installed (`apt install libzydis-dev` on Debian for example). + +#### Build DynaRec + +Add `-D ARM_DYNAREC=ON` option to enable DynaRec on ARM machines. +Add `-D RV64_DYNAREC=ON` option to enable DynaRec on RV64 machines. +Add `-D LARCH64_DYNAREC=ON` option to enable DynaRec on LARCH64 machines. + +#### Save memory at run time + +You can use `-DSAVE_MEM` to have a build that will try to save some memory. For now, it only increases the jumptable from 4 levels to 5. The added granularity avoids wasting space, but adds one more read from memory when jumping between blocks. + +#### Build outside of a git repo + +Box64 uses git SHA1 to show last commit in version number, use `-DNOGIT=1` option when building outside of a git repo (for example, downloading a release source code zip from github). + +#### Use faster linker + +Add `-DWITH_MOLD=1` option when GNU ld is extremely slow. Then run `mold -run make -j4` to build (make sure [Mold](https://github.com/rui314/mold) is installed). + +#### Build a statically linked box64 + +You can now build box64 statically linked, with `-DSTATICBUILD` to use inside of a x86_64 chroot. Note that this version of box64 will only have the minimal wrapped libs, such as libc, libm and libpthread. Other libs (like libGL or libvulkan, SDL2, etc...) will use x86_64 versions. A static build is intended to be used in a docker image, or in a headless server. It is highly experimental, but feedback is always welcome. + +---- + +## Testing + +A few tests are included with box64. + +They can be launched using the `ctest` command. + +The tests are very basic and only test some functionality for now. + +---- + +## Debian Packaging + +Box64 can also be packaged into a .deb file ***using the source code zip from the releases page*** with `DEB_BUILD_OPTIONS=nostrip dpkg-buildpackage -us -uc -nc`. Configure any additional cmake options you want in `debian/rules`. + +## Pre-built packages + +### Debian-based Linux + +You can use the [Pi-Apps-Coders apt repository](https://github.com/Pi-Apps-Coders/box64-debs) to install precompiled box64 debs, updated every 24 hours. + +``` +# check if .list file already exists +if [ -f /etc/apt/sources.list.d/box64.list ]; then + sudo rm -f /etc/apt/sources.list.d/box64.list || exit 1 +fi + +# check if .sources file already exists +if [ -f /etc/apt/sources.list.d/box64.sources ]; then + sudo rm -f /etc/apt/sources.list.d/box64.sources || exit 1 +fi + +# download gpg key from specified url +if [ -f /usr/share/keyrings/box64-archive-keyring.gpg ]; then + sudo rm -f /usr/share/keyrings/box64-archive-keyring.gpg +fi +sudo mkdir -p /usr/share/keyrings +wget -qO- "https://pi-apps-coders.github.io/box64-debs/KEY.gpg" | sudo gpg --dearmor -o /usr/share/keyrings/box64-archive-keyring.gpg + +# create .sources file +echo "Types: deb +URIs: https://Pi-Apps-Coders.github.io/box64-debs/debian +Suites: ./ +Signed-By: /usr/share/keyrings/box64-archive-keyring.gpg" | sudo tee /etc/apt/sources.list.d/box64.sources >/dev/null + +sudo apt update +sudo apt install box64-generic-arm -y +``` + +## Cross-Compiling +---- +### Set Up the Cross-Compiler +For example, to compile Box64 for RISC-V on an x86 machine, you can get prebuilt GNU toolchain from the [riscv-gnu-toolchain](https://github.com/riscv-collab/riscv-gnu-toolchain/releases) + +### Run CMake with Cross-Compilation Options +Follow the per-platform compilation instructions to configure the CMake options for your target architecture. +In particular, you must specify the cross-compiler. For example: +``` +-DCMAKE_C_COMPILER=riscv64-unknown-linux-gnu-gcc # Or whichever cross-compiler you use +``` + +Be aware of potential glibc capability errors when choosing a cross-compiler. +To avoid this, run `ldd --version` on your target machine to check its glibc version. + +### Running tests with QEMU (optional) +To do a quick check, run: +``` +qemu-riscv64 -L path/to/your/riscv64/sysroot box64 --help +``` +You can run `dirname $(find -name libc.so.6)` to determine whether sysroot is provided by the prebuilt GNU toolchain or not. + +To run CTest-based tests under QEMU: +``` +ctest -j$(nproc) +``` + +### Installing on the Target Machine +After successfully cross-compiling, copy the box64 executable to your RISC-V device. Note that simply copying the binary does not automatically install Box64’s shared libraries. Because `make install` does not run on the target during cross-compilation, libraries required for emulation may be missing. + +To resolve this, copy the shared libraries folder from the Box64 repository (`x64lib` or `x86lib`) to your target device, then rename it and place it in the appropriate library search path (e.g., `/usr/lib`). + +For `x86_64`: +```shell +$ mv x64lib box64-x86_64-linux-gnu +$ mv box64-x86_64-linux-gnu /usr/lib +``` +For `i386`: +```shell +$ mv x86lib box64-i386-linux-gnu +$ mv box64-i386-linux-gnu /usr/lib +``` +