Macos Developer Toolchain

---
name: macos-developer-toolchain
description: "macOS developer toolchain management: Xcode versions and lifecycle, Swift migration (5.9 to 6.0 to 6.2), code signing, notarization, Command Line Tools, Foundation Models, CI/CD pipelines, and Homebrew. Covers Xcode 15 through Xcode 26 and macOS 14 Sonoma through macOS 26 Tahoe. Use when: \"Xcode\", \"xcode\", \"Swift\", \"swift\", \"codesign\", \"notarize\", \"notarytool\", \"stapler\", \"Developer ID\", \"code signing\", \"provisioning profile\", \"xcode-select\", \"Command Line Tools\", \"CLT\", \"Foundation Models\". Do NOT use for general macOS system administration — use the `macos` skill."
license: MIT
---

# Developer Toolchain (macOS)

This skill covers macOS developer toolchain management across Xcode 15, 16, and 26, covering macOS 14 Sonoma through macOS 26 Tahoe. It provides deep knowledge of:

- Xcode versions and SDK mapping: Xcode 15 (Swift 5.9, macOS 14 SDK), Xcode 16 (Swift 6.0, macOS 15 SDK), Xcode 26 (Swift 6.2, macOS 26 SDK)
- Xcode installation and multi-version coexistence: xcode-select, xcrun tool resolution, Spotlight discovery
- Xcode Command Line Tools (CLT): standalone installation, headless/MDM deployment, CLT vs full Xcode
- Swift version management: Swift 5.9 macros, Swift 6.0 strict concurrency, Swift 6.2 Foundation Models and embedded Swift
- Code signing: certificate types, Keychain identity management, codesign flags, Hardened Runtime, entitlements
- Notarization: notarytool workflow, App Store Connect API keys, stapler, async submission, rejection debugging
- Provisioning profiles: types, inspection, CI/CD management, automatic vs manual signing
- Gatekeeper and SIP: assessment, troubleshooting blocked applications
- CI/CD pipelines: GitHub Actions macOS runners, xcodebuild, xcresult analysis, Fastlane integration
- Foundation Models (macOS 26): on-device AI, LanguageModelSession, @Generable, Tool calling
- Homebrew: Apple Silicon vs Intel paths, brew doctor, taps, casks, disk usage
- Certificate lifecycle: creation, expiry monitoring, MDM deployment, automatic vs manual signing
- Build optimization: Xcode 26 compilation caching, Swift Package Manager, dependency resolution

When a question is version-specific, note the relevant differences. When the Xcode or macOS version is unknown, provide general guidance and flag where behavior varies. For general macOS administration, see the `macos` skill.

## How to Approach Tasks

Route by request type: **Xcode/SDK** → `references/xcode-versions.md`; **Swift migration** → `references/swift-migration.md`; **signing/notarization** → `references/signing-notarization.md`; **health check** → the diagnostic scripts; **CI/CD signing** → `references/signing-notarization.md`.

**Identify Xcode version, macOS version, and target platform first** — these determine available SDKs, Swift features, and signing requirements. Reason from the interaction between Xcode version, Swift version, signing identity, and deployment target to isolate whether the issue is installation, configuration, signing, or build-related. Use `xcrun` for tool resolution rather than hard-coded paths; prefer non-destructive diagnostic steps first. Validate with `xcodebuild -version`, `codesign --verify`, `stapler validate`, and `security find-identity`.

## Core Expertise

### Xcode Versions and SDK Mapping

Apple ships one major Xcode version per macOS release. Each bundles a specific SDK and Swift toolchain.

| Xcode | macOS Codename | Min Host macOS | Bundled Swift | Key SDK |
|---|---|---|---|---|
| 15.x | Sonoma era | macOS 13 Ventura | Swift 5.9 | macOS 14 SDK |
| 16.x | Sequoia era | macOS 14 Sonoma | Swift 6.0 | macOS 15 SDK |
| 26.x | Tahoe era | macOS 15 Sequoia | Swift 6.2 | macOS 26 SDK |

Note: Xcode jumped from 16 to 26 to align with the macOS 26 "Tahoe" branding cycle.

Multiple Xcode installations coexist by renaming (e.g., `Xcode-16.app`, `Xcode-26.app`). Each is self-contained. Switching requires only `xcode-select --switch`.

**Active developer directory** controls which tools `xcrun` resolves:
```bash
xcode-select --print-path                                          # show current
sudo xcode-select --switch /Applications/Xcode-26.app/Contents/Developer  # switch
```

### Command Line Tools (CLT)

CLT provides compilers and Unix tools without the full Xcode GUI -- appropriate for CI servers and headless machines.

| Feature | CLT Only | Full Xcode |
|---|---|---|
| clang/clang++ | Yes | Yes |
| swift compiler | Yes | Yes |
| iOS/macOS SDKs | macOS SDK only | All platforms |
| Simulator | No | Yes |
| Interface Builder | No | Yes |
| Disk footprint | ~2 GB | 12-30 GB |

Install methods:
```bash
# Interactive (GUI dialog)
xcode-select --install

# Headless/MDM
softwareupdate --list | grep "Command Line"
softwareupdate --install "Command Line Tools for Xcode-16" --agree-to-license

# Silent from .pkg
installer -pkg /tmp/Command_Line_Tools_for_Xcode_16.pkg -target /
```

### Swift Version Management

**Swift 5.9 (Xcode 15):**
- Swift Macros (`@attached`, `@freestanding` compile-time code generation)
- SwiftData (declarative CoreData successor)
- Observation framework (`@Observable` macro)
- Variadic generics (parameter packs)

**Swift 6.0 (Xcode 16):**
- Strict concurrency: data race safety enforced at compile time
- Complete actor isolation by default
- `Sendable` enforcement across module boundaries
- Typed throws: `throws(ErrorType)` declarations
- Migration: `SWIFT_STRICT_CONCURRENCY=complete` build setting

**Swift 6.2 (Xcode 26):**
- Foundation Models API: on-device Apple Intelligence model integration
- `@MainActor` inference improvements (opt-in)
- `nonisolated(unsafe)` for gradual strict concurrency migration
- Embedded Swift for microcontrollers

### Code Signing

Code signing cryptographically asserts software identity and detects tampering. The kernel enforces signing via Gatekeeper and SIP.

**Certificate types:**
| Type | Issued By | Used For |
|---|---|---|
| Apple Development | Apple (via team) | Development builds, device testing |
| Apple Distribution | Apple (via team) | TestFlight, App Store |
| Developer ID Application | Apple | Mac apps outside App Store |
| Developer ID Installer | Apple | .pkg installers outside App Store |

Developer ID is the critical certificate for enterprise Mac software. Without it, Gatekeeper blocks execution.

**Hardened Runtime** is required for notarization:
- Prevents code injection and unsigned dynamic library loading
- Restricts DYLD environment variables
- Enable with `--options runtime` in codesign
- Exceptions declared via entitlements

### Notarization

Notarization is Apple's automated malware scanning service. After passing, Apple issues a ticket that Gatekeeper checks at launch.

**notarytool workflow:**
```bash
# Store credentials (one-time)
xcrun notarytool store-credentials "AC_PASSWORD" \
  --key AuthKey.p8 --key-id KEYID --issuer ISSUERID

# Submit and wait
xcrun notarytool submit MyApp.zip --keychain-profile "AC_PASSWORD" --wait

# Staple the ticket
xcrun stapler staple MyApp.app

# Validate
xcrun stapler validate MyApp.app
```

Apple checks: Hardened Runtime enabled, no malware signatures, no private entitlements, secure timestamp present, all binaries signed.

### Foundation Models (macOS 26)

On-device AI framework, part of Apple Intelligence:
- Runs entirely on-device using Apple Neural Engine (ANE)
- ~3B parameter model, quantized for M-series chips
- Requires macOS 26+, Apple Silicon, Apple Intelligence enabled
- MDM can control availability via `allowAppleIntelligence` restriction

```swift
import FoundationModels
let session = LanguageModelSession()
let response = try await session.respond(to: "Summarize this document")
```

Advanced: `@Generable` for structured output, `Tool` protocol for tool calling.

### Homebrew

Homebrew is the de facto package manager for macOS developer tools.

| Architecture | Prefix | Notes |
|---|---|---|
| Apple Silicon (arm64) | `/opt/homebrew` | Native ARM packages |
| Intel (x86_64) | `/usr/local` | Legacy path |

Intel Homebrew on Apple Silicon (Rosetta 2) is a common misconfiguration. Detect with `brew --prefix` and compare to expected path for `uname -m`.

### Certificate Lifecycle

- Developer ID certificates expire in **5 years**
- Apple Development/Distribution certificates expire in **1 year**
- APNs push certificates (for MDM) expire annually
- Set calendar reminders; automate expiry monitoring

```bash
# Check all signing identity expiry
security find-identity -v -p codesigning

# Check specific certificate
security find-certificate -c "Developer ID Application" -p | openssl x509 -noout -enddate
```

### CI/CD Best Practices

- Download specific Xcode .xip from developer.apple.com for version pinning
- Use temporary keychains in CI to avoid polluting system keychain
- `set-key-partition-list` required on macOS 10.12+ for codesign access without UI prompts
- Lock CI images to specific Xcode version; avoid App Store auto-updates
- Use `xcrun` for tool resolution rather than absolute paths

## Troubleshooting Decision Tree

```
1. Build failure
   +-- Missing SDK --> xcodebuild -showsdks; xcode-select --switch
   +-- Swift version mismatch --> swift --version; check TOOLCHAINS env var
   +-- Dependency resolution --> swift package resolve --verbose
   +-- License not accepted --> sudo xcodebuild -license accept
   |
2. Signing failure
   +-- No valid identity --> security find-identity -v -p codesigning
   +-- Certificate expired --> Check expiry; request new cert
   +-- Provisioning profile mismatch --> security cms -D -i profile
   +-- CI keychain access denied --> set-key-partition-list
   |
3. Notarization rejection
   +-- Missing Hardened Runtime --> codesign --display --verbose=4
   +-- Unsigned nested bundle --> codesign --verify --deep --strict
   +-- Private entitlement --> codesign --display --entitlements :-
   +-- Retrieve rejection log --> notarytool log <uuid>
   |
4. Gatekeeper blocking
   +-- Not notarized --> xcrun stapler validate
   +-- Quarantine flag --> xattr -d com.apple.quarantine (manual override)
   +-- spctl --assess --type execute --verbose MyApp.app
```

## Common Pitfalls

**1. Active developer directory pointing to CLT instead of Xcode**
CLT lacks iOS SDKs, simulators, and full signing tools. Verify with `xcode-select --print-path` and switch if needed.

**2. TOOLCHAINS environment variable overriding Xcode bundled toolchain**
A stale `TOOLCHAINS` env var can cause unexpected Swift version. Unset it or verify it matches your intended toolchain.

**3. Missing set-key-partition-list in CI**
On macOS 10.12+, imported certificates require `security set-key-partition-list` to allow codesign access without UI prompts. Without it, CI builds fail with "errSecInternalComponent."

**4. App Store Xcode auto-updating and breaking CI**
App Store can update Xcode automatically, changing the SDK and Swift version mid-pipeline. Pin Xcode versions via direct .xip download for CI.

**5. Homebrew on Intel path on Apple Silicon**
Running `/usr/local/bin/brew` on an arm64 Mac indicates a Rosetta 2 installation. Native arm64 packages are faster and avoid translation overhead. Migrate to `/opt/homebrew`.

## Reference Files

Load these when you need deep knowledge for a specific area:

- `references/xcode-versions.md` -- Xcode 15 through 26, SDK mapping, features per version. Read for version compatibility questions.
- `references/swift-migration.md` -- Swift 5.9 to 6.0 to 6.2, concurrency migration. Read for Swift upgrade guidance.
- `references/signing-notarization.md` -- Code signing, notarization pipeline, entitlements. Read for signing and distribution questions.

## Diagnostic Scripts

Run these for rapid toolchain assessment:

| Script | Purpose |
|---|---|
| `scripts/01-xcode-health.sh` | Xcode version, CLT, SDKs, Swift, simulators |
| `scripts/02-signing-audit.sh` | Developer ID certs, expiry, provisioning profiles, Gatekeeper |
| `scripts/03-homebrew-health.sh` | Install path, outdated packages, doctor, taps, disk usage |

## Key Paths and Files

| Path | Purpose |
|---|---|
| `/Applications/Xcode.app` | Default Xcode installation |
| `/Library/Developer/CommandLineTools/` | CLT standalone installation |
| `~/Library/MobileDevice/Provisioning Profiles/` | Installed provisioning profiles |
| `~/Library/Keychains/login.keychain-db` | User signing identities |
| `/Library/Keychains/System.keychain` | System certificates |
| `~/.swiftpm/cache` | Swift Package Manager cache |
| `/opt/homebrew` | Homebrew prefix (Apple Silicon) |
| `/usr/local` | Homebrew prefix (Intel) |

## Key Commands Quick Reference

```bash
# Xcode management
xcode-select --print-path
sudo xcode-select --switch /Applications/Xcode-26.app/Contents/Developer
xcodebuild -version
xcodebuild -showsdks

# Swift
swift --version
xcrun swift --version
swift package resolve

# CLT
pkgutil --pkg-info=com.apple.pkg.CLTools_Executables
xcode-select --install

# Code signing
security find-identity -v -p codesigning
codesign --verify --deep --strict --verbose=2 MyApp.app
codesign --display --verbose=4 MyApp.app
codesign --display --entitlements :- MyApp.app

# Notarization
xcrun notarytool submit MyApp.zip --keychain-profile "AC_PASSWORD" --wait
xcrun stapler staple MyApp.app
xcrun stapler validate MyApp.app

# Gatekeeper
spctl --assess --type execute --verbose MyApp.app
spctl --status

# Provisioning profiles
security cms -D -i profile.provisionprofile

# Homebrew
brew doctor
brew outdated
brew --prefix
```