From f8035591aa62282637523a3683800e48b7baf334 Mon Sep 17 00:00:00 2001
From: akol1 <15747200+akol1@users.noreply.github.com>
Date: Sun, 18 Oct 2026 15:27:55 -0700
Subject: [PATCH] docs: install Xcode's Metal Toolchain component before a Mac
 build

The `.metal` sources need `metal` from the Metal Toolchain component of full
Xcode. With only the Command Line Tools every kernel compile fails with
`unable to find utility "metal"`, including the reference suites, so the build
instructions name the requirement and the component install command.
---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 594285ca38..83f7b4aa88 100644
--- a/README.md
+++ b/README.md
@@ -248,7 +248,9 @@ The supported environment variables are listed in `capabilities --json`, includi
 ## Build and contribute
 
 Use the Zig version pinned in `.zig-version`, currently 0.17.0.
-On a Mac with Xcode's Metal toolchain:
+The `.metal` sources need Xcode's Metal compiler. Install full Xcode and its Metal Toolchain component
+(`xcodebuild -downloadComponent MetalToolchain`); the Command Line Tools alone fail every kernel compile with
+`unable to find utility "metal"`.
 
 ```sh
 zig build native -Dcpu=apple_m1 -Dversion=1.0.12