# XcodeGen — Generate Xcode Projects from YAML Specs

> A command-line tool that generates Xcode project files from a simple YAML or JSON specification, eliminating merge conflicts in .xcodeproj files.

## Install

Save in your project root:

# XcodeGen — Generate Xcode Projects from YAML Specs

## Quick Use
```bash
brew install xcodegen

# Create project.yml in your repo root:
# name: MyApp
# targets:
#   MyApp:
#     type: application
#     platform: iOS
#     deploymentTarget: "16.0"
#     sources: [Sources]
#     settings:
#       SWIFT_VERSION: "5.9"

xcodegen generate
# Opens the generated MyApp.xcodeproj
```

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

---
Source: https://tokrepo.com/en/workflows/asset-1df1c969
Author: AI Open Source