From 02ddd67078ee459df6fdec756e0239a97af3c376 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?=
 <zhangyanghaha0407@outlook.com>
Date: Fri, 10 Jul 2026 15:55:39 -0400
Subject: [PATCH] fix(dev): resolve the macOS Metal toolchain before building
 the shell

---
 scripts/run_dev.sh | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/scripts/run_dev.sh b/scripts/run_dev.sh
index 490e94d..1621b31 100755
--- a/scripts/run_dev.sh
+++ b/scripts/run_dev.sh
@@ -1,6 +1,36 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# gpui compiles its Metal shaders with `xcrun metal`, which ships only in the
+# full Xcode Metal Toolchain — the standalone Command Line Tools do not provide
+# it. Respect a developer directory that already resolves `metal`; otherwise
+# fall back to a standard Xcode install; otherwise stop with the exact fix.
+ely_ensure_metal_toolchain() {
+    if xcrun --find metal >/dev/null 2>&1; then
+        return 0
+    fi
+    local xcode_developer_dir="/Applications/Xcode.app/Contents/Developer"
+    if [[ -d "${xcode_developer_dir}" ]] &&
+        DEVELOPER_DIR="${xcode_developer_dir}" xcrun --find metal >/dev/null 2>&1; then
+        export DEVELOPER_DIR="${xcode_developer_dir}"
+        return 0
+    fi
+    cat >&2 <<'EOF'
+error: the Metal shader compiler (`xcrun metal`) is unavailable.
+
+gpui compiles Metal shaders at build time, which needs the full Xcode Metal
+Toolchain. The Command Line Tools alone cannot build the macOS shell.
+
+Fix (no sudo required):
+  1. Install Xcode from the App Store.
+  2. DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
+       xcodebuild -downloadComponent MetalToolchain
+  3. Re-run scripts/run_dev.sh
+     (or point DEVELOPER_DIR at a non-standard Xcode location).
+EOF
+    return 1
+}
+
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "${repo_root}"
 target_dir="${CARGO_TARGET_DIR:-${repo_root}/target}"
@@ -15,6 +45,7 @@ binary_suffix=""
 if [[ "$(uname -s)" == "Darwin" ]]; then
     sidecar_features="servo-engine,hardware-render"
     rendering_context="hardware"
+    ely_ensure_metal_toolchain
 fi
 case "$(uname -s)" in
     MINGW*|MSYS*|CYGWIN*) binary_suffix=".exe" ;;