XcodeGen — Generate Xcode Projects from YAML Specs

Introduction

XcodeGen generates .xcodeproj files from a declarative YAML specification. By keeping your project definition in a human-readable spec and gitignoring the .xcodeproj, you eliminate merge conflicts on the project file, the single most common source of frustration in team-based iOS development.

What XcodeGen Does

• Generates complete .xcodeproj files from a project.yml specification
• Eliminates merge conflicts by making the project file disposable and regenerable
• Supports multiple targets, schemes, build configurations, and test plans
• Automatically discovers source files from directory paths
• Handles dependencies including SPM packages, Carthage frameworks, and CocoaPods

Architecture Overview

XcodeGen reads a project.yml specification and builds an in-memory model of the Xcode project structure (targets, build settings, file references, groups, schemes). It then serializes this model into the .xcodeproj bundle format using the XcodeProj library. Source file discovery walks the directories specified in the YAML and creates file references with appropriate build phase assignments based on file extension.

Self-Hosting & Configuration

• Install via Homebrew: brew install xcodegen
• Or via Mint: mint install yonaskolb/xcodegen
• Define your project structure in project.yml at the repository root
• Add .xcodeproj to .gitignore and regenerate on clone
• Run xcodegen generate after changing the spec or adding new source files

Key Features

• Human-readable YAML project definition that diffs cleanly in version control
• Automatic source file discovery with glob and exclude patterns
• Multi-target support for apps, frameworks, extensions, and test bundles
• Scheme generation with configurable build, test, run, and archive actions
• Template and include support for sharing configuration across multiple targets

Comparison with Similar Tools

• Tuist — project generation with dependency graph management and caching; more opinionated, larger tool
• Manual .xcodeproj — no tooling required but merge conflicts are frequent in teams
• Bazel / Buck2 — full build systems with Xcode project generation; far heavier setup
• xcodebuild — command-line build tool; does not generate or manage project files
• Swift Package Manager — manages dependencies and simple project structures; limited for complex multi-target apps

FAQ

Q: Do I need to regenerate the project every time I add a file? A: If you use directory-based source references, XcodeGen auto-discovers new files on regeneration. Run xcodegen generate after adding files.

Q: Can XcodeGen handle multiple platforms in one project? A: Yes. Define separate targets for each platform (iOS, macOS, watchOS) in the same project.yml.

Q: How does XcodeGen interact with CocoaPods? A: Run xcodegen generate first, then pod install. CocoaPods modifies the generated workspace to add its integration.

Q: Can I still use Xcode's GUI to modify build settings? A: You can, but changes to the .xcodeproj are lost on regeneration. All persistent settings should go in project.yml.

Sources

• https://github.com/yonaskolb/XcodeGen
• https://github.com/yonaskolb/XcodeGen/blob/master/Docs/ProjectSpec.md