Merge PR #2885: docs(linux): document LLVM 23 ThinLTO SIGILL workaround (#2811)

README.md

@@ -451,6 +451,36 @@ information combined with LTO and one codegen unit on low-memory builders. A PKG
 its own profile settings can override inherited variables; adjust the packaging recipe locally or
 contact its maintainer rather than assuming an environment prefix on `makepkg` will take precedence.
 
+**Linux/Arch build troubleshooting: rustc SIGILL with ThinLTO.**
+In [#2811](https://github.com/storytold/lightcraft/issues/2811), an Arch Linux x86_64 build on an
+AMD Ryzen 9 7900X3D with 64 GB RAM failed with rustc 1.99.0 / LLVM 23.1.1, AUR `lightcraft`
+`0.7.1-1` and `0.13.0-1`, `RUSTFLAGS="-C opt-level=3 -C target-cpu=native"`, and release settings
+`opt-level=3`, `lto=thin`, `codegen-units=1`. `cargo build --frozen --release` reached the executable
+crates before rustc crashed with signal 4 (`SIGILL` / `ILL_ILLOPN`). The core dumps point into LLVM's
+SelectionDAG / vector-combine optimization path; the exact compiler root cause has not been isolated.
+This does not mean every machine with that hardware or toolchain will fail. It is a different observed
+failure from the 16 GB OOM kills in [#1196](https://github.com/storytold/lightcraft/issues/1196) above;
+there is no evidence establishing a shared root cause.
+
+For a direct Cargo source build, the equivalent command-local LTO override is:
+
+```sh
+CARGO_PROFILE_RELEASE_LTO=off cargo build --frozen --release
+```
+
+Reporter @rwarmstr verified the workaround by exporting `CARGO_PROFILE_RELEASE_LTO=off` **inside the
+AUR PKGBUILD's `_srcenv()` function** and rebuilding both package versions, without changing
+`RUSTFLAGS`. The reporter tested the AUR recipe, not the direct Cargo invocation above.
+A variable prefixed to `makepkg` alone may be overwritten by the PKGBUILD's own exports; the recipe
+must honor or set the override. The AUR `!lto` opt-out behavior is tracked separately in
+[#2813](https://github.com/storytold/lightcraft/issues/2813).
+
+[Cargo's LTO documentation](https://doc.rust-lang.org/cargo/reference/profiles.html#lto) distinguishes
+`false` from `off`: `false` can still perform thin local LTO across codegen units (unless
+`codegen-units=1` or `opt-level=0`); `off` disables LTO explicitly. The low-memory recipe above is
+unchanged. This workaround is for affected builds, not a new default; disabling LTO may change
+performance, binary size and build behavior.
+
 Tests that need a GPU, the corpus, the craft-fonts faces or a model pass without checking anything when
 those are missing (libtest has no "skipped" status), so `cargo xtask ci` lists them: tests record a skip
 with `lightcraft_testkit::skip!`, and the run ends with what the machine offered (OS, CPUs, RAM, GPU

README.zh-hans.md

@@ -384,6 +384,34 @@ CARGO_BUILD_JOBS=1 CARGO_PROFILE_RELEASE_DEBUG=0 CARGO_PROFILE_RELEASE_LTO=false
 设置可以覆盖继承的环境变量；应在本地调整打包配方或联系维护者，而不要假定给
 `makepkg` 添加环境变量前缀就能优先生效。
 
+**Linux/Arch 构建故障：rustc 在 ThinLTO 阶段发生 SIGILL。**
+在 [#2811](https://github.com/storytold/lightcraft/issues/2811) 中，报告者的 Arch Linux x86_64
+机器配备 AMD Ryzen 9 7900X3D 和 64 GB RAM，使用 rustc 1.99.0 / LLVM 23.1.1、AUR
+`lightcraft` `0.7.1-1` 和 `0.13.0-1`、`RUSTFLAGS="-C opt-level=3 -C target-cpu=native"`，
+以及 release 设置 `opt-level=3`、`lto=thin`、`codegen-units=1`。
+`cargo build --frozen --release` 在编译到可执行 crate 时，rustc 因 signal 4
+（`SIGILL` / `ILL_ILLOPN`）崩溃。core dump 指向 LLVM 的 SelectionDAG / vector-combine
+优化路径；编译器的具体根因尚未确定。这不表示所有使用这些硬件或工具链的机器都会失败。
+此故障与上文 [#1196](https://github.com/storytold/lightcraft/issues/1196) 中 16 GB 机器上的
+OOM 终止表现不同，没有证据表明两者根因相同。
+
+直接使用 Cargo 从源码构建时，等价的单条命令 LTO 覆盖方式是：
+
+```sh
+CARGO_PROFILE_RELEASE_LTO=off cargo build --frozen --release
+```
+
+报告者 @rwarmstr 验证成功的是：在 **AUR PKGBUILD 的 `_srcenv()` 函数内部**导出
+`CARGO_PROFILE_RELEASE_LTO=off` 后重新构建上述两个版本，无需更改 `RUSTFLAGS`。
+报告者测试的是 AUR 配方，并未单独验证上面的直接 Cargo 命令。仅在 `makepkg` 前添加变量，
+可能会被 PKGBUILD 自己的 export 覆盖；打包配方必须保留或设置该覆盖值。
+AUR 的 `!lto` 选项行为由 [#2813](https://github.com/storytold/lightcraft/issues/2813) 单独跟踪。
+
+[Cargo 的 LTO 文档](https://doc.rust-lang.org/cargo/reference/profiles.html#lto) 区分了 `false`
+和 `off`：`false` 仍可能在代码生成单元之间执行 thin local LTO（除非 `codegen-units=1`
+或 `opt-level=0`）；`off` 则明确禁用 LTO。上文的低内存配方保持不变。
+此绕过方法仅针对受影响的构建，不是新的默认建议；禁用 LTO 可能改变性能、二进制大小和构建行为。
+
 **中文和日文文字**需要共享字体仓库，这是一个可选的构建输入（所有正式发布版都会包含它）：
 
 ```sh

README.zh-hant.md

@@ -402,6 +402,34 @@ CARGO_BUILD_JOBS=1 CARGO_PROFILE_RELEASE_DEBUG=0 CARGO_PROFILE_RELEASE_LTO=false
 PKGBUILD 可能會覆寫繼承的環境變數；請在本機調整打包腳本或聯絡維護者，而不要假設替
 `makepkg` 加上環境變數前綴就能優先生效。
 
+**Linux/Arch 建置故障：rustc 在 ThinLTO 階段發生 SIGILL。**
+在 [#2811](https://github.com/storytold/lightcraft/issues/2811) 中，回報者的 Arch Linux x86_64
+機器配備 AMD Ryzen 9 7900X3D 與 64 GB RAM，使用 rustc 1.99.0 / LLVM 23.1.1、AUR
+`lightcraft` `0.7.1-1` 與 `0.13.0-1`、`RUSTFLAGS="-C opt-level=3 -C target-cpu=native"`，
+以及 release 設定 `opt-level=3`、`lto=thin`、`codegen-units=1`。
+`cargo build --frozen --release` 在編譯到可執行 crate 時，rustc 因 signal 4
+（`SIGILL` / `ILL_ILLOPN`）當機。core dump 指向 LLVM 的 SelectionDAG / vector-combine
+最佳化路徑；編譯器的具體根因尚未確定。這不表示所有使用這些硬體或工具鏈的機器都會失敗。
+此故障與上文 [#1196](https://github.com/storytold/lightcraft/issues/1196) 中 16 GB 機器上的
+OOM 終止表現不同，沒有證據顯示兩者根因相同。
+
+直接使用 Cargo 從原始碼建置時，等價的單條指令 LTO 覆寫方式是：
+
+```sh
+CARGO_PROFILE_RELEASE_LTO=off cargo build --frozen --release
+```
+
+回報者 @rwarmstr 驗證成功的是：在 **AUR PKGBUILD 的 `_srcenv()` 函式內部**匯出
+`CARGO_PROFILE_RELEASE_LTO=off` 後重新建置上述兩個版本，無須變更 `RUSTFLAGS`。
+回報者測試的是 AUR 腳本，並未單獨驗證上面的直接 Cargo 指令。僅在 `makepkg` 前加上變數，
+可能會被 PKGBUILD 自己的 export 覆寫；打包腳本必須保留或設定該覆寫值。
+AUR 的 `!lto` 選項行為由 [#2813](https://github.com/storytold/lightcraft/issues/2813) 另行追蹤。
+
+[Cargo 的 LTO 文件](https://doc.rust-lang.org/cargo/reference/profiles.html#lto) 區分了 `false`
+與 `off`：`false` 仍可能在程式碼產生單元之間執行 thin local LTO（除非 `codegen-units=1`
+或 `opt-level=0`）；`off` 則明確停用 LTO。上文的低記憶體建置配方維持不變。
+此繞過方法僅適用於受影響的建置，不是新的預設建議；停用 LTO 可能改變效能、二進位檔大小與建置行為。
+
 測試在缺少 GPU、語料庫、craft-fonts 字型或模型時會直接通過而不檢查任何內容（libtest 沒有「已跳過」
 這個狀態），所以 `cargo xtask ci` 會把它們列出來：測試會用 `lightcraft_testkit::skip!` 記錄跳過原因，
 執行結束時會列出機器提供的環境（作業系統、CPU、記憶體、每個後端的 GPU 配接器、語料庫、字型）以及每一項