XcodeGen

A Swift command line tool for generating your Xcode project

6,992

816

6,992

353

View on GitHub

Top Related Projects

SwiftLint

18,578

A tool to enforce Swift style and conventions.

Carthage

14,950

A simple, decentralized dependency manager for Cocoa

R.swift

9,493

Strong typed, autocompleted resources like images, fonts and segues in Swift projects

SwiftGen

9,230

The Swift code generator for your assets, storyboards, Localizable.strings, … — Get rid of all String-based APIs!

Quick Overview

XcodeGen is a command-line tool that generates Xcode projects based on a simple spec file. It simplifies the process of managing Xcode projects, especially for large or complex iOS, macOS, or tvOS applications. XcodeGen allows developers to define their project structure, targets, and build settings in a YAML or JSON file, which can be version controlled and shared across teams.

Pros

Simplifies project management by using a declarative spec file instead of complex Xcode project files
Improves collaboration and reduces merge conflicts in version control
Allows for easy customization and configuration of project settings
Supports generation of schemes, build phases, and dependencies

Cons

Requires learning a new syntax and structure for defining projects
May not support all advanced Xcode features or custom configurations
Initial setup and migration from existing projects can be time-consuming
Potential for discrepancies between generated project and spec file if not managed carefully

Code Examples

# Example XcodeGen spec file
name: MyApp
options:
  bundleIdPrefix: com.example
targets:
  MyApp:
    type: application
    platform: iOS
    sources: [Sources]
    settings:
      base:
        INFOPLIST_FILE: Sources/Info.plist
        PRODUCT_BUNDLE_IDENTIFIER: com.example.MyApp

This YAML code defines a basic XcodeGen spec file for an iOS application.

# Adding dependencies to the spec file
targets:
  MyApp:
    dependencies:
      - target: MyFramework
      - carthage: Alamofire
      - package: SwiftPackage

This example shows how to add dependencies to a target in the XcodeGen spec file.

# Configuring build settings
targets:
  MyApp:
    settings:
      base:
        SWIFT_VERSION: 5.0
      configs:
        Debug:
          SWIFT_OPTIMIZATION_LEVEL: -Onone
        Release:
          SWIFT_OPTIMIZATION_LEVEL: -O

This code demonstrates how to configure build settings for different configurations in XcodeGen.

Getting Started

Install XcodeGen using Homebrew:
```
brew install xcodegen
```
Create a project.yml file in your project directory with your desired configuration.
Run XcodeGen to generate the Xcode project:
```
xcodegen generate
```
Open the generated .xcodeproj file in Xcode and start developing.

Competitor Comparisons

tuist

4,503

Tuist's CLI

Pros of Tuist

More comprehensive project management with built-in dependency resolution
Offers a complete CLI tool for project generation and management
Provides a domain-specific language (DSL) for project configuration

Cons of Tuist

Steeper learning curve due to its custom DSL and project structure
Less flexibility for complex, custom Xcode configurations
Requires more setup and integration compared to XcodeGen

Code Comparison

Tuist project definition:

let project = Project(
    name: "MyApp",
    targets: [
        Target(
            name: "App",
            platform: .iOS,
            product: .app,
            bundleId: "com.example.app",
            infoPlist: "Info.plist",
            sources: ["Sources/**"]
        )
    ]
)

XcodeGen project definition:

name: MyApp
targets:
  App:
    type: application
    platform: iOS
    deploymentTarget: "13.0"
    sources: [Sources]
    info:
      path: Info.plist
      properties:
        CFBundleIdentifier: com.example.app

Both tools aim to simplify Xcode project management, but Tuist offers a more comprehensive solution with its own ecosystem, while XcodeGen focuses on generating Xcode projects from YAML specifications. XcodeGen may be easier to adopt for simpler projects, while Tuist provides more powerful features for complex, multi-module projects.

SwiftLint

18,578

A tool to enforce Swift style and conventions.

Pros of SwiftLint

Extensive set of predefined rules for Swift code style and conventions
Highly customizable with the ability to enable/disable rules and set custom thresholds
Integrates well with various IDEs and CI/CD pipelines

Cons of SwiftLint

Focuses solely on code linting, unlike XcodeGen which generates Xcode projects
Can be resource-intensive for large projects, potentially slowing down build times
Requires initial setup and configuration to align with team preferences

Code Comparison

SwiftLint configuration example:

disabled_rules:
  - trailing_whitespace
opt_in_rules:
  - empty_count
  - missing_docs
line_length:
  warning: 120
  error: 200

XcodeGen project specification example:

name: MyProject
options:
  bundleIdPrefix: com.company
targets:
  MyApp:
    type: application
    platform: iOS
    sources: [MyApp]

While SwiftLint focuses on enforcing code style and quality, XcodeGen is designed to generate Xcode project files. SwiftLint is more about maintaining code consistency, whereas XcodeGen aims to simplify project setup and management. Both tools serve different purposes in the iOS development workflow, with SwiftLint being more focused on code quality and XcodeGen on project structure.

CocoaPods

14,559

The Cocoa Dependency Manager.

Pros of CocoaPods

Widely adopted and well-established in the iOS development community
Supports a vast library of third-party dependencies
Integrates seamlessly with Xcode and provides a user-friendly interface

Cons of CocoaPods

Can slow down project build times, especially for larger projects
Requires maintenance of a separate Podfile and occasional pod updates
May introduce complexities in version management and conflicts

Code Comparison

CocoaPods (Podfile):

platform :ios, '13.0'
use_frameworks!

target 'MyApp' do
  pod 'Alamofire', '~> 5.0'
end

XcodeGen (project.yml):

name: MyApp
options:
  bundleIdPrefix: com.example
targets:
  MyApp:
    type: application
    platform: iOS
    deploymentTarget: "13.0"
    sources: [MyApp]
    dependencies:
      - package: Alamofire

XcodeGen focuses on generating Xcode projects from a YAML configuration, while CocoaPods primarily manages dependencies. XcodeGen offers more flexibility in project structure and can be faster for large projects, but CocoaPods has a larger ecosystem and is more widely used. The choice between them depends on specific project requirements and team preferences.

Carthage

14,950

A simple, decentralized dependency manager for Cocoa

Pros of Carthage

Decentralized dependency manager, allowing direct use of GitHub repositories
Builds frameworks instead of modifying project structures
Supports a wide range of platforms (iOS, macOS, tvOS, watchOS)

Cons of Carthage

Slower build times compared to XcodeGen
Requires manual framework linking in Xcode
Less integration with Xcode's native dependency management

Code Comparison

XcodeGen:

name: MyProject
targets:
  MyApp:
    type: application
    platform: iOS
    sources: [MyApp]
    dependencies:
      - target: MyFramework

Carthage:

github "Alamofire/Alamofire" ~> 5.0
github "ReactiveX/RxSwift" ~> 6.0

XcodeGen focuses on generating Xcode project files from a YAML specification, while Carthage manages dependencies by building frameworks. XcodeGen provides more control over project structure, while Carthage offers a simpler approach to dependency management. XcodeGen integrates better with Xcode's native features, whereas Carthage provides more flexibility in terms of dependency sources.

R.swift

9,493

Strong typed, autocompleted resources like images, fonts and segues in Swift projects

Pros of R.swift

Focuses specifically on resource management, providing a more specialized solution for handling assets, colors, and strings
Generates strongly-typed accessors for resources, reducing the risk of runtime errors due to typos or missing resources
Integrates well with Swift's type system, offering better autocomplete and compile-time checks

Cons of R.swift

Limited to resource management, unlike XcodeGen which offers broader project configuration capabilities
Requires manual setup and integration into the build process, whereas XcodeGen can generate the entire Xcode project
May add additional build time due to code generation step, especially for large projects with many resources

Code Comparison

R.swift:

let icon = R.image.settingsIcon()
let title = R.string.localizable.settingsTitle()
let color = R.color.primaryColor()

XcodeGen (project configuration):

targets:
  MyApp:
    type: application
    platform: iOS
    sources: [Sources]
    resources: [Resources]

While not directly comparable in functionality, this comparison illustrates the different focus areas of the two tools. R.swift generates code for accessing resources, while XcodeGen defines the project structure and configuration.

SwiftGen

9,230

The Swift code generator for your assets, storyboards, Localizable.strings, … — Get rid of all String-based APIs!

Pros of SwiftGen

Generates type-safe code for various resources (strings, images, fonts, etc.)
Supports multiple input formats (JSON, YAML, Plist, etc.)
Highly customizable output templates

Cons of SwiftGen

Focused solely on resource code generation, not project configuration
Requires manual integration into the build process
May require more setup time for complex resource structures

Code Comparison

SwiftGen (example output for localized strings):

enum L10n {
  enum Greetings {
    static let welcome = L10n.tr("Localizable", "greetings.welcome")
  }
}

XcodeGen (example project configuration):

name: MyApp
targets:
  MyApp:
    type: application
    platform: iOS
    sources: [Sources]
    settings:
      base:
        INFOPLIST_FILE: Info.plist
        PRODUCT_BUNDLE_IDENTIFIER: com.example.myapp

SwiftGen focuses on generating type-safe code for resources, while XcodeGen is primarily used for project configuration and generation. SwiftGen provides more granular control over resource access, but XcodeGen offers a broader scope of project management features. The choice between the two depends on specific project needs and workflow preferences.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

XcodeGen

XcodeGen is a command line tool written in Swift that generates your Xcode project using your folder structure and a project spec.

The project spec is a YAML or JSON file that defines your targets, configurations, schemes, custom build settings and many other options. All your source directories are automatically parsed and referenced appropriately while preserving your folder structure. Sensible defaults are used in many places, so you only need to customize what is needed. Very complex projects can also be defined using more advanced features.

â Generate projects on demand and remove your .xcodeproj from git, which means no more merge conflicts!
â Groups and files in Xcode are always synced to your directories on disk
â Easy configuration of projects which is human readable and git friendly
â Easily copy and paste files and directories without having to edit anything in Xcode
â Share build settings across multiple targets with build setting groups
â Automatically generate Schemes for different environments like test and production
â Easily create new projects with complicated setups on demand without messing around with Xcode
â Generate from anywhere including on CI
â Distribute your spec amongst multiple files for easy sharing and overriding
â Easily create multi-platform frameworks
â Integrate Carthage frameworks without any work

Given an example project spec:

name: MyProject
include:
  - base_spec.yml
options:
  bundleIdPrefix: com.myapp
packages:
  Yams:
    url: https://github.com/jpsim/Yams
    from: 2.0.0
targets:
  MyApp:
    type: application
    platform: iOS
    deploymentTarget: "10.0"
    sources: [MyApp]
    settings:
      configs:
        debug:
          CUSTOM_BUILD_SETTING: my_debug_value
        release:
          CUSTOM_BUILD_SETTING: my_release_value
    dependencies:
      - target: MyFramework
      - carthage: Alamofire
      - framework: Vendor/MyFramework.framework
      - sdk: Contacts.framework
      - sdk: libc++.tbd
      - package: Yams
  MyFramework:
    type: framework
    platform: iOS
    sources: [MyFramework]

A project would be created with 2 connected targets, with all the required configurations and build settings. See the Project Spec documentation for all the options you can specify, and Usage for more general documentation.

Installing

Make sure the latest stable (non-beta) version of Xcode is installed first.

Mint

mint install yonaskolb/xcodegen

Make

git clone https://github.com/yonaskolb/XcodeGen.git
cd XcodeGen
make install

Homebrew

brew install xcodegen

Swift Package Manager

Use as CLI

git clone https://github.com/yonaskolb/XcodeGen.git
cd XcodeGen
swift run xcodegen

Use as dependency

Add the following to your Package.swift file's dependencies:

.package(url: "https://github.com/yonaskolb/XcodeGen.git", from: "2.42.0"),

And then import wherever needed: import XcodeGenKit

Usage

Simply run:

xcodegen generate

This will look for a project spec in the current directory called project.yml and generate an Xcode project with the name defined in the spec.

Options:

--spec: An optional path to a .yml or .json project spec. Defaults to project.yml. (It is also possible to link to multiple spec files by comma separating them. Note that all other flags will be the same.)
--project: An optional path to a directory where the project will be generated. By default this is the directory the spec lives in.
--quiet: Suppress informational and success messages.
--use-cache: Used to prevent unnecessarily generating the project. If this is set, then a cache file will be written to when a project is generated. If xcodegen is later run but the spec and all the files it contains are the same, the project won't be generated.
--cache-path: A custom path to use for your cache file. This defaults to ~/.xcodegen/cache/{PROJECT_SPEC_PATH_HASH}

There are other commands as well such as xcodegen dump which lets one output the resolved spec in many different formats, or write it to a file. Use xcodegen help to see more detailed usage information.

Editing

git clone https://github.com/yonaskolb/XcodeGen.git
cd XcodeGen
swift package generate-xcodeproj

This uses Swift Package Manager to create an xcodeproj file that you can open, edit and run in Xcode, which makes editing any code easier.

If you want to pass any required arguments when running in Xcode, you can edit the scheme to include launch arguments.

Documentation

See Project Spec documentation for all the various properties and options that can be set
See Usage for more specific usage and use case documentation
See FAQ for a list of some frequently asked questions
See Examples for some real world XcodeGen project specs out in the wild