spb/zyquo-local Public MIT

1<!--2  BUILD.md3  Zyquo Local45  Author: Simon-Pierre Boucher6  Mail: contact@spboucher.ai7-->89# Building Zyquo Local Without the Xcode IDE1011Zyquo Local is built entirely from the command line with SwiftPM. The Xcode IDE is never used and no `.xcodeproj` exists. Two toolchain pieces are required beyond a plain macOS install:12131. **Command Line Tools** (`xcode-select --install`) — provides Swift 6.4 and the macOS SDKs.142. **Apple Metal Toolchain** — MLX compiles its GPU kernels (`.metal` files) at build time, and the `metal` compiler is **not** included in the Command Line Tools.1516## The Metal toolchain finding (Phase 0, resolved empirically 2026-07-30)1718- `swift build` on a CLT-only machine fails inside `Cmlx` with19  `error: unable to spawn process 'metal' (No such file or directory)` —20  mlx-swift 0.31.6 declares its Metal sources as SPM resources and SwiftPM's21  `CompileMetalFile` rule shells out to `metal`.22- SwiftPM resolves `metal` **via `PATH`** (verified with a logging stub), so a23  full Xcode install is NOT required. A standalone `Metal.xctoolchain` on24  `PATH` is sufficient.25- This machine uses the Metal Toolchain component copied from cluster node26  M4M36 (`com.apple.MobileAsset.MetalToolchain-v17.5.188.0`, Apple metal27  version 32023.883) into:2829  ```30  ~/Developer/Metal.xctoolchain31  ```3233  On a machine with Xcode 26+, the same component is installed by34  `xcodebuild -downloadComponent MetalToolchain`.3536## SDK pin for SwiftUI on macOS 27 CLT3738The macOS 27 SDKs shipped with the CLT expose SwiftUI's `@State` / `@Bindable`39(and related Observation wrappers) as Xcode-only macro plugins, which a plain40`swift build` cannot expand. As with Zyquo Term (see its ADR-0001), builds pin:4142```sh43export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk44```4546The Makefile and all scripts set both `SDKROOT` and the Metal `PATH`47automatically.4849## Canonical build recipe5051```sh52# everything below is wrapped by `make build` / `make dev` / `make release`53export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk54export PATH="$HOME/Developer/Metal.xctoolchain/usr/bin:$PATH"5556swift build -c release        # release binary57make dev                      # debug app bundle, ad-hoc signed, and launch58make release                  # signed + notarized + stapled Zyquo Local.app59```6061Verified: a scratch package depending on mlx-swift 0.31.6 builds in seconds62with this recipe and executes on the GPU (`Device(gpu, 0)`), confirming the63runtime `mlx.metallib` resource is produced and loaded correctly.64