docs: Document dev build prerequisites and preflight missing tools (#334)#347
Merged
Conversation
Signed-off-by: Logan Nguyen <lg.131.dev@gmail.com>
Signed-off-by: Logan Nguyen <lg.131.dev@gmail.com>
Contributor
|
Looks good! Thanks for addressing this :) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
On a clean machine,
bun run devfails atengine:ensurewith a raw spawn error whencmakeor 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
cmakeand full Xcode.app (including thesudo xcode-select -s /Applications/Xcode.appstep) to Prerequisites.bun run devruns a bare binary, so macOS attaches Accessibility and Screen Recording grants to the terminal running the command, not to a Thuki app bundle.cmakeand 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.$PATH: the cmake and Metal messages print together and the script exits non-zero.bun run test:all:coverageandbun run validate-build: clean. Coverage scope issrc/**, 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.