Skip to content

Commit

Permalink
Minor adjustments to README, updated README_CN (#2032)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ksco
ksco authored Nov 14, 2024
1 parent 0688c53 commit 4e568e1
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 67 deletions.
30 changes: 18 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Check out Box64 in action on YouTube:

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 ARM64 and RV64 platforms, Box64 achieves a speed boost 5-10x faster than the interpreter alone. For a deeper look at DynaRec, see [Games performances](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/).
With DynaRec for ARM64, RV64 and LA64 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/).

<img src="docs/img/Box64Icon.png" width="96" height="96" alt="Box64 Icon">

Expand All @@ -29,8 +29,6 @@ _Logo and icon by @grayduck - Thank you!_

Box64 offers environment variables to control its behavior. For details, see [Usage Documentation](docs/USAGE.md).

**Debugging Note:** Box64's Dynarec uses Memory Protection and a SegFault signal handler for JIT code handling. If debugging with GDB, set `handle SIGSEGV nostop` to avoid constant interruptions. Set a breakpoint inside `my_memprotectionhandler` in `signals.c` if you want to track SegFaults.

---

## 🚀 Compiling and Installation
Expand All @@ -50,7 +48,10 @@ See the [Changelog](docs/CHANGELOG.md) for version updates.

Box64 requires 64-bit libraries on the host system, as it directly translates x86_64 function calls. For 32-bit binaries, use Box86.

**Note:** Some installers may default to x86 on ARM64 OS, causing compatibility issues. Workaround: Use a fake `uname` that returns "x86_64" for `-m`.
**Notes**

1. Box32 mode is in the making, which aims to support 32-bit binaries on Box64, stay tuned!
2. Some installers may default to x86 on 64-bit host OSes, causing compatibility issues. Workaround: Use a fake `uname` that returns "x86_64" for `-m`.

---

Expand All @@ -65,23 +66,28 @@ Settings priority: `~/.box64rc` > `/etc/box64.box64rc` > Command line.
## 📄 Additional Platform-Specific Notes

### Unity Game Emulation
- Many Unity games require OpenGL 3+, which may be challenging on ARM 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.

Let me know if you’d like further adjustments!
- 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.

### GTK Programs
- Box64 now wraps GTK libraries, supporting both gtk2 and gtk3.

Box64 wraps GTK libraries, supporting both gtk2 and gtk3.

### Steam
- Steam requires Box86 due to its 32-bit client app, but uses 64-bit local server binaries. Systems with less than 6GB RAM may need a swap file for optimal performance.

Steam requires Box86 due to its 32-bit client app, but uses 64-bit local server binaries. Systems with less than 6GB RAM may need a swap file for optimal performance.

### 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.

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.

### Vulkan
- Box64 wraps Vulkan libraries. Limited testing done with AMD RX550 and Freedreno drivers.

Box64 wraps Vulkan libraries.

----
Final word
Expand Down
105 changes: 50 additions & 55 deletions README_CN.md
View file
Original file line number Diff line number Diff line change
@@ -1,97 +1,92 @@
# box64
![图标](docs/img/Box64Logo.png "图标")

![Official logo](docs/img/Box64Logo.png "Official Logo")
Linux 上用户空间的 x86_64 应用模拟器（支持运行原生库）
# Box64：Linux 用户空间 x86-64 模拟器（支持原生库）

----
![box64 build status](https://app.travis-ci.com/ptitSeb/box64.svg?branch=main)
[更新日志](https://github.com/ptitSeb/box64/blob/main/docs/CHANGELOG.md) | [English](https://github.com/ptitSeb/box64/blob/main/README.md) | [Українська](https://github.com/ptitSeb/box64/blob/main/README_UK.md) | [Report an Error](https://github.com/ptitSeb/box64/issues/new)

[English](docs/README.md) | [Українська](https://github.com/ptitSeb/box64/blob/main/README_UK.md)
![Build Status](https://app.travis-ci.com/ptitSeb/box64.svg?branch=main) ![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)

Box64 可以在非 x86_64 Linux 系统（比如 ARM64）上运行 x86_64 Linux 程序（比如游戏），注意主机系统需要是 64 位小端。
---

您可以在 [MicroLinux](https://www.youtube.com/channel/UCwFQAEj1lp3out4n7BeBatQ)、[Pi Labs](https://www.youtube.com/channel/UCgfQjdc5RceRlTGfuthBs7g) 和 [The Byteman](https://www.youtube.com/channel/UCEr8lpIJ3B5Ctc5BvcOHSnA) YouTube 频道上找到许多 Box64 视频。
Box64 可以在非 x86_64 Linux 主机系统（比如 Arm）上运行 x86_64 Linux 程序（比如游戏），目前仅支持 64 位小端主机系统。

由于 Box64 使用一些“系统”库的原生版本，如 libc、libm、SDL 和 OpenGL 等，因此很容易与大多数应用程序集成和使用，并且在许多情况下性能会相当不错。可以在[这里](https://box86.org/index.php/2021/06/game-performances/)查看一些性能测试的样例。
在 YouTube 上查看 Box64 的运行效果:
- [MicroLinux](https://www.youtube.com/channel/UCwFQAEj1lp3out4n7BeBatQ)
- [Pi Labs](https://www.youtube.com/channel/UCgfQjdc5RceRlTGfuthBs7g)
- [The Byteman](https://www.youtube.com/channel/UCEr8lpIJ3B5Ctc5BvcOHSnA)

Box64 集成了适用于 ARM64 和 RV64 平台的 DynaRec（动态重编译器），速度可以比纯解释模式快 5 到 10 倍。可以在[这里](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/)找到有关 DynaRec 工作原理的一些信息。
Box64 可以使用本机原生的系统库（libc、libm、SDL、OpenGL），有着易于集成的特性和令人惊讶的性能。如需性能基准测试，请查看[此分析](https://box86.org/index.php/2021/06/game-performances/)。

一些 x64 内部操作码使用 “Realmode X86 Emulator Library” 的部分内容，有关版权详细信息，请参见 [x64primop.c](../src/emu/x64primop.c)。
借助适用于 ARM64，RV64 以及 LA64 平台的 DynaRec，Box64 的速度比单独使用解释器快 5-10 倍。如需深入了解 DynaRec，请参考[此文章](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/)。

<img src="docs/img/Box64Icon.png" width="96" height="96">
<img src="docs/img/Box64Icon.png" width="96" height="96" alt="Box64 Icon">

LOGO 由 @grayduck 制作，感谢！
_Logo 由 @grayduck 制作，感谢！_

----
---

使用方法
----
## 📖 使用方法

有若干环境变量可以控制 Box64 的行为。
Box64 提供了环境变量来控制其行为。有关详细信息请参阅[使用文档](docs/USAGE.md)。

可在[这里](docs/USAGE.md)查看所有环境变量及其作用。
---

注意：Box64 的 Dynarec 使用具有内存保护和段错误信号处理的机制来执行 JIT 代码。所以，如果想使用 GDB 调试使用 JIT 代码的程序（如 Mono/Unity3D），这会触发许多“正常”的段错误。建议在 GDB 中使用类似 `handle SIGSEGV nostop` 来防止它每个段错误处停止。如果你想捕获段错误，可以在 `signals.c` 的 `my_memprotectionhandler` 中设置断点。

----
## 🚀 编译和安装

编译/安装
----
- [编译说明](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md)
- [安装 Wine](https://github.com/ptitSeb/box64/blob/main/docs/X64WINE.md)

编译说明可以在[这里](docs/COMPILE.md)查看。
---

----
## 🔄 版本历史

版本历史
----
请参阅[变更日志](docs/CHANGELOG.md)了解版本更新说明。

版本日志在[这里](docs/CHANGELOG.md)。
---

----
## 🖥️ 平台兼容性说明

32位平台的注意事项
----
Box64 直接转换 x86_64 函数调用到本机原生库，因此需要主机系统上的 64 位库。对于 32 位二进制文​​件，请使用 Box86。

因为 Box64 的工作原理是直接将函数调用从 x86_64 转换为主机系统，所以主机系统（运行 Box64 的系统）需要有 64 位库。Box64 不包含任何 64 位 <-> 32 位的转换。
**注意事项**

所以 box64 只能运行 64 位的 Linux 二进制。对于 32 位二进制则需要使用 box86 来运行（它在 64 位操作系统上使用了 multiarch 和 proot 等技巧来实现运行）。请注意，许多（基于 mojo 的）安装程序在检测到 ARM64 操作系统时将回退到 “x86”，因此即使存在 x86_64 版本，也会尝试使用 box86。这时你可以使用一个假的 `uname` ，并使它在运行参数为 `-m` 时返回 `x86_64`。
1. Box32 模式正在制作中，旨在支持 Box64 上运行 32 位二进制文​​件，敬请期待！
2. 某些安装程序可能会将 64 位的主机操作系统判定为 x86 导致兼容性问题。解决方法：使用假的 `uname` ，并使它在运行参数为 `-m` 时返回 `x86_64`。

----
---

关于 Unity 游戏模拟的注意事项
----
## ⚙️ 配置

运行 Unity 游戏应该没什么问题，但还应该注意，许多 Unity3D 游戏需要 OpenGL 3+，这在 ARM SBC 上可能会比较棘手。同时许多较新的 Unity3D游戏（如 KSP）也使用 BC7 压缩纹理，很多 ARM 的集成显卡并不支持。
Box64 的配置文件位于 `/etc/box64.box64rc` 和 `~/.box64rc`，均为 `.ini` 格式的文件。如果您不想使用默认的 `/etc/box64.box64rc` 文件，请将其复制到 `~/.box64rc` 以确保兼容性。

> 提示：如果游戏开始后没有显示任何东西就退出了，在 Pi4 上可以使用 `MESA_GL_VERSION_OVERRIDE=3.2`，在 Panfrost 上则可以使用 `PAN_MESA_DEBUG=gl3` 来使用更高的配置。
配置项的优先级：`~/.box64rc` > `/etc/box64.box64rc` > 命令行。

----
---

关于GTK程序的注意事项
----
## 📄 特定平台的其他说明

box64 封装了 GTK，包括 gtk2 和 gtk3。
### Unity 游戏
- 许多 Unity 游戏需要 OpenGL 3+，这对 ARM/RISC-V SBC 来说可能具有挑战性。
- **对 Pi4 和 Pi5 用户的提示**：设置 `MESA_GL_VERSION_OVERRIDE=3.2` 和 `BOX64_DYNAREC_STRONGMEM=1` 以防止卡死并启用强内存模式。
- **Panfrost**：为了在 ARM 上实现更好的兼容性，启用 `PAN_MESA_DEBUG=gl3` 以强制更高的 OpenGL Profile。如果游戏可以启动但在显示任何内容之前意外退出，这个设置可能会有所帮助。

----
### GTK 程序

关于 Steam 的注意事项
----
Box64 包装了 GTK 库，支持 gtk2 和 gtk3。

请注意，Steam 是 32/64 位混合的应用，所以你需要 box86 才能运行，因为客户端应用程序是 32 位的。它还使用 64 位本地服务器，它的 steamwebhelper 无法被关闭（即使是在最小模式）而且会吃掉大量的内存。对于内存小于 6 GB 的机型，你将会需要创建 swapfile 来运行 Steam。
### Steam

----
由于 Steam 客户端应用是 32 位的，需要使用 Box86，但其本地服务器是 64 位的二进制文件。对于内存少于 6GB 的系统，可能需要使用交换文件以获得最佳性能。

关于 Wine 的注意事项
----
### Wine

box64 支持 Wine64，Proton 应该也能运行。请注意，64 位 Wine 包含有 32 位组件，以便能够运行 32 位 Windows 程序。32 位应用程序需要 box86，否则无法运行。在 box64 和 box86 都存在并工作的系统上，64 位的 Wine 可以同时运行 32 位和 64 位 Windows 程序（分别使用 `wine` 和 `wine64`）。请注意，目前在 Wine 7.+ 中实现的 Wine 时间在 64 位进程中的新 32bit PE 尚不支持。我测试了 Wine 7.5 64 位可以正常工作，但是更新的版本可能还不行。
Box64 支持 Wine64 和 Proton。对于 32 位组件，需要 Box86。配备 Box64 和 Box86 的系统可以运行 32 位和 64 位的 Windows 程序。

----
**提示**：您可以使用 Wine WOW64 版本在仅限 Box64 的环境中运行 x86 Windows 程序，这项支持仍处于实验阶段，但在大多数情况下都可以工作。

关于 Vulkan 注意事项
----
### Vulkan

Box64 封装了 Vulkan 库，但请注意，它仅在 RX550 显卡上进行过测试，因此根据您的显卡，某些扩展可能会丢失。
Box64 包装了 Vulkan 库。

----

Expand All @@ -103,7 +98,7 @@ Box64 封装了 Vulkan 库，但请注意，它仅在 RX550 显卡上进行过
以下感谢不分先后：

* 代码贡献：rajdakin, mogery, ksco, xctan
* 财务帮助：[Playtron](https://playtron.one), tohodakilla, FlyingFathead, stormchaser3000, dennis1248, sll00, [libre-computer-project](https://libre.computer/)
* 财务支持：[Playtron](https://playtron.one), tohodakilla, FlyingFathead, stormchaser3000, dennis1248, sll00, [libre-computer-project](https://libre.computer/), [CubeCoders Limited](http://cubecoders.com/)
* 硬件捐赠和 LoongArch 迁移：[xiaoji](https://www.linuxgame.cn/), Deepin Beijing Develop Team
* 硬件捐赠：[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)
* 为本项目持续的宣传：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/))
Expand Down

0 comments on commit 4e568e1

Please sign in to comment.