Repository files navigation

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 meansno more merge conflicts!
• ✅ Groups and files in Xcode are alwayssynced to your directories on disk
• ✅ Easyconfiguration of projects which is human readable and git friendly
• ✅ Easily copy and pastefiles and directories without having to edit anything in Xcode
• ✅ Share build settings across multiple targets withbuild setting groups
• ✅ Automatically generate Schemes fordifferent environments like test and production
• ✅ Easilycreate new projects with complicated setups on demand without messing around with Xcode
• ✅ Generate from anywhere including onCI
• ✅ Distribute your spec amongst multiple files for easysharing and overriding
• ✅ Easily createmulti-platform frameworks
• ✅ IntegrateCarthage frameworks without any work

Given an example project spec:

name:MyProjectinclude:  -base_spec.ymloptions:bundleIdPrefix:com.myapppackages:Yams:url:https://github.com/jpsim/Yamsfrom:2.0.0targets:MyApp:type:applicationplatform:iOSdeploymentTarget:"10.0"sources:[MyApp]settings:configs:debug:CUSTOM_BUILD_SETTING:my_debug_valuerelease:CUSTOM_BUILD_SETTING:my_release_valuedependencies:      -target:MyFramework      -carthage:Alamofire      -framework:Vendor/MyFramework.framework      -sdk:Contacts.framework      -sdk:libc++.tbd      -package:YamsMyFramework:type:frameworkplatform:iOSsources:[MyFramework]

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

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

mint install yonaskolb/xcodegen

git clone https://github.com/yonaskolb/XcodeGen.gitcd XcodeGenmake install

brew install xcodegen

Use as CLI

git clone https://github.com/yonaskolb/XcodeGen.gitcd XcodeGenswift 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.44.1"),

And then import wherever needed:import XcodeGenKit

Simply run:

xcodegen generate

This will look for a project spec in the current directory calledproject.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 toproject.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. Ifxcodegen 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 asxcodegen dump which lets one output the resolved spec in many different formats, or write it to a file. Usexcodegen help to see more detailed usage information.

git clone https://github.com/yonaskolb/XcodeGen.gitcd XcodeGenswift package generate-xcodeproj

This uses Swift Package Manager to create anxcodeproj 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.

• SeeProject Spec documentation for all the various properties and options that can be set
• SeeUsage for more specific usage and use case documentation
• SeeFAQ for a list of some frequently asked questions
• SeeExamples for some real world XcodeGen project specs out in the wild

If XcodeGen doesn't meet your needs try these great alternatives:

• Tuist
• Xcake
• struct

This tool is powered by:

• XcodeProj
• JSONUtilities
• Spectre
• PathKit
• Yams
• SwiftCLI

Inspiration for this tool came from:

• struct
• Xcake
• CocoaPods Xcodeproj

Pull requests and issues are always welcome. Please open any issues and PRs for bugs, features, or documentation.

XcodeGen is licensed under the MIT license. SeeLICENSE for more info.