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.xcodeprojfrom 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 -
✅ Export Dependency Diagrams to view in Graphviz
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 Xcode 11 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.25.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
.ymlor.jsonproject spec. Defaults toproject.yml - --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/cache/{PROJECT_SPEC_PATH_HASH}
There are other commands as well such as xcodegen dump which lets out output the resolved spec in many different formats, or write it to a file. Use xcodegen help to see more detailed usage information.
Dependency Diagrams
Click to expand!
How to export dependency diagrams:
To stdout:
xcodegen dump --type graphviz
To a file:
xcodegen dump --type graphviz --file Graph.viz
During implementation, graphviz formatting was validated using GraphvizOnline, WebGraphviz, and Graphviz on MacOS.
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
Alternatives
If XcodeGen doesn't meet your needs try these great alternatives:
Attributions
This tool is powered by:
Inspiration for this tool came from:
Contributions
Pull requests and issues are always welcome. Please open any issues and PRs for bugs, features, or documentation.
License
XcodeGen is licensed under the MIT license. See LICENSE for more info.
238 Sep 12, 2022
2k Dec 11, 2022
143 Oct 11, 2022
8.3k Jan 5, 2023
348 Sep 18, 2022
123 Jun 29, 2022
338 Nov 29, 2022
822 Dec 21, 2022
73 Nov 9, 2020
233 Dec 28, 2022
510 Nov 24, 2022
310 Sep 9, 2022
242 Dec 16, 2022
339 Dec 6, 2022
2.6k Dec 17, 2022
377 Dec 1, 2022
8.9k Jan 6, 2023
7.2k Jan 3, 2023