macos-developer-toolchain
/macos-developer-toolchain
Zarządza toolchainem deweloperskim macOS: wersjami Xcode, migracją Swifta, podpisywaniem kodu, notaryzacją, Command Line Tools, Foundation Models, potokami CI/CD i Homebrew, od Xcode 15 do 26.
- Autor
- chrishuffman5 ↗
- Repozytorium
- domain-expert ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 23.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 7
- Skrypty
- 3
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 23.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/01-xcode-health.sh, scripts/02-signing-audit.sh, scripts/03-homebrew-health.sh
Co robi i kiedy
Zarządza toolchainem deweloperskim macOS: wersjami Xcode, migracją Swifta, podpisywaniem kodu, notaryzacją, Command Line Tools, Foundation Models, potokami CI/CD i Homebrew, od Xcode 15 do 26.
Wyzwalacze z opisu
Oryginalny opis (EN)
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` skil
Jak działa
- How to Approach Tasks
- Core Expertise
- Troubleshooting Decision Tree
- Common Pitfalls
- Reference Files
- Diagnostic Scripts
- Key Paths and Files
- Key Commands Quick Reference
Podgląd SKILL.md
--- 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 ```
Pliki w paczce (7)
- SKILL.md 13 KB
- references/signing-notarization.md 10 KB
- references/swift-migration.md 8 KB
- references/xcode-versions.md 7 KB
- scripts/01-xcode-health.sh 6 KB
- scripts/02-signing-audit.sh 6 KB
- scripts/03-homebrew-health.sh 7 KB
Wersje
W bazie nie ma innych skilli o nazwie macos-developer-toolchain.
Migawka bazy z 13.11.2026 · wersja paczki 1c9da33e4e51 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100xcode
Wspiera pracę w Xcode: Swift i SwiftUI, symulatory iOS i macOS, Xcode Cloud, profilowanie Instruments, Swift Package Manager, debugowanie LLDB i podpisywanie. - 100xcode-management
Zarządza projektem Xcode i plikiem pbxproj: dodaje nowe pliki do projektu i pomaga w problemach z konfiguracją. - 90macos-build-run-debug
Buduje, uruchamia i debuguje aplikacje macOS przez powłokę, Xcode i Swift, gdy start lub działanie kończy się błędem. - 100guide-macos-spm-packaging
Tworzy, buduje i pakuje aplikacje macOS oparte na SwiftPM bez projektu Xcode, z własnym skryptem składania bundla .app i notaryzacją. - 90mac-app
Buduje, pakuje, podpisuje i wydaje aplikację macOS przez SwiftPM i narzędzia wiersza poleceń, bez projektu Xcode. - 90apple-developer
Buduje, debuguje i przegląda natywne aplikacje macOS, iPadOS i iOS w Swift, SwiftUI, UIKit i Xcode, także przy wysyłce do App Store.