This gives us an entry point for disabling specific project.yml validations that sometimes shouldn't apply. The first example is missingConfigs, which, if you use your .yml file in multiple projects, can be too strict if the projects have different top level configurations.
21 KiB
Project Spec
The project spec can be written in either YAML or JSON. All the examples below use YAML.
Required properties are marked with checkbox. Some of the YAML examples don't show all the required properties. For example not all target examples will have a platform or type, even though they are required.
Index
Project
- name: String - Name of the generated project
- include: Include - One or more paths to other specs
- options: Options - Various options to override default behaviour
- attributes: [String: Any] - The PBXProject attributes. This is for advanced use. This defaults to
{"LastUpgradeCheck": "XcodeVersion"}
withxcodeVersion
being set by Options.xcodeVersion
- configs: Configs - Project build configurations. Defaults to
Debug
andRelease
configs - configFiles: Config Files -
.xcconfig
files per config - settings: Settings - Project specific settings. Default base and config type settings will be applied first before any settings defined here
- settingGroups: Setting Groups - Setting groups mapped by name
- targets: Target - The list of targets in the project mapped by name
- fileGroups: [String] - A list of paths to add to the top level groups. These are files that aren't build files but that you'd like in the project hierachy. For example a folder xcconfig files that aren't already added by any target sources.
- schemes: Scheme - A list of schemes by name. This allows more control over what is found in Target Scheme
Include
One or more specs can be included in the project spec. This can be used to split your project spec into multiple files, for easier structuring or sharing between multiple specs. Included specs can also include other specs and so on.
Include can either be a list of string paths or a single string path. They will be merged in order and then the current spec will be merged on top. By default specs are merged additively. That is for every value:
- if existing value and new value are both dictionaries merge them and continue down the hierachy
- if existing value and new value are both an array then add the new value to the end of the array
- otherwise replace the existing value with the new value
This merging behaviour can be overridden on a value basis. If you wish to replace a whole value (set a new dictionary or new array instead of merging them) then just affix :REPLACE
to the key
include:
- base.yml
name: CustomSpec
targets:
MyTarget: # target lives in base.yml
sources:REPLACE:
- my_new_sources
Note that target names can also be changed by adding a name
property to a target.
Options
- carthageBuildPath: String - The path to the carthage build directory. Defaults to
Carthage/Build
. This is used when specifying target carthage dependencies - createIntermediateGroups: Bool - If this is specified and set to
true
, then intermediate groups will be created for every path component between the folder containing the source and next existing group it finds or the base path. For example, when enabled if a source path is specified asVendor/Foo/Hello.swift
, the groupVendor
will created as a parent of theFoo
group. - bundleIdPrefix: String - If this is specified then any target that doesn't have an
PRODUCT_BUNDLE_IDENTIFIER
(via all levels of build settings) will get an autogenerated one by combiningbundleIdPrefix
and the target name:bundleIdPrefix.name
. The target name will be stripped of all characters that aren't alphanumerics, hyphens, or periods. Underscores will be replace with hyphens. - settingPresets: String - This controls the settings that are automatically applied to the project and its targets. These are the same build settings that Xcode would add when creating a new project. Project settings are applied by config type. Target settings are applied by the product type and platform. By default this is set to
all
all
: project and target settingsproject
: only project settingstargets
: only target settingsnone
: no settings are automatically applied
- developmentLanguage: String - Sets the development language of the project. Defaults to
en
- usesTabs: Bool - If this is specified, the Xcode project will override the user's setting determining whether or not tabs or spaces should be used in the project.
- indentWidth: Int - If this is specified, the Xcode project will override the user's setting for indent width in number of spaces.
- tabWidth: Int - If this is specified, the Xcode project will override the user's setting for indent width in number of spaces.
- xcodeVersion: String - The version of Xcode. This defaults to the latest version periodically. You can specify it in the format
0910
or9.1
- deploymentTarget: [Platform: String] - A project wide deployment target can be specified for each platform otherwise the default SDK version in Xcode will be used. This will be overridden by any custom build settings that set the deployment target eg
IPHONEOS_DEPLOYMENT_TARGET
. Target specific deployment targets can also be set with Target.deploymentTarget. - disabledValidations: [String] - A list of validations that can be disabled if they're too strict for your use case. By default this is set to an empty array. Currently these are the available options:
missingConfigs
: Disable errors for configurations in yaml files that don't exist in the project itself. This can be useful if you include the same yaml file in different projects
options:
deploymentTarget:
watchOS: 2.0
tvOS: 10.0
Configs
Each config maps to a build type of either debug
or release
which will then apply default build settings to the project. Any value other than debug
or release
(for example none
), will mean no default build settings will be applied to the project.
configs:
Debug: debug
Release: release
If no configs are specified, default Debug
and Release
configs will be created automatically.
Setting Groups
Setting groups are named groups of build settings that can be reused elsewhere. Each preset is a Settings schema, so can include other groups
settingGroups:
preset1:
BUILD_SETTING: value
preset2:
base:
BUILD_SETTING: value
groups:
- preset
preset3:
configs:
debug:
groups:
- preset
Settings
Settings can either be a simple map of build settings [String:String]
, or can be more advanced with the following properties:
- groups: [String] - List of setting groups to include and merge
- configs: [String:Settings] - Mapping of config name to a settings spec. These settings will only be applied for that config. Each key will be matched to any configs that contain the key and is case insensitive. So if you had
Staging Debug
andStaging Release
, you could apply settings to both of them usingstaging
. - base: [String:String] - Used to specify default settings that apply to any config
settings:
BUILD_SETTING_1: value 1
BUILD_SETTING_2: value 2
settings:
base:
BUILD_SETTING_1: value 1
configs:
my_config:
BUILD_SETTING_2: value 2
groups:
- my_settings
Settings are merged in the following order: groups, base, configs.
Target
- type: Product Type - Product type of the target
- platform: Platform - Platform of the target
- deploymentTarget: String or Double - The deployment target eg (11.0). If this is not specified the value from the project set in Options
.deploymentTarget.PLATFORM
will be used. - sources: Sources - Source directories of the target
- configFiles: Config Files -
.xcconfig
files per config - settings: Settings - Target specific build settings. Default platform and product type settings will be applied first before any custom settings defined here. Other context dependant settings will be set automatically as well:
INFOPLIST_FILE
: If it doesn't exist your sources will be searched forInfo.plist
files and the first one found will be used for this settingFRAMEWORK_SEARCH_PATHS
: If carthage dependencies are used, the platform build path will be added to this setting
- prebuildScripts: [Build Script] - Build scripts that run before any other build phases
- postbuildScripts: [Build Script] - Build scripts that run after any other build phases
- dependencies: [Dependency] - Dependencies for the target
- scheme: Target Scheme - Generated scheme with tests or config variants
- legacy: Legacy Target - When present, opt-in to make an Xcode "External Build System" legacy target instead.
Product Type
This will provide default build settings for a certain product type. It can be any of the following:
application
application.messages
application.watchapp
application.watchapp2
app-extension.messages
app-extension.messages-sticker-pack
app-extension
bundle
bundle.unit-test
bundle.ui-testing
bundle.ocunit-test
framework
library.dynamic
library.static
tool
tv-app-extension
watchkit-extension
watchkit2-extension
xpc-service
""
(used for legacy targets)
Platform
This will provide default build settings for a certain platform. It can be any of the following:
iOS
tvOS
macOS
watchOS
Multi Platform targets
You can also specify an array of platforms. This will generate a target for each platform.
If you reference the string $platform
anywhere within the target spec, that will be replaced with the platform.
The generated targets by default will have a suffix of _$platform
applied, you can change this by specifying a platformSuffix
or platformPrefix
.
If no PRODUCT_NAME
build setting is specified for a target, this will be set to the target name, so that this target can be imported under a single name.
targets:
MyFramework:
sources: MyFramework
platform: [iOS, tvOS]
type: framework
settings:
base:
INFOPLIST_FILE: MyApp/Info.plist
PRODUCT_BUNDLE_IDENTIFIER: com.myapp
MY_SETTING: platform $platform
groups:
- $platform
The above will generate 2 targets named MyFramework_iOS
and MyFramework_tvOS
, with all the relevant platform build settings. They will both have a PRODUCT_NAME
of MyFramework
Sources
Specifies the source directories for a target. This can either be a single source or a list of sources. Applicable source files, resources, headers, and .lproj
files will be parsed appropriately.
A source can be provided via a string (the path) or an object of the form:
Target Source Object:
- path: String - The path to the source file or directory.
- name: String - Can be used to override the name of the source file or directory. By default the last component of the path is used for the name
- compilerFlags: [String] or String - A list of compilerFlags to add to files under this specific path provided as a list or a space delimitted string. Defaults to empty.
- excludes: [String] or String - A list of global patterns representing the files to exclude.
- optional: Bool - Disable missing path check. Defaults to false.
- buildPhase: String - This manually sets the build phase this file or files in this directory will be added to, otherwise XcodeGen will guess based on the file extension. Note that
Info.plist
files will never be added to any build phases, no matter what this setting is. Possible values are:sources
- Compile Sources phaseresources
- Copy Bundle Resources phaseheaders
- Headers Phasenone
- Will not be added to any build phases
- type: String: This can be one of the following values
file
: a file reference with a parent group will be created (Default for files or directories with extensions)group
: a group with all it's containing files. (Default for directories without extensions)folder
: a folder reference.
targets:
MyTarget
sources: MyTargetSource
MyOtherTarget
sources:
- MyOtherTargetSource1
- path: MyOtherTargetSource2
name: MyNewName
excludes:
- "ios/*.[mh]"
- "configs/server[0-2].json"
- "*-Private.h"
compilerFlags:
- "-Werror"
- "-Wextra"
- path: MyOtherTargetSource3
compilerFlags: "-Werror -Wextra"
- path: Resources
type: folder
Dependency
A dependency can be one of a 3 types:
target: name
- links to another targetframework: path
- links to a frameworkcarthage: name
- helper for linking to a Carthage framework
Embed options:
These only applied to target
and framework
dependencies.
- embed: Bool - Whether to embed the dependency. Defaults to true for application target and false for non application targets.
- link: Bool - Whether to link the dependency. Defaults to true but only static library and dynamic frameworks are linked. This only applies for target dependencies.
- codeSign: Bool - Whether the
codeSignOnCopy
setting is applied when embedding framework. Defaults to true - removeHeaders: Bool - Whether the
removeHeadersOnCopy
setting is applied when embedding the framework. Defaults to true
Implicit Framework options:
This only applies to framework
dependencies. Implicit framework dependencies are useful in Xcode Workspaces which have multiple .xcodeproj
that are not embedded within each other yet have a dependency on a framework built in an adjacent .xcodeproj
. By having Find Implicit Dependencies
checked within your scheme Build Options
Xcode can link built frameworks in BUILT_PRODUCTS_DIR
.
- implicit: Bool - Whether the framework is an implicit dependency. Defaults to
false
.
Carthage Dependency
Carthage frameworks are expected to be in CARTHAGE_BUILD_PATH/PLATFORM/FRAMEWORK.framework
where:
CARTHAGE_BUILD_PATH
=options.carthageBuildPath
orCarthage/Build
by defaultPLATFORM
= the target's platformFRAMEWORK
= the specified name.
If any applications contain carthage dependencies within itself or any dependent targets, a carthage copy files script is automatically added to the application containing all the relevant frameworks. A FRAMEWORK_SEARCH_PATHS
setting is also automatically added
targets:
MyTarget:
dependencies:
- target: MyFramework
- framework: path/to/framework.framework
- carthage: Result
MyFramework:
type: framework
Config Files
Specifies .xcconfig
files for each configuration.
targets:
MyTarget:
configFiles:
Debug: config_files/debug.xcconfig
Release: config_files/release.xcconfig
Build Script
Run script build phases added via prebuildScripts or postBuildScripts. They run before or after any other build phases respectively and in the order defined. Each script can contain:
- path: String - a relative or absolute path to a shell script
- script: String - an inline shell script
- name: String - name of a script. Defaults to
Run Script
- inputFiles: [String] - list of input files
- outputFiles: [String] - list of output files
- shell: String - shell used for the script. Defaults to
/bin/sh
- runOnlyWhenInstalling: Bool - whether the script is only run when installing (
runOnlyForDeploymentPostprocessing
). Defaults to no
Either a path or script must be defined, the rest are optional.
A multiline script can be written using the various YAML multiline methods, for example with |
as below:
targets:
MyTarget:
prebuildScripts:
- path: myscripts/my_script.sh
name: My Script
inputFiles:
- $(SRCROOT)/file1
- $(SRCROOT)/file2
outputFiles:
- $(DERIVED_FILE_DIR)/file1
- $(DERIVED_FILE_DIR)/file2
postbuildScripts:
- script: swiftlint
name: Swiftlint
- script: |
command do
othercommand
Target Scheme
This is a convenience used to automatically generate schemes for a target based on different configs or included tests. If you want more control check out the top level Scheme.
- configVariants: [String] - This generates a scheme for each entry, using configs that contain the name with debug and release variants. This is useful for having different environment schemes.
- testTargets: [String] - a list of test targets that should be included in the scheme. These will be added to the build targets and the test entries
- gatherCoverageData: Bool - a boolean that indicates if this scheme should gather coverage data. This defaults to false
- commandLineArguments: [String:Bool] - a dictionary from the argument name (
String
) to if it is enabled (Bool
). These arguments will be added to the Test, Profile and Run scheme actions
For example, the spec below would create 3 schemes called:
- MyApp Test
- MyApp Staging
- MyApp Production
Each scheme would use different build configuration for the different build types, specifically debug configs for run
, test
, and analyze
, and release configs for profile
and archive
.
The MyUnitTests target would also be linked.
configs:
Test Debug: debug
Staging Debug: debug
Production Debug: debug
Test Release: release
Staging Release: release
Production Release: release
targets
MyApp:
scheme:
testTargets:
- MyUnitTests
configVariants:
- Test
- Staging
- Production
gatherCoverageData: true
commandLineArguments:
"-MyEnabledArg": true
"-MyDisabledArg": false
MyUnitTests:
sources: Tests
Legacy Target
By providing a legacy target, you are opting in to the "Legacy Target" mode. This is the "External Build Tool" from the Xcode GUI. This is useful for scripts that you want to run as dependencies of other targets, but you want to make sure that it only runs once even if it is specified as a dependency from multiple other targets.
- toolPath: String - Path to the build tool used in the legacy target.
- arguments: String - Build arguments used for the build tool in the legacy target
- passSettings: Bool - Whether or not to pass build settings down to the build tool in the legacy target.
- workingDirectory: String - The working directory under which the build tool will be invoked in the legacy target.
Scheme
Schemes allows for more control than the convenience Target Scheme on Target
- build: Build options
- run: The run action
- test: The test action
- profile: The profile action
- analyze: The analyze action
- archive: The archive action
Build
- targets: String or [String] - A map of target names to build and which build types they should be enabled for. The buildTypes can either be
all
,none
or an array of the following types:run
test
profile
analyze
archive
Common Build Action options
The different actions share some properties:
- config: String - All build actions can be set to use a certain config. If this is not set the first configuration found of a certain type will be used, depending on the type:
debug
: run, test, analyzerelease
: profile, archive
- commandLineArguments: [String:Bool] -
run
,test
andprofile
actions have a map of command line arguments to whether they are enabled
Test Action
- gatherCoverageData: Bool - a boolean that indicates if this scheme should gather coverage data. This defaults to false
- targets: [String] - a list of targets to test
scheme:
Production:
build:
targets:
MyTarget1: all
MyTarget2: [run, archive]
run:
config: prod-debug
commandLineArguments: "--option value"
test:
config: prod-debug
commandLineArguments: "--option testValue"
gatherCoverageData: true
targets: [Tester1, Tester2]
profile:
config: prod-release
analyze:
config: prod-debug
archive:
config: prod-release