--- name: macos-project-tooling description: >- Xcode project vs Swift Package Manager vs Tuist vs XcodeGen; SPM dependency management; project structure tradeoffs and .xcodeproj churn topics: - macos-native - tooling - spm - xcode - project-structure volatility: evolving last-reviewed: 2026-06-18 version-pin: null sources: - url: https://docs.swift.org/package-manager/ - url: https://developer.apple.com/documentation/xcode/swift-packages - url: https://tuist.io/docs/ - url: https://github.com/yonaskolb/XcodeGen --- The choice of project definition format — a hand-maintained `.xcodeproj`, an SPM-only package, Tuist (Swift DSL), or XcodeGen (YAML) — affects team onboarding, merge conflict surface area, and build system flexibility. For macOS apps, the tradeoffs are different from iOS: fewer provisioning profile headaches, but AppKit integration sometimes requires features SPM-only projects do not support well. ## Summary **Pure SPM** (`Package.swift` only) works well for command-line tools, libraries, and simple SwiftUI apps but cannot configure certain Xcode targets (UI tests, app extensions, custom build phases). **Xcode project** (`.xcodeproj`) is the universal default — required for complex apps — but generates verbose, merge-conflict-prone diffs. **Tuist** generates `.xcodeproj`/`.xcworkspace` from a Swift DSL and adds build caching and modularization; it is actively developed and well-suited to large modular codebases. **XcodeGen** generates from a `project.yml` file; lighter weight and stable. Both generators treat the project definition as source of truth and gitignore the generated `.xcodeproj`. ## Deep Guidance ### Pure Swift Package Manager (SPM) Use SPM alone when building a library, CLI tool, or a macOS app simple enough to not need Xcode-managed capabilities. **`Package.swift` structure:** ```swift // swift-tools-version: 6.0 import PackageDescription let package = Package( name: "MyApp", platforms: [ .macOS(.v14) ], products: [ .executable(name: "MyApp", targets: ["MyApp"]) ], dependencies: [ .package(url: "https://github.com/apple/swift-argument-parser", from: "1.5.0"), .package(url: "https://github.com/sparkle-project/Sparkle", from: "2.7.0"), ], targets: [ .executableTarget( name: "MyApp", dependencies: [ .product(name: "ArgumentParser", package: "swift-argument-parser"), .product(name: "Sparkle", package: "Sparkle"), ], path: "Sources/MyApp" ), .testTarget( name: "MyAppTests", dependencies: ["MyApp"], path: "Tests/MyAppTests" ) ] ) ``` **Key SPM commands:** ```bash swift package resolve # Fetch and pin all dependencies swift package update # Update all dependencies to latest compatible versions swift build # Build all targets swift build -c release # Release build swift test # Run all tests (XCTest + Swift Testing) swift package clean # Remove .build directory swift run MyApp # Build and run the named executable target ``` **SPM limitations for macOS apps:** - Cannot define Info.plist content, entitlements, or code signing settings — these require an Xcode project. - Cannot add custom build phases or run script phases. - UI tests (`XCUITest` targets) require Xcode project integration. - App extensions (Share, Today) require Xcode project structure. For any app that needs the App Sandbox, custom entitlements, or Xcode-managed signing, you need an Xcode project — either hand-maintained or generated. ### Hand-Maintained Xcode Project (`.xcodeproj`) The default for most macOS apps. Xcode manages the `.xcodeproj` bundle (a directory containing XML files). These XML files are the source of merge conflicts in team environments. **Reducing `.xcodeproj` churn:** - Keep targets minimal — avoid adding files to the Xcode project if SPM can manage them instead. - Use `SRCROOT`-relative paths; avoid absolute paths in build settings. - Sort file references alphabetically — Xcode does not sort them by default, which causes unnecessary diffs when two developers add files in different orders. - Keep build settings in `.xcconfig` files (text files that diff cleanly) rather than embedded in the `.pbxproj` XML. - Use `xcodegen` or Tuist if merge conflicts in `.pbxproj` become a significant pain point. ### XcodeGen XcodeGen reads a `project.yml` (or `project.json`) file and generates the `.xcodeproj`. The generated project file is gitignored — the YAML is the source of truth. ```yaml # project.yml name: MyApp options: bundleIdPrefix: com.example deploymentTarget: macOS: "14.0" targets: MyApp: type: application platform: macOS sources: [Sources/MyApp] settings: base: INFOPLIST_FILE: Sources/MyApp/Info.plist PRODUCT_BUNDLE_IDENTIFIER: com.example.MyApp dependencies: - package: Sparkle packages: Sparkle: url: https://github.com/sparkle-project/Sparkle from: "2.7.0" ``` ```bash # Generate the project: xcodegen generate ``` XcodeGen is stable, focused, and has a small learning surface. Good choice for simpler apps or teams already comfortable with YAML. ### Tuist Tuist generates Xcode projects from Swift code (`Project.swift`, `Workspace.swift`). Beyond generation, it offers: - **Local build caching** — skip rebuilding unchanged modules. - **Remote caching** (Tuist Cloud) — share build artifacts across the team. - **Scaffolding** — generate new modules from templates. - **Dependency graph validation** — catch circular dependencies at generate time. ```swift // Project.swift import ProjectDescription let project = Project( name: "MyApp", targets: [ .target( name: "MyApp", destinations: .macOS, product: .app, bundleId: "com.example.MyApp", deploymentTargets: .macOS("14.0"), infoPlist: .file(path: "Sources/MyApp/Info.plist"), sources: ["Sources/MyApp/**"], dependencies: [ .external(name: "Sparkle"), ] ), .target( name: "MyAppTests", destinations: .macOS, product: .unitTests, bundleId: "com.example.MyAppTests", sources: ["Tests/MyAppTests/**"], dependencies: [.target(name: "MyApp")] ) ] ) ``` ```bash tuist generate # Generate .xcodeproj and .xcworkspace tuist build # Build (with caching) tuist test # Test (with caching) ``` Tuist is the stronger choice for large modular codebases where build times matter. It has a steeper initial learning curve and more moving parts than XcodeGen. ### SPM Dependency Management in Xcode Projects Add SPM dependencies in Xcode via `File → Add Package Dependencies`, or define them in the `Package.swift` (for SPM-only projects) or in the Xcode project's package list. The resolved versions are recorded in `Package.resolved` — commit this file to ensure reproducible builds. **Version resolution strategies:** - `.exact("2.7.0")` — pin to a specific version (most reproducible for production) - `.upToNextMajor(from: "2.7.0")` — allow minor and patch updates within major version (SemVer-safe) - `.upToNextMinor(from: "2.7.0")` — allow only patch updates - `.branch("main")` — track a branch (use only for local development; not reproducible) **Update all SPM dependencies:** ```bash # In Xcode: File → Packages → Update to Latest Package Versions # On command line (SPM-only projects): swift package update ``` ### Recommended Project Structure ``` MyApp/ ├── Package.swift # Only for pure-SPM projects ├── MyApp.xcodeproj/ # Or MyApp.xcworkspace for SPM+Xcode ├── project.yml # If using XcodeGen ├── Project.swift # If using Tuist ├── Tuist/ # Tuist configuration ├── Sources/ │ └── MyApp/ │ ├── App/ # App entry point, AppDelegate │ ├── Features/ # Feature modules │ ├── Services/ # Network, persistence, system integration │ ├── Models/ # Data models │ └── Resources/ # Assets, Info.plist, entitlements ├── Tests/ │ ├── MyAppTests/ # Unit tests │ └── MyAppUITests/ # XCUITest targets └── fastlane/ # Release automation ```