#839·OpenCut

[BUG] Desktop build fails on macOS: README understates Xcode/Metal Toolchain requirement

Author: gendonholaholoCreated Jul 14, 2026Updated Sep 8, 2026

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

  1. On macOS with only the Command Line Tools installed (xcode-select -p/Library/Developer/CommandLineTools), clone the repo.
  2. cd apps/desktop && bun install is not needed; just run moon run desktop:check from the repo root.
  3. Observe the unable to find utility "metal" failure.
  4. Install full Xcode, sudo xcode-select -s /Applications/Xcode.app/Contents/Developer, retry → observe the missing Metal Toolchain failure.

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.