SPB Git

spb/zyquo-local Public MIT

Native macOS AI chat that runs LLMs 100% locally on Apple Silicon with MLX — no cloud, no API keys.

macosswiftaimlxlocal-llm
Swift 97.2% Shell 1.8% Makefile 1%
2.5 KB
View source Raw Blame History

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

    text
    ~/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.