Skip to content

LightCraft: An open-source non-destructive photo editor written by scratch in pure Rust

LR-BUILD: document command-local low-memory release overrides (#1196)

skybluuf12cf65ab72c
diff --git a/README.md b/README.md
index 8884f2bd3..e3398bd72 100644
--- a/README.md
+++ b/README.md
@@ -370,6 +370,31 @@ per CPU, otherwise exhaust RAM before any test runs. GPU coverage is unchanged.
`CARGO_PROFILE_DEV_DEBUG`, `CARGO_BUILD_JOBS` and `RUST_TEST_THREADS` settings
override these defaults. Ordinary development commands keep their own settings.
+**Release builds on memory-constrained machines:** [#1196](https://github.com/storytold/lightcraft/issues/1196)
+reports Arch/AUR release-link OOM kills on a 16 GB machine when the desktop and CLI build concurrently
+with full debug information, thin LTO and one codegen unit. The CI defaults above do not apply to
+ordinary `cargo build --release`. Start with one job; two may be suitable if enough memory is available:
+
+```sh
+CARGO_BUILD_JOBS=1 cargo build --release -p lightcraft -p lightcraft-cli
+# Alternatively: CARGO_BUILD_JOBS=2 cargo build --release -p lightcraft -p lightcraft-cli
+```
+
+If a packaging environment enables full debug information or memory-heavy LTO settings, use
+command-local overrides for a lower-memory source build:
+
+```sh
+CARGO_BUILD_JOBS=1 CARGO_PROFILE_RELEASE_DEBUG=0 CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 cargo build --release -p lightcraft -p lightcraft-cli
+```
+
+These POSIX-shell assignments affect only this command, not global Cargo configuration or the
+repository's release profiles. Disabling LTO may change performance and binary size; disabling debug
+information reduces debugging detail. This is build guidance, not a guarantee that any machine has
+enough memory. Downstream packagers should serialize large binary builds and avoid full debug
+information combined with LTO and one codegen unit on low-memory builders. A PKGBUILD that exports
+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.
+
**Chinese and Japanese text** need the shared font repo, an optional build input (official releases always include it):
```sh
diff --git a/README.zh-hans.md b/README.zh-hans.md
index 9a5331435..0a7feb32c 100644
--- a/README.zh-hans.md
+++ b/README.zh-hans.md
@@ -359,6 +359,30 @@ CI 默认使用行表调试信息,并按启动时可用内存每 1.5 GB 开一
`CARGO_PROFILE_DEV_DEBUG`、`CARGO_BUILD_JOBS` 和 `RUST_TEST_THREADS` 会覆盖这些默认值。
日常开发命令保持它们各自的设置。
+**内存受限机器上的 release 构建:** [#1196](https://github.com/storytold/lightcraft/issues/1196)
+报告在 16 GB 的 Arch/AUR 机器上,同时构建桌面应用和 CLI,并启用完整调试信息、thin LTO
+和单个代码生成单元时,链接过程被 OOM 终止。上述 CI 默认设置不适用于普通的
+`cargo build --release`。建议先使用一个构建任务;内存充足时可以尝试两个:
+
+```sh
+CARGO_BUILD_JOBS=1 cargo build --release -p lightcraft -p lightcraft-cli
+# 或者:CARGO_BUILD_JOBS=2 cargo build --release -p lightcraft -p lightcraft-cli
+```
+
+如果打包环境启用了完整调试信息或占用较多内存的 LTO 设置,可以使用仅对本条命令生效的
+覆盖设置,降低源码构建的内存需求:
+
+```sh
+CARGO_BUILD_JOBS=1 CARGO_PROFILE_RELEASE_DEBUG=0 CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 cargo build --release -p lightcraft -p lightcraft-cli
+```
+
+这些 POSIX shell 赋值只影响本条命令,不修改全局 Cargo 配置或仓库的 release profile。
+关闭 LTO 可能改变性能和二进制大小;关闭调试信息会减少可用的调试细节。这是构建建议,
+并不保证任何机器都有足够内存。下游打包者应串行构建大型二进制文件,并避免在低内存
+构建机器上同时使用完整调试信息、LTO 和单个代码生成单元。PKGBUILD 自己导出的 profile
+设置可以覆盖继承的环境变量;应在本地调整打包配方或联系维护者,而不要假定给
+`makepkg` 添加环境变量前缀就能优先生效。
+
**中文和日文文字**需要共享字体仓库,这是一个可选的构建输入(所有正式发布版都会包含它):
```sh
diff --git a/docs/whats-new.md b/docs/whats-new.md
index fb8b285a3..9f0711082 100644
--- a/docs/whats-new.md
+++ b/docs/whats-new.md
@@ -1,5 +1,13 @@
# What's new in LightCraft
+## 2026-10-13
+
+### Building from source
+- The English and Simplified Chinese build guides now describe command-local job and release
+ profile overrides for memory-constrained builders (issue #1196), including why packaging
+ recipes can override inherited settings. Default release profiles and application behavior
+ are unchanged; the guidance does not guarantee a build will fit every 16 GB machine.
+
## 2026-10-11
### JPEG XL export