Skip to content

docs: steer low-memory installs to prebuilt binaries#368

Open
dubadub wants to merge 1 commit into
mainfrom
docs/install-guidance-low-memory
Open

docs: steer low-memory installs to prebuilt binaries#368
dubadub wants to merge 1 commit into
mainfrom
docs/install-guidance-low-memory

Conversation

@dubadub

@dubadub dubadub commented Jul 13, 2026

Copy link
Copy Markdown
Member

Addresses the install side of #366.

We already publish aarch64-unknown-linux-musl and arm-unknown-linux-musleabihf binaries in release.yaml — but the README presents cargo install cookcli as a peer option with no caveats, so SBC users reach for it and then spend an hour compiling ~400 crates only to run out of RAM.

Changes to the Installation section:

  • cargo install cookclicargo install cookcli --locked, with a note on why.
  • Say plainly that installing via cargo compiles from source and needs a few GB, and point memory-constrained users at the prebuilt binaries we already ship.
  • A collapsed section documenting the Armbian trap: /tmp is zram-backed (sized RAM/2) and cargo install puts its target dir there, which is what produces the confusing failed to load bitcode of module ... failure. Gives the CARGO_TARGET_DIR and CARGO_PROFILE_RELEASE_LTO=false escape hatches.

Pairs with #367, which fixes the underlying memory cliff by moving off fat LTO.

Refs #366

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
@claude

claude Bot commented Jul 13, 2026

Copy link
Copy Markdown

Review

Reviewed the README diff (docs-only change, no Rust code touched, so cargo fmt/clippy/test don't apply here).

Overall: solid, well-scoped documentation fix. Verified the technical claims:

  • aarch64-unknown-linux-musl and arm-unknown-linux-musleabihf are indeed published in release.yaml, so the "prebuilt binaries" pointer is accurate.
  • CARGO_PROFILE_RELEASE_LTO is a real Cargo profile override env var and works regardless of whether Cargo.toml's [profile.release] currently has lto = true (as on main today) or lto = "thin" (as proposed in fix(build): use thin LTO to cut peak build memory #367) — so this doc doesn't depend on fix(build): use thin LTO to cut peak build memory #367 landing first or in any particular order.
  • Link casing (cooklang/CookCLI) is consistent with the rest of the README.
  • <details>/<summary> block is well-formed with blank lines around the fenced code blocks, so it should render correctly on GitHub.

Minor nits (non-blocking):

  • "optimisation" (line 185) is the only British-spelling word in the file; the rest of the README uses American English ("organize", "customize", etc. elsewhere in the repo). Consider "optimization" for consistency.
  • The zram-causes-OOM explanation is a specific technical claim about Armbian's /tmp mount; worth double-checking against current Armbian defaults before merging, since it's stated as unqualified fact rather than "typically."

No security, performance, or test-coverage concerns — this is a README-only change with no executable code paths affected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant