[BUG] Desktop build fails on macOS: README understates Xcode/Metal Toolchain requirement
Platform
macOS 26.5 (Darwin 25.5.0), Apple Silicon. Reproduced with Xcode 26.6 (17F113) and Moon 2.3.3.
Browser
N/A — native desktop build (moon run desktop:dev / cargo).
Current Behavior
apps/desktop/README.md lists the macOS requirement as:
macOS: Xcode command line tools (Metal renderer).
Command Line Tools alone are not enough. GPUI's build script compiles shaders.metal with xcrun metal, and the Metal compiler only ships inside full Xcode. On a fresh clone with only the CLT installed, moon run desktop:check (and desktop:dev) fail while building gpui v0.2.2:
cargo::error=metal shader compilation failed:
xcrun: error: unable to find utility "metal", not a developer tool or in PATH
error: failed to run custom build command for `gpui v0.2.2`
After installing full Xcode and running sudo xcode-select -s /Applications/Xcode.app/Contents/Developer, the build gets one step further and then fails again, because on Xcode 16.3+ the Metal compiler is a separately downloadable component:
cargo::error=metal shader compilation failed:
error: cannot execute tool 'metal' due to missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain
Running xcodebuild -downloadComponent MetalToolchain (~688 MB) resolves it, and moon run desktop:check / desktop:dev then succeed and the window opens. None of this is documented, so macOS contributors hit two consecutive build failures with no pointer to the fix.
Expected Behavior
apps/desktop/README.md should state that macOS needs full Xcode (not just Command Line Tools), and that on Xcode 16.3+ the Metal Toolchain component must be downloaded, so a first-time build succeeds by following the README.
Recurrence Probability
Always
Steps To Reproduce
- On macOS with only the Command Line Tools installed (
xcode-select -p→/Library/Developer/CommandLineTools), clone the repo. cd apps/desktop && bun installis not needed; just runmoon run desktop:checkfrom the repo root.- Observe the
unable to find utility "metal"failure. - Install full Xcode,
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer, retry → observe themissing Metal Toolchainfailure.
Anything else?
I have a one-line-ish README fix ready (documents full Xcode + xcodebuild -downloadComponent MetalToolchain, and notes that extra platform SDKs are not required). Per the PR template I'm opening this issue first and requesting maintainer approval before submitting the PR. Happy to adjust the wording however you prefer.
Source: OpenCut-app/OpenCut