fix(bootstrap): install Xcode Metal Toolchain on macOS (#9996)#10017
fix(bootstrap): install Xcode Metal Toolchain on macOS (#9996)#10017lonexreb wants to merge 2 commits intowarpdotdev:masterfrom
Conversation
`crates/warpui/build.rs` invokes the `metal` compiler to translate shader
sources to `.air` at cargo-build time. Xcode 16 split the Metal Toolchain
into a separately-downloadable component that is not installed by Xcode's
default first-launch setup, so a fresh macOS dev box following
`./script/bootstrap` then `./script/run` fails with a confusing
`build.rs` panic deep in the cargo output:
error compiling metal shaders to .air; error: error: cannot execute
tool 'metal' due to missing Metal Toolchain;
use: xcodebuild -downloadComponent MetalToolchain
This is the macOS counterpart to warpdotdev#9544 (Node.js / yarn check on Linux /
Windows, fixed in warpdotdev#9669). Same pattern: detect a missing build-time tool
during bootstrap rather than during cargo build.
Implementation:
- `xcrun --find metal` probes for the toolchain (fast, no network).
- If missing, `xcodebuild -downloadComponent MetalToolchain` triggers
Apple's downloader. The script streams xcodebuild's progress output so
the user can see what's happening on the multi-GB download.
- After the download attempt, re-probe `xcrun --find metal` and fail
loudly with manual-install instructions if the tool is still missing.
`xcodebuild -downloadComponent` can exit 0 without actually downloading
the component (e.g. when App Store credentials are missing), so the
re-probe is load-bearing — without it the bug just manifests in the
same place later.
Placed between `xcodebuild -runFirstLaunch` and the brew installs so the
Apple-side environment setup happens together. No change to Linux or
Windows bootstrap scripts.
github-actions
Bot
added
the
external-contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds a macOS bootstrap check that downloads Xcode's separately installed Metal Toolchain before cargo reaches the shader build step.
Concerns
- The new fallback does not run when
xcodebuild -downloadComponent MetalToolchainexits non-zero because the bootstrap script hasset -e; in that case users still miss the explicit re-probe/manual-install guidance this change is trying to provide.
Found: 0 critical, 1 important, 0 suggestions
Verdict
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| if ! xcrun --find metal >/dev/null 2>&1; then | ||
| echo "Metal Toolchain not installed. Running: xcodebuild -downloadComponent MetalToolchain" | ||
| echo "(this can take several minutes on first run; xcodebuild streams progress below)" | ||
| xcodebuild -downloadComponent MetalToolchain |
There was a problem hiding this comment.
set -e makes the script exit here on any non-zero downloader status, so the re-probe and manual-install instructions below never run; capture/ignore this command's status and let the xcrun --find metal check decide whether bootstrap should fail.
Per oz-for-oss review on PR warpdotdev#10017: the script runs under `set -e`, so `xcodebuild -downloadComponent MetalToolchain` exiting non-zero would abort the script before reaching the re-probe and manual-install instructions. Append `|| true` so the downloader's status is captured but doesn't trip set -e; the `xcrun --find metal` re-probe below remains the source of truth on whether the toolchain is now usable. The re-probe was already load-bearing for the silent-success case (where xcodebuild exits 0 without actually downloading, e.g. when App Store credentials are missing). This change extends the same defense to the explicit-failure case.
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I reviewed this pull request and requested human review from: @warpdotdev/oss-maintainers. Comment Powered by Oz |
oz-for-oss
Bot
dismissed
their stale review
Oz no longer requests changes for this pull request after the latest automated review.
There was a problem hiding this comment.
Overview
This PR updates the macOS bootstrap script to detect a missing Xcode Metal Toolchain before Cargo reaches the warpui shader build, attempts Apple's component download, and re-probes before continuing. The added flow keeps the failure mode in bootstrap with clear manual recovery instructions.
Concerns
- No blocking concerns found in the changed lines.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
oz-for-oss
Bot
requested review from
a team and
lucieleblanc
and removed request for
a team
1 participant
Fixes #9996.
crates/warpui/build.rsinvokes themetalcompiler to translate shader sources to.airat cargo-build time. Xcode 16 split the Metal Toolchain into a separately-downloadable component that is not installed by Xcode's default first-launch setup, so a fresh macOS dev box following `./script/bootstrap` then `./script/run` fails partway through cargo with a confusing build-script panic deep in the output:This is the macOS counterpart to #9544 (Node.js / yarn check on Linux / Windows, fixed in #9669) — same pattern, different platform: catch a missing build-time tool during bootstrap rather than during cargo build, where the user is least equipped to diagnose it.
What's in the diff
xcrun --find metalprobes for the toolchain (fast, no network).xcodebuild -downloadComponent MetalToolchaintriggers Apple's downloader. xcodebuild streams progress output so the user can see what's happening on the multi-GB download.xcrun --find metaland fail loudly with manual-install instructions if the tool is still missing. The re-probe is load-bearing:xcodebuild -downloadComponentcan exit 0 without actually downloading the component (e.g. when App Store credentials are missing). Without the re-probe the bug just resurfaces later in cargo build.Placement
Placed between
xcodebuild -runFirstLaunchand the brew installs so the Apple-side environment setup happens together. The script structure stays linear and matches the convention./script/macos/bootstrapalready uses (probe → install → continue).Scope
script/macos/bootstrap), 21 insertions, 0 deletions.cargo-bundlegap; that's tracked under./script/bootstrapdoes not install Xcode Metal Toolchain on macOS, leading to confusingcargo buildfailure incrates/warpui/build.rs#9996 as a sibling concern but is out of scope for this PR (line 37 of the script does already installcargo-bundlefrom a specific commit; if there's still a gap it deserves its own focused fix).Test plan
./script/bootstrapdetects the gap, runsxcodebuild -downloadComponent MetalToolchain, and produces a workingxcrun --find metalafter the download completes../script/bootstrapno-ops the new probe (xcrun --find metalsucceeds, noxcodebuildinvocation).xcodebuild -downloadComponentexits 0 without installing (e.g. App Store creds missing), the script fails with the manual-install message rather than letting cargo fail later.xcodebuild -runFirstLaunchstep or the brew/rust/gcloud installs that follow.