From d25f2779e80e82b4a128c4b8cb9c5a4e57e69d52 Mon Sep 17 00:00:00 2001 From: damocles Date: Fri, 5 Jun 2026 21:23:26 +0200 Subject: [PATCH] docs: note that linking workspace binaries locally needs nix develop (libsqlite3) --- docs/gotchas.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/gotchas.md b/docs/gotchas.md index 9211dad4..bfbf8305 100644 --- a/docs/gotchas.md +++ b/docs/gotchas.md @@ -209,6 +209,28 @@ and fail outright if the host daemon's fall back to unsandboxed local builds rather than failing. Security implications: `docs/security.md`. +## Linking workspace binaries locally needs `nix develop` + +The Rust workspace links `libsqlite3-sys` (rusqlite) against the +system `libsqlite3`. Agent containers carry no system libsqlite3 on +the linker path, so a plain `cargo build` of any binary dies with +`cannot find -lsqlite3` (deps and `ring` compile fine — only the +final link fails). `cargo check` / `cargo clippy` still work in the +ambient shell since they never link. + +Build + run binaries through the dev shell, which carries `sqlite` +on `NIX_LDFLAGS`: + +```bash +nix develop -c cargo build -p hive-c0re --bin hivectl +nix develop -c cargo run -p hive-c0re --bin hivectl -- +``` + +This is also how you regenerate committed generated docs locally — +e.g. `docs/tools/hivectl-cli.md` via the `hivectl markdown-docs` +subcommand (its `hivectl-docs` flake check otherwise only fails in +CI on drift). + ## Split asset derivations away from the rust workspace `nix/assets.nix` builds the branding SVG/PNG family + claude