From 51641bf413febe4cdfa893c330dd1cc77826d6c2 Mon Sep 17 00:00:00 2001
From: Alexey Dubovskoy <dubovskoy.a@gmail.com>
Date: Mon, 13 Jul 2026 10:34:33 +0100
Subject: [PATCH] docs: steer low-memory installs to prebuilt binaries

cargo install compiles ~400 crates and needs several GB of RAM and disk.
On Armbian /tmp is zram-backed (RAM/2), and cargo install puts its target
dir there, so SBC users hit confusing OOM-shaped build failures. We
already publish aarch64 and armv7 binaries; point people at them, and
document CARGO_TARGET_DIR for those who do want to build.

Refs #366
---
 README.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d5525bc..974a534 100644
--- a/README.md
+++ b/README.md
@@ -164,9 +164,34 @@ brew install cookcli
 If you have Rust installed:
 
 ```bash
-cargo install cookcli
+cargo install cookcli --locked
 ```
 
+`--locked` builds against the dependency versions we tested and released with, rather than re-resolving to the newest compatible ones.
+
+Note that this compiles CookCLI and all its dependencies from source, which needs a few GB of RAM and disk. If you are on a Raspberry Pi, an Armbian board, or anything else memory-constrained, prefer the [prebuilt binaries](https://github.com/cooklang/CookCLI/releases) — we publish `aarch64` and `armv7` Linux builds.
+
+<details>
+<summary>Building on a low-memory single-board computer</summary>
+
+`cargo install` places its build directory under `$TMPDIR`. On Armbian, `/tmp` is mounted on zram — a RAM-backed device sized to half your RAM — so a multi-gigabyte build will exhaust memory and fail, sometimes with a confusing `failed to load bitcode of module ...` error.
+
+Point the build somewhere on real storage:
+
+```bash
+CARGO_TARGET_DIR=~/.cache/cookcli-build cargo install cookcli --locked
+```
+
+If memory is still tight, disable link-time optimisation for the build:
+
+```bash
+CARGO_PROFILE_RELEASE_LTO=false \
+CARGO_TARGET_DIR=~/.cache/cookcli-build \
+  cargo install cookcli --locked
+```
+
+</details>
+
 ### Build from Source
 
 You'll need Rust and Node.js installed. Then: