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
.xcodeprojfile 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 a very simple project spec file like this:
name: MyProject options: bundleIdPrefix: com.myapp 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 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.
Make sure Xcode 9.3 is installed first.
mint install yonaskolb/xcodegen
git clone https://github.com/yonaskolb/XcodeGen.git cd XcodeGen make
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: "1.0.0"),
And then import wherever needed:
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.
- --spec: An optional path to a
.jsonproject spec. Defaults to
- --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
xcodegenis 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 help to see more detailed usage information.
git clone https://github.com/yonaskolb/XcodeGen.git cd XcodeGen swift package generate-xcodeproj
This use Swift Project 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.
- 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
This tool is powered by:
Inspiration for this tool came from:
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. See LICENSE for more info.
Help us keep the lights on
2.2.0 - Jan 28, 2019
- Added ability to generate empty directories via
- Added support for the
instrumentsPackageproduct type #482 @ksulliva
- Added support for
outputFileListswithin project build scripts #500 @lukewakeford
- Added support for a
$target_namereplacement string within target templates #504 @yonaskolb
createIntermediateGroupsto individual Target Sources which overrides the top level option #505 @yonaskolb
- BREAKING: All the paths within
includefiles are now relative to that file and not the root spec. This can be disabled with a
relativePaths: falseon the include. See the documentation for more details #489 @ellneal
- Updated the Xcode compatibility version from 3.2 to 9.3 #497 @yonaskolb
- Exact matches to config names in build settings won't partial apply to other configs #503 @yonaskolb
- UUIDs in the project are standard and don't contain any type prefixes anymore
--projectargument not taking effect #487 @monowerker
- Fixed Sticker Packs from generating an empty Source file phase which caused in error in the new build system #492 @rpassis
- Fixed generated schemes for tool targets not setting the executable #496 @yonaskolb
- Fixed resolving Carthage dependencies for iOS app with watchOS target. 465 @raptorxcz
2.1.0 - Dec 18, 2018
- Added an experiment new caching feature. Pass
--use-cacheto opt in. This will read and write from a cache file to prevent unnecessarily generating the project. Give it a try as it may become the default in a future release #412 @yonaskolb
- Changed spelling of build phases to preBuildPhase and postBuildPhase. The older names are deprecated but still work #402 @brentleyjones
- Moved generation to a specific subcommand
xcodegen generate. Simple
xcodegenwill continue to work for now #437 @yonaskolb
INFOPLIST_FILEhas been set on a target, then an
infopath won't ovewrite it #443 @feischl97
- Fixed XPC Service package type in generated
- Fixed phase ordering for modulemap and static libary header Copy File phases. 402 @brentleyjones
- Fixed intermittent errors when running multiple
xcodegens concurrently #450 @bryansum
--projectargument not working #437 @yonaskolb
- Fixed unit tests not hooking up to host applications properly by default. They now generate a
- Fixed static libraries not including external frameworks in their search paths #454 @brentleyjones
.intentdefinitionfiles to sources build phase instead of resources #442 @yonaskolb
mlmodelfiles to sources build phase instead of resources #457 @dwb357
2.0.0 - Nov 4, 2018
weaklinking setting for dependencies #411 @alvarhansen
infoto targets for generating an
entitlementsto targets for generating an
.entitlementfile #415 @yonaskolb
sdkdependency type for linking system frameworks and libs #430 @yonaskolb
Schemetest targets in an expanded form #434 @yonaskolb
- Validate incorrect config setting definitions #431 @yonaskolb
- Automatically set project
SDKROOTif there is only a single platform within the project #433 @yonaskolb
- Performance improvements for large projects #388 #417 #416 @yonaskolb @kastiglione
- Upgraded to xcodeproj 6 #388 @yonaskolb
- Upgraded to Swift 4.2 #388 @yonaskolb
- Remove iOS codesigning sdk restriction in setting preset #414 @yonaskolb
- Changed default project version to Xcode 10.0 and default Swift version to 4.2 #423 @yonaskolb
- Added ability to not link Carthage frameworks #432 @yonaskolb
- Fixed code signing issues #414 @yonaskolb
TargetSource.headerVisibilitynot being set in initializer #419 @jerrymarino
- Fixed crash when using Xcode Legacy targets as dependencies #427 @dflems
1.11.2 - Sep 19, 2018
If XcodeGen is compiled with Swift 4.2, then UUID's in the generated project will not be deterministic. This will be fixed in an upcoming release with an update to xcodeproj 6.0
- Fixed release builds in Swift 4.2 404 @pepibumur
- Fixed default settings for macOS unit-tests 387 @frankdilo
- Fixed Copy Headers phase ordering for Xcode 10 401 @brentleyjones
- Fixed generated schemes on aggregate targets 394 @vgorloff
enas default value for knownRegions 390 @Saik0s