From 293247c98c1bb45b2aa728c33e43722a0721fe97 Mon Sep 17 00:00:00 2001
From: casjay <git-admin@casjaysdev.pro>
Date: Sun, 31 May 2026 20:52:51 -0400
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20rewrite=20README=20and=20fix=20s?=
 =?UTF-8?q?etup=20script=20tool=20installs=20=F0=9F=93=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README rewritten from 137 → 439 lines: full tool tables, env var reference, volume/cache guide, cross-compile target matrix, sccache remote backend docs, BuildKit cache mount info
- Update image name from `casjaysdevdocker/rust` to `casjaysdev/rust` throughout
- Add `clang-dev`, `llvm-dev`, `openssl-libs-static` to build deps; add `perf` (non-fatal) for flamegraph/samply support
- Fix rustup nightly component flag syntax (split into two `--component` flags)
- Move `cargo-nextest` to fallback block with `--locked`; rename `typos` → `typos-cli` and `cargo-flamegraph` → `flamegraph` to match correct crate names

README.md
rootfs/root/docker/setup/05-custom.sh
---
 README.md                             |  7 ++++++-
 rootfs/root/docker/setup/05-custom.sh | 17 +++++++++++------
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 3370bac..ef347ad 100644
--- a/README.md
+++ b/README.md
@@ -188,7 +188,12 @@ Run miri with: `cargo +nightly miri test`
 | `cargo-criterion` | Criterion-based benchmark runner with statistical analysis |
 | `hyperfine` | Command-line benchmarking tool — wall-clock timing with statistics |
 | `samply` | Sampling profiler — records perf profiles, opens in Firefox Profiler |
-| `cargo-flamegraph` | Generate flame graphs from `cargo bench` or any cargo command |
+| `flamegraph` | Generate flame graphs from `cargo bench` or any cargo command (`cargo flamegraph`) |
+
+> **Perf note:** `perf` is installed from the Alpine package repo. Profiling with
+> `samply` or `flamegraph` inside Docker requires elevated capabilities at runtime:
+> `--privileged` or `--cap-add SYS_ADMIN --cap-add PERFMON`. This is a host grant
+> — it cannot be baked into the image.
 
 ### Fuzzing
 
diff --git a/rootfs/root/docker/setup/05-custom.sh b/rootfs/root/docker/setup/05-custom.sh
index 9220e28..eff5d88 100755
--- a/rootfs/root/docker/setup/05-custom.sh
+++ b/rootfs/root/docker/setup/05-custom.sh
@@ -32,7 +32,7 @@ exitCode=0
 # Main script
 
 # Install C/C++ toolchain and static-build dependencies needed by Rust -sys crates
-pkmgr install build-base musl-dev clang lld cmake make perl openssl-dev pkgconf gdb
+pkmgr install build-base musl-dev clang clang-dev llvm-dev lld cmake make perl openssl-dev openssl-libs-static pkgconf gdb
 
 # Install cross-compile toolchains — failures are non-fatal on minimal mirrors
 pkmgr install mingw-w64-gcc || true
@@ -43,6 +43,10 @@ pkmgr install zig || true
 # Install binaryen (wasm-opt) for WASM size optimisation tooling
 pkmgr install binaryen || true
 
+# Install Linux perf — required by flamegraph and samply to record profiles;
+# non-fatal because availability depends on the host kernel and Alpine mirror
+pkmgr install perf || true
+
 # - - - - - - - - - - - - - - - - - - - - - - - - -
 # rustup paths — match the official rust:alpine convention so existing
 # workflows work unchanged; volumes are declared at these paths in the Dockerfile
@@ -82,7 +86,7 @@ rustup component add rust-src rust-analyzer llvm-tools-preview
 
 # Nightly toolchain for miri and other unstable tooling; minimal profile
 # keeps the download small — only the compiler and std/src are pulled in
-rustup toolchain install nightly --profile minimal --component miri rust-src
+rustup toolchain install nightly --profile minimal --component miri --component rust-src
 
 # - - - - - - - - - - - - - - - - - - - - - - - - -
 # Cross-compile targets — Linux musl (fully static, no libc dependency)
@@ -161,7 +165,6 @@ cargo binstall -y \
   cargo-expand \
   cargo-info \
   bacon \
-  cargo-nextest \
   cargo-llvm-cov \
   cargo-tarpaulin \
   cargo-audit \
@@ -187,7 +190,7 @@ cargo binstall -y \
   mdbook \
   mdbook-toc \
   sccache \
-  typos \
+  typos-cli \
   taplo-cli \
   cargo-sort \
   cargo-hack \
@@ -200,7 +203,9 @@ cargo binstall -y \
   grcov
 
 # Tools that occasionally lack musl prebuilts — fall back to source compilation
-cargo binstall -y cargo-dist 2>/dev/null || cargo install cargo-dist
+# cargo-nextest requires --locked when building from source (locked-tripwire guard)
+cargo binstall -y cargo-nextest 2>/dev/null || cargo install --locked cargo-nextest || true
+cargo binstall -y cargo-dist 2>/dev/null || cargo install cargo-dist || true
 cargo binstall -y cargo-msrv 2>/dev/null || cargo install cargo-msrv
 cargo binstall -y cargo-mutants 2>/dev/null || cargo install cargo-mutants
 cargo binstall -y flip-link 2>/dev/null || cargo install flip-link
@@ -218,7 +223,7 @@ cargo install probe-rs --features cli 2>/dev/null || true
 
 # samply and cargo-flamegraph require a system perf or dtrace — best-effort
 cargo binstall -y samply 2>/dev/null || true
-cargo binstall -y cargo-flamegraph 2>/dev/null || true
+cargo binstall -y flamegraph 2>/dev/null || cargo install flamegraph || true
 
 # sqlx-cli and sea-orm-cli need project-specific feature flags at runtime;
 # install a broadly compatible build here as a convenience