Skip to content

Latest commit

 

History

History
741 lines (614 loc) · 37.8 KB

ProjectSpec.md

File metadata and controls

741 lines (614 loc) · 37.8 KB
Raw

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"} with xcodeVersion being set by Options.xcodeVersion
  • configs: Configs - Project build configurations. Defaults to Debug and Release 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: [String: Target] - The list of targets in the project mapped by name
  • fileGroups: [String] - A list of paths to add to the root of the project. These aren't files that will be included in your targets, but that you'd like to include in the project hierachy anyway. For example a folder of xcconfig files that aren't already added by any target sources, or a Readme file.
  • schemes: Scheme - A list of schemes by name. This allows more control over what is found in Target Scheme
  • targetTemplates: [String: Target Template] - a list of targets that can be used as templates for actual targets which reference them via a template property. They can be used to extract common target settings. Works great in combination with include.

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 includes or a single include. They will be merged in order and then the current spec will be merged on top.

An include can be provided via a string (the path) or an object of the form:

Include Object

  • path: String - The path to the included file.
  • relativePaths: Bool - Dictates whether the included spec specifies paths relative to itself (the default) or the root spec file.
include:
  - includedFile.yml
  - path: path/to/includedFile.yml
    relativePaths: false

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

  • minimumXcodeGenVersion: String - The minimum version of XcodeGen required.
  • carthageBuildPath: String - The path to the carthage build directory. Defaults to Carthage/Build. This is used when specifying target carthage dependencies
  • carthageExecutablePath: String - The path to the carthage executable. Defaults to carthage. You can specify when you use custom built or locally installed Carthage using Mint, for example.
  • 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 as Vendor/Foo/Hello.swift, the group Vendor will created as a parent of the Foo group. This can be overriden in a specific Target source
  • 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 combining bundleIdPrefix 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 replaced 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 settings
    • project: only project settings
    • targets: only target settings
    • none: 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 or 9.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
    • missingConfigFiles: Disable checking for the existence of configuration files. This can be useful for generating a project in a context where config files are not available.
  • defaultConfig: String - The default configuration for command line builds from Xcode. If the configuration provided here doesn't match one in your configs key, XcodeGen will fail. If you don't set this, the first configuration alphabetically will be chosen.
  • groupSortPosition: String - Where groups are sorted in relation to other files. Either:
    • none - sorted alphabetically with all the other files
    • top - at the top, before files
    • bottom (default) - at the bottom, after other files
  • transitivelyLinkDependencies: Bool - If this is true then targets will link to the dependencies of their target dependencies. If a target should embed its dependencies, such as application and test bundles, it will embed these transitive dependencies as well. Some complex setups might want to set this to false and explicitly specify dependencies at every level. Targets can override this with Target.transitivelyLinkDependencies. Defaults to false.
  • generateEmptyDirectories: Bool - If this is true then empty directories will be added to project too else will be missed. Defaults to false.
  • findCarthageFrameworks: Bool - When this is set to true, all the invididual frameworks for Carthage dependencies will automatically be found. This property can be overriden individually for each carthage dependency - for more details see See findFrameworks in the Dependency section. Defaults to false.
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
  Beta: release
  AppStore: 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 and Staging Release, you could apply settings to both of them using staging. However if a config name is an exact match to a config it won't be applied to any others. eg Release will be applied to config Release but not Staging Release
  • 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 - The deployment target (eg 9.2). 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 for Info.plist files and the first one found will be used for this setting
    • FRAMEWORK_SEARCH_PATHS: If carthage dependencies are used, the platform build path will be added to this setting
    • OTHER_LDFLAGS: See requiresObjCLinking below
    • TEST_TARGET_NAME: for ui tests that target an application
    • TEST_HOST: for unit tests that target an application
  • dependencies: [Dependency] - Dependencies for the target
  • info: Plist - If defined, this will generate and write an Info.plist to the specified path and use it by setting the INFOPLIST_FILE build setting for every configuration, unless INFOPLIST_FILE is already defined in settings for this configuration. The following properties are generated automatically, the rest will have to be provided.
    • CFBundleIdentifier
    • CFBundleInfoDictionaryVersion
    • CFBundleExecutable
    • CFBundleName
    • CFBundleDevelopmentRegion
    • CFBundleShortVersionString
    • CFBundleVersion
    • CFBundlePackageType
  • entitlements: Plist - If defined this will generate and write a .entitlements file, and use it by setting CODE_SIGN_ENTITLEMENTS build setting for every configuration. All properties must be provided
  • templates: [String] - A list of Target Templates referenced by name that will be merged with the target in order. Any instances of ${target_name} within these templates will be replaced with the target name.
  • templateAttributes: [String: String] - A list of attributes where each instance of ${attributeName} within the templates listed in templates will be replaced with the value specified.
  • transitivelyLinkDependencies: Bool - If this is not specified the value from the project set in Options.transitivelyLinkDependencies will be used.
  • directlyEmbedCarthageDependencies: Bool - If this is true Carthage dependencies will be embedded using an Embed Frameworks build phase instead of the copy-frameworks script. Defaults to true for all targets except iOS/tvOS/watchOS Applications.
  • requiresObjCLinking: Bool - If this is true any targets that link to this target will have -ObjC added to their OTHER_LDFLAGS. This is required if a static library has any catagories or extensions on Objective-C code. See this guide for more details. Defaults to true if type is library.static. If you are 100% sure you don't have catagories or extensions on Objective-C code (pure Swift with no use of Foundation/UIKit) you can set this to false, otherwise it's best to leave it alone.
  • preBuildScripts: [Build Script] - Build scripts that run before any other build phases
  • postCompileScripts: [Build Script] - Build scripts that run after the Compile Sources phase
  • postBuildScripts: [Build Script] - Build scripts that run after any other build phases
  • buildRules: [Build Rule] - Custom build rules
  • 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.
  • attributes: [String: Any] - This sets values in the project TargetAttributes. It is merged with attributes from the project and anything automatically added by XcodeGen, with any duplicate values being override by values specified here. This is for advanced use only. Properties that are already set include:
    • DevelopmentTeam: if all configurations have the same DEVELOPMENT_TEAM setting
    • ProvisioningStyle: if all configurations have the same CODE_SIGN_STYLE setting
    • TestTargetID: if all configurations have the same TEST_TARGET_NAME setting

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
  • app-extension.messages
  • app-extension.messages-sticker-pack
  • app-extension.intents-service
  • bundle
  • bundle.unit-test
  • bundle.ui-testing
  • bundle.ocunit-test
  • framework
  • instruments-package
  • library.dynamic
  • library.static
  • tool
  • tv-app-extension
  • watchkit-extension
  • watchkit2-extension
  • xcode-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 deploymenTarget is specified for a multi platform target, it can have different values per platform similar to how it's defined in Options. See below for an example. 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]
    deploymentTarget:
      iOS: 9.0
      tvOS: 10.0
    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

  • 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] - A list of global patterns representing the files to exclude. These rules are relative to path and not the directory where project.yml resides.
  • createIntermediateGroups: Bool - This overrides the value in Options
  • 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 phase
    • resources - Copy Bundle Resources phase
    • headers - Headers Phase
    • copyFiles - Copy Files Phase. Must be specified as an object with the following fields:
      • destination: String - Destination of the Copy Files phase. This can be one of the following values:
        • absolutePath
        • productsDirectory
        • wrapper
        • executables
        • resources
        • javaResources
        • frameworks
        • sharedFrameworks
        • sharedSupport
        • plugins
      • subpath: String - The path inside of the destination to copy the files.
    • none - 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.
  • headerVisibility: String - The visibility of any headers. This defaults to public, but can be either:
    • public
    • private
    • project
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: ModuleMaps
        buildPhase:
          copyFiles:
            destination: productsDirectory
            subpath: include/$(PRODUCT_NAME)
      - path: Resources
        type: folder

Dependency

A dependency can be one of a 3 types:

  • target: name - links to another target
  • framework: path - links to a framework
  • carthage: name - helper for linking to a Carthage framework
  • sdk: name - links to a dependency with the SDK. This can either be a relative path within the sdk root or a single filename that references a framework (.framework) or lib (.tbd)

Linking options:

  • 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 depending on the type of the dependency and the type of the target (e.g. static libraries will only link to executables by default).
  • 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
  • weak: Bool - Whether the Weak setting is applied when linking the framework. Defaults to false

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 or Carthage/Build by default
  • PLATFORM = the target's platform
  • FRAMEWORK = the specified name.

All the invididual frameworks of a Carthage dependency can be automatically found via findFrameworks: true. This overrides the value of Options.findCarthageFrameworks. Otherwise each one will have to be listed invididually. Xcodegen uses .version files generated by Carthage in order for this framework lookup to work, so the Carthage dependencies will need to have already been built at the time XcodeGen is run.

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
        findFrameworks: true
      - sdk: Contacts.framework
      - sdk: libc++.tbd
  MyFramework:
    type: framework

SDK Dependency

  • root: String - Root of framework path, for example DEVELOPER_DIR. Default value is BUILT_PRODUCTS_DIR
targets:
  MyTestTarget:
    dependencies:
      - target: MyFramework
      - framework: path/to/framework.framework
      - sdk: Contacts.framework
      - sdk: Platforms/iPhoneOS.platform/Developer/Library/Frameworks/XCTest
        root: DEVELOPER_DIR
  MyFramework:
    type: framework

Config Files

Specifies .xcconfig files for each configuration.

configFiles:
  Debug: debug.xcconfig
  Release: release.xcconfig
targets:
  App:
    configFiles:
      Debug: App/debug.xcconfig
      Release: App/release.xcconfig

Plist

Plists are created on disk on every generation of the project. They can be used as a way to define Info.plist or .entitlement files. Some Info.plist properties are generated automatically.

  • path: String - This is the path where the plist will be written to
  • properties: [String: Any] - This is a map of all the plist keys and values
targets:
  App:
    info:
      path: App/Info.plist
      properties:
        UISupportedInterfaceOrientations: [UIInterfaceOrientationPortrait]
        UILaunchStoryboardName: LaunchScreen
    entitlements:
      path: App/App.entitlements
      properties:
        com.apple.security.application-groups: group.com.app

Build Script

Run script build phases can be added at 3 different points in the build:

  • preBuildScripts: Before any other build phases
  • postCompileScripts: After the compile sources build phase
  • postBuildScripts: After any other build phases

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
  • inputFileLists: [String] - list of input .xcfilelist
  • outputFileLists: [String] - list of output .xcfilelist
  • shell: String - shell used for the script. Defaults to /bin/sh
  • showEnvVars: Bool - whether the environment variables accessible to the script show be printed to the build log. Defaults to yes
  • 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
        inputFileLists:
          - $(SRCROOT)/inputFiles.xcfilelist
        outputFiles:
          - $(DERIVED_FILE_DIR)/file1
          - $(DERIVED_FILE_DIR)/file2
        outputFileLists:
          - $(SRCROOT)/outputFiles.xcfilelist
    postCompileScripts:
      - script: swiftlint
        name: Swiftlint
      - script: |
      		command do
      		othercommand
    postBuildScripts:
      - path: myscripts/my_final_script.sh
        name: My Final Script

Build Rule

  • filePattern: String - A glob pattern for the files that will have the build rule run on them. This or fileType must be defined
  • fileType: String - A file type determined by Xcode. The available types can be seen by hovering your mouse of the Process dropdown in the Xcode interface. For example sourcecode.swift or file.xib. This or filePattern must be defined.
  • script: String - The script that will be run on each file. This or compilerSpec must be defined.
  • compilerSpec: String: A reference to a built in apple tool to run on each file. This is for advanced use and the the values for this must be checked. This or script must be defined.
  • name: String - The name of a build rule. Defaults to Build Rule
  • outputFiles: [String] - The list of output files
  • outputFilesCompilerFlags: [String] - The list of compiler flags to apply to the output files
targets:
  MyTarget:
    buildRules:
      - filePattern: "*.xcassets"
        script: generate_assets.py
      - fileType: sourcecode.swift
        script: pre_process_swift.py
      - filePattern: "*.txt"
        name: My Build Rule
        compilerSpec: com.apple.xcode.tools.swift.compiler
        outputFiles:
          - $(SRCROOT)/Generated.swift

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: [Test Target] - a list of test targets that should be included in the scheme. These will be added to the build targets and the test entries. Each entry can either be a simple string, or a Test Target
  • 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
  • environmentVariables: [Environment Variable] or [String:String] - environment variables for Run, Test and Profile scheme actions. When passing a dictionary, every key-value entry maps to a corresponding variable that is enabled.
  • preActions: [Execution Action] - Scripts that are run before all actions
  • postActions: [Execution Action] - Scripts that are run after all 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
      environmentVariables:
        MY_ENV_VAR: VALUE
  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.

Aggregate Target

This is used to override settings or run build scripts in specific targets

  • targets: [String] - The list of target names to include as target dependencies
  • configFiles: Config Files - .xcconfig files per config
  • settings: Settings - Target specific build settings.
  • buildScripts: [Build Script] - Build scripts to run
  • scheme: Target Scheme - Generated scheme
  • attributes: [String: Any] - This sets values in the project TargetAttributes. It is merged with attributes from the project and anything automatically added by XcodeGen, with any duplicate values being override by values specified here

Target Template

This is a template that can be referenced from a normal target using the templates property. The properties of this template are the same as a Target]. Any instances of ${target_name} within each template will be replaced by the final target name which references the template. Any attributes defined within a targets templateAttributes will be used to replace any attribute references in the template using the syntax ${attribute_name}.

targets:
  MyFramework:
    templates: 
      - Framework
    templateAttributes:
      frameworkName: AwesomeFramework
    sources:
      - SomeSources
targetTemplates:
  Framework:
    platform: iOS
    type: framework
    sources:
      - ${frameworkName}/${target_name}

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:String] or [String:[String]] - A map of target names to build and which build types they should be enabled for. The build types can be all, none, or an array of the following types:

    • run or running
    • test or testing
    • profile or profiling
    • analyze or analyzing
    • archive or archiving

  • parallelizeBuild: Bool - Whether or not your targets should be built in parallel. By default this is true if not set.

    • true: Build targets in parallel
    • false: Build targets serially

  • buildImplicitDependencies: Bool - Flag to determine if Xcode should build implicit dependencies of this scheme. By default this is true if not set.

    • true: Discover implicit dependencies of this scheme
    • false: Only build explicit dependencies of this scheme
targets:
  myTarget: all
  myTarget2: [test, run]
parallelizeBuild: true
buildImplicitDependencies: true

Common Build Action options

The different actions share some properties:

  • config: String - All build actions can be set to use a certain config. If a config, or the build action itself, is not defined the first configuration found of a certain type will be used, depending on the type:
    • debug: run, test, analyze
    • release: profile, archive
  • commandLineArguments: [String:Bool] - run, test and profile actions have a map of command line arguments to whether they are enabled
  • preActions: [Execution Action] - Scripts that are run before the action
  • postActions: [Execution Action] - Scripts that are run after the action
  • environmentVariables: [Environment Variable] or [String:String] - run, test and profile actions can define the environment variables. When passing a dictionary, every key-value entry maps to a corresponding variable that is enabled.

Execution Action

Scheme run scripts added via preActions or postActions. They run before or after a build action, respectively, and in the order defined. Each execution action can contain:

  • script: String - an inline shell script
  • name: String - name of a script. Defaults to Run Script
  • settingsTarget: String - name of a build or test target whose settings will be available as environment variables.

A multiline script can be written using the various YAML multiline methods, for example with |. See Build Script.

Test Action

  • gatherCoverageData: Bool - a boolean that indicates if this scheme should gather coverage data. This defaults to false
  • targets: [Test Target] - a list of targets to test. Each entry can either be a simple string, or a Test Target

Test Target

  • name: String - The name of the target
  • parallelizable: Bool - Whether to run tests in parallel. Defaults to false
  • randomExecutionOrder: Bool - Whether to run tests in a random order. Defaults to false
  • skippedTests: [String] - List of tests in the test target to skip. Defaults to empty.

Archive Action

  • customArchiveName: String - the custom name to give to the archive
  • revealArchiveInOrganizer: Bool - flag to determine whether the archive will be revealed in Xcode's Organizer after it's done building

Environment Variable

  • variable: String - variable's name.
  • value: String - variable's value.
  • isEnabled: Bool - indicates whether the environment variable is enabled. This defaults to true.
schemes:
  Production:
    build:
      targets:
        MyTarget1: all
        MyTarget2: [run, archive]
    run:
      config: prod-debug
      commandLineArguments: "--option value"
      environmentVariables:
        RUN_ENV_VAR: VALUE
    test:
      config: prod-debug
      commandLineArguments: "--option testValue"
      gatherCoverageData: true
      targets: 
        - Tester1 
        - name: Tester2
          parallelizable: true
          randomExecutionOrder: true
          skippedTests: [Test/testExample()]
      environmentVariables:
        - variable: TEST_ENV_VAR
          value: VALUE
          isEnabled: false
    profile:
      config: prod-release
    analyze:
      config: prod-debug
    archive:
      config: prod-release
      customArchiveName: MyTarget
      revealArchiveInOrganizer: false