Skip to content

docs: Document dev build prerequisites and preflight missing tools (#334)#347

Merged
quiet-node merged 2 commits into
mainfrom
fix/334-dev-prereqs
Jul 21, 2026
Merged

docs: Document dev build prerequisites and preflight missing tools (#334)#347
quiet-node merged 2 commits into
mainfrom
fix/334-dev-prereqs

Conversation

@quiet-node

Copy link
Copy Markdown
Owner

Description

On a clean machine, bun run dev fails at engine:ensure with a raw spawn error when cmake or the full Xcode.app is missing, and neither tool is listed in CONTRIBUTING.md. This documents both prerequisites and makes the engine build check for them up front, failing with an actionable message instead of a cryptic spawn error. Closes #334.

Key changes

  • CONTRIBUTING.md: add cmake and full Xcode.app (including the sudo xcode-select -s /Applications/Xcode.app step) to Prerequisites.
  • CONTRIBUTING.md: correct two stale claims that described the engine as downloaded; it is cloned and built from source, which is why the build toolchain is required.
  • CONTRIBUTING.md: note that bun run dev runs a bare binary, so macOS attaches Accessibility and Screen Recording grants to the terminal running the command, not to a Thuki app bundle.
  • scripts/ensure-llama-server.ts: add a preflight check that probes cmake and the Metal shader compiler before building, reporting every missing tool together with its install step.

How it works

The preflight runs only when a build will actually happen: it sits after the already-built fast-path exit, so a machine with the sidecar already built is never blocked. The Metal check is conditional on xcrun -sdk macosx -f metal, the same probe the existing toolchain-download path uses, so Xcode.app is only demanded when the compiler is genuinely absent. Every probe is permissive on doubt: only a definitive "missing" result fails, anything ambiguous falls through to the existing behavior.

Testing

  • bun run engine:ensure: full source build succeeds; the re-run is a 0.1s no-op.
  • Simulated missing tools via a stripped $PATH: the cmake and Metal messages print together and the script exits non-zero.
  • bun run test:all:coverage and bun run validate-build: clean. Coverage scope is src/**, so the build-script change does not affect the 100% gate.

Note: the original clean-machine failure cannot be reproduced on a developer machine that already has the tools installed. A maintainer on a fresh setup can confirm the end-to-end path.

Signed-off-by: Logan Nguyen <lg.131.dev@gmail.com>
Signed-off-by: Logan Nguyen <lg.131.dev@gmail.com>
@quiet-node quiet-node changed the title Document dev build prerequisites and preflight missing tools (#334) docs: Document dev build prerequisites and preflight missing tools (#334) Jul 20, 2026
@andrewholzbach

Copy link
Copy Markdown
Contributor

Looks good! Thanks for addressing this :)

@quiet-node
quiet-node merged commit bbb33c1 into main Jul 21, 2026
6 checks passed
@quiet-node
quiet-node deleted the fix/334-dev-prereqs branch July 21, 2026 19:39
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.

cmake and full Xcode.app seem to be undocumented requirements for bun run dev

2 participants