<!--
  BUILD.md
  Zyquo Local

  Author: Simon-Pierre Boucher
  Mail: contact@spboucher.ai
-->

# Building Zyquo Local Without the Xcode IDE

Zyquo 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:

1. **Command Line Tools** (`xcode-select --install`) — provides Swift 6.4 and the macOS SDKs.
2. **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.

## The Metal toolchain finding (Phase 0, resolved empirically 2026-07-30)

- `swift build` on a CLT-only machine fails inside `Cmlx` with
  `error: unable to spawn process 'metal' (No such file or directory)` —
  mlx-swift 0.31.6 declares its Metal sources as SPM resources and SwiftPM's
  `CompileMetalFile` rule shells out to `metal`.
- SwiftPM resolves `metal` **via `PATH`** (verified with a logging stub), so a
  full Xcode install is NOT required. A standalone `Metal.xctoolchain` on
  `PATH` is sufficient.
- This machine uses the Metal Toolchain component copied from cluster node
  M4M36 (`com.apple.MobileAsset.MetalToolchain-v17.5.188.0`, Apple metal
  version 32023.883) into:

  ```
  ~/Developer/Metal.xctoolchain
  ```

  On a machine with Xcode 26+, the same component is installed by
  `xcodebuild -downloadComponent MetalToolchain`.

## SDK pin for SwiftUI on macOS 27 CLT

The macOS 27 SDKs shipped with the CLT expose SwiftUI's `@State` / `@Bindable`
(and related Observation wrappers) as Xcode-only macro plugins, which a plain
`swift build` cannot expand. As with Zyquo Term (see its ADR-0001), builds pin:

```sh
export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk
```

The Makefile and all scripts set both `SDKROOT` and the Metal `PATH`
automatically.

## Canonical build recipe

```sh
# everything below is wrapped by `make build` / `make dev` / `make release`
export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk
export PATH="$HOME/Developer/Metal.xctoolchain/usr/bin:$PATH"

swift build -c release        # release binary
make dev                      # debug app bundle, ad-hoc signed, and launch
make release                  # signed + notarized + stapled Zyquo Local.app
```

Verified: a scratch package depending on mlx-swift 0.31.6 builds in seconds
with this recipe and executes on the GPU (`Device(gpu, 0)`), confirming the
runtime `mlx.metallib` resource is produced and loaded correctly.