Skip to content

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

Merged
dubadub merged 1 commit into
mainfrom
docs/install-guidance-low-memory
Jul 14, 2026
Merged

docs: steer low-memory installs to prebuilt binaries#368
dubadub merged 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

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

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
@dubadub dubadub force-pushed the docs/install-guidance-low-memory branch from 02508cd to 51641bf Compare July 14, 2026 11:08
@claude

claude Bot commented Jul 14, 2026

Copy link
Copy Markdown

Review

Small, well-scoped, README-only change. Verified the factual claims against the repo:

  • aarch64-unknown-linux-musl and arm-unknown-linux-musleabihf targets are indeed built in .github/workflows/release.yaml (lines ~58-64), so the "prebuilt binaries" pointer is accurate.
  • cargo install's default build directory really does live under the system temp dir ($TMPDIR, /tmp on Linux) unless --target-dir/CARGO_TARGET_DIR is set — matches the Armbian zram-/tmp failure mode described.
  • CARGO_PROFILE_RELEASE_LTO is a documented, stable Cargo environment-variable profile override, so it will correctly override the workspace's lto = true in Cargo.toml (Cargo.toml:99) for a cargo install build.

Code quality / best practices

  • Clean, minimal diff (26 additions, 1 deletion), matches the "one thing well" spirit of this repo. --locked is a sensible default to recommend for install-from-source.
  • The collapsible <details> block is good UX — keeps the low-memory SBC caveat from cluttering the main install path for the majority of readers.

Potential issues (all minor/non-blocking)

  • "optimisation" (line 185) uses British spelling; nothing else in README.md establishes a convention either way, so this is a non-issue, just flagging in case you want consistency.
  • This PR explicitly pairs with fix(build): use thin LTO to cut peak build memory #367 (switch to thin LTO). Once fix(build): use thin LTO to cut peak build memory #367 lands, the default release profile may no longer need CARGO_PROFILE_RELEASE_LTO=false to build within the same memory budget — worth a quick sanity check after that merges to confirm the "if memory is still tight" escape hatch is still accurate/necessary, or reorder merging so this doesn't get stale.

Performance / security / tests

  • N/A — docs-only change, no code paths, no secrets or untrusted content introduced.

Overall this looks accurate and ready to merge; only the #367 sequencing note above is worth a glance.

@dubadub dubadub merged commit 9b2a851 into main Jul 14, 2026
4 checks passed
@dubadub dubadub deleted the docs/install-guidance-low-memory branch July 14, 2026 11:19
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