XcodeGen

https://github.com/yonaskolb/xcodegen
Admin
XcodeGen is a command-line tool that generates Xcode projects from a YAML or JSON spec file,...
Tokens:113,420
Snippets:789
Trust Score:9.4
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### YAML options example with deploymentTarget and postGenCommand

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Example of the `options` dictionary in a project spec. It sets a project-wide `deploymentTarget` for watchOS and tvOS, and runs `pod install` after generation via `postGenCommand`.

```yaml
options:
  deploymentTarget:
    watchOS: "2.0"
    tvOS: "10.0"
  postGenCommand: pod install
```

--------------------------------

### Usage example: load and resolve a spec file

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/specfile.md

Shows how to load a spec file and get its resolved dictionary, including a multi-file example.

```swift
import ProjectSpec
import PathKit

let spec = try SpecFile(path: Path("project.yml"))
let resolved = spec.resolvedDictionary()
print(resolved["name"] ?? "")

// multi-file specs
let merged = try SpecFile(path: Path("App/project.yml"))
    .resolvedDictionary()
```

--------------------------------

### Settings usage example

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/settings.md

Shows how to create a `Settings` instance with build settings, config overrides, and groups, plus dictionary literal shorthand.

```swift
import ProjectSpec
import XcodeProj // BuildSetting

let settings = Settings(
    buildSettings: [
        "SWIFT_VERSION": .string("5.0"),
        "OTHER_LDFLAGS": .array(["-ObjC"]),
    ],
    configSettings: [
        "Debug": Settings(buildSettings: ["DEBUG_INFORMATION_FORMAT": .string("dwarf")]),
    ],
    groups: ["Signing"]
)

// dictionary literal form
let shorthand: Settings = [
    "PRODUCT_NAME": .string("MyApp"),
]
```

--------------------------------

### Scheme generation usage example

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/schemegenerator.md

Shows how to load a project, generate the PBXProj, create a SchemeGenerator, and generate schemes. Prints counts of shared and user schemes.

```swift
import ProjectSpec
import XcodeGenKit
import XcodeProj
import PathKit

let project = try Project(path: Path("project.yml"))
let pbxProj = try PBXProjGenerator(project: project).generate()
let schemeGenerator = SchemeGenerator(project: project, pbxProj: pbxProj)

let (sharedSchemes, userSchemes, management) = try schemeGenerator.generateSchemes()
print("\(sharedSchemes.count) shared, \(userSchemes.count) user schemes")
```

--------------------------------

### Target usage example with Plist and build scripts

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/buildscripts.md

Shows how to create a Target with pre-build and post-compile scripts, build rules, build tool plugins, and Plist configurations for Info.plist and entitlements.

```swift
import ProjectSpec

let target = Target(
    name: "MyApp",
    type: .application,
    platform: .iOS,
    preBuildScripts: [
        BuildScript(
            script: .script("swiftlint"),
            name: "Lint",
            inputFiles: ["$(SRCROOT)/.swiftlint.yml"],
            outputFiles: []
        ),
        BuildScript(script: .path("Scripts/generate.sh"), shell: "/bin/sh"),
    ],
    postCompileScripts: [
        BuildScript(script: .script("echo done"), basedOnDependencyAnalysis: false)
    ],
    buildRules: [
        BuildRule(
            fileType: .pattern("*.liquid"),
            action: .script("echo compile $INPUT_FILE_PATH"),
            outputFiles: ["$(DERIVED_FILE_DIR)/$(INPUT_FILE_BASE).swift"]
        )
    ],
    buildToolPlugins: [
        BuildToolPlugin(plugin: "SwiftLintPlugin", package: "SwiftLint")
    ],
    info: Plist(path: "MyApp/Info.plist", attributes: [
        "CFBundleDisplayName": "MyApp",
        "UILaunchScreen": [:],
    ]),
    entitlements: Plist(path: "MyApp/MyApp.entitlements", attributes: [
        "com.apple.security.application-groups": ["group.com.example"]
    ])
)
```

--------------------------------

### Usage Example

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/aggregatetarget.md

Shows how to create an AggregateTarget, add it to a project, and access targets through the ProjectTarget protocol.

```APIDOC
## Usage Example

### Description
Shows how to create an AggregateTarget, add it to a project, and access targets through the ProjectTarget protocol.

### Code
```swift
import ProjectSpec

var project = try Project(path: Path("project.yml"))
project.aggregateTargets = [
    AggregateTarget(
        name: "Lint",
        targets: ["MyApp"],
        buildScripts: [
            BuildScript(script: .script("swiftlint lint --strict")),
        ]
    )
]

if let aggregate = project.getAggregateTarget("Lint") {
    print(aggregate.name, aggregate.targets) // Lint ["MyApp"]
}
// Both kinds are reachable through the common protocol:
for target in project.projectTargets {
    print(target.name, target.type.name)
}
```

### Validation
```swift
do {
    try project.validate()  // throws .invalidTargetDependency when a member name is unknown
} catch let error as SpecValidationError {
    print(error.description)
}
```
```

--------------------------------

### Configure Target Build Rules

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Example showing how to define custom build rules for a target using file patterns, file types, and compiler specifications.

```yaml
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
        runOncePerArchitecture: false
```

--------------------------------

### Usage example for ProjectFormat and PBXProductType

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/projectformat.md

Shows how to set SpecOptions.xcodeVersion and projectFormat, load a Project from a YAML file, and access the computed xcodeVersion and projectFormat properties. Also demonstrates creating a PBXProductType from a string and checking its name and isApp property.

```swift
import ProjectSpec
import XcodeGenKit
import Version

var options = SpecOptions()
options.xcodeVersion = "15.3"
options.projectFormat = ProjectFormat.xcode15_3.rawValue

let project = try Project(path: Path("project.yml")) // options loaded from spec
print(project.xcodeVersion)      // "1530"
print(project.projectFormat.rawValue) // "xcode15_3"
print(ProjectFormat.default.objectVersion) // 77

let type = PBXProductType(string: "application")!
print(type.name, type.isApp) // application true
```

--------------------------------

### Configure Target Build Scripts

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Example showing how to define preBuildScripts, postCompileScripts, and postBuildScripts for a target, including multiline script support using the pipe operator.

```yaml
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
        discoveredDependencyFile: $(DERIVED_FILE_DIR)/target.d
    postCompileScripts:
      - script: swiftlint
        name: Swiftlint
      - script: |
      		command do
      		othercommand
    postBuildScripts:
      - path: myscripts/my_final_script.sh
        name: My Final Script
```

--------------------------------

### Define Project Dependencies

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Example showing various dependency types including local project references, framework paths, Carthage integration, and SDKs.

```yaml
projectReferences:
  FooLib:
    path: path/to/FooLib.xcodeproj
targets:
  MyTarget:
    supportedDestinations: [iOS, tvOS]
    dependencies:
      - target: MyFramework
        destinationFilters: [iOS]
      - target: FooLib/FooTarget
      - framework: path/to/framework.framework
        destinationFilters: [tvOS]
      - carthage: Result
        findFrameworks: false
        linkType: static
        destinationFilters: [iOS]
      - sdk: Contacts.framework
      - sdk: libc++.tbd
      - sdk: libz.dylib
  MyFramework:
    type: framework
```

--------------------------------

### Define a Scheme with ProjectSpec

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/scheme.md

Example of initializing a Scheme object with build, run, test, archive, and management configurations.

```swift
import ProjectSpec

let scheme = Scheme(
    name: "MyApp-Dev",
    build: Scheme.Build(
        targets: [Scheme.BuildTarget(target: TestableTargetReference.local("MyApp"))],
        parallelizeBuild: true,
        buildImplicitDependencies: true
    ),
    run: Scheme.Run(
        config: "Debug",
        commandLineArguments: ["-UITesting": true],
        environmentVariables: [
            .init(variable: "API_BASE", value: "https://staging.example.com", isEnabled: true)
        ],
        storeKitConfiguration: "Config.storekit",
        simulateLocation: Scheme.SimulateLocation(allow: true, defaultLocation: "London, England")
    ),
    test: Scheme.Test(
        config: "Debug",
        gatherCoverageData: true,
        testPlans: [TestPlan(path: "MyApp.xctestplan", defaultPlan: true)]
    ),
    archive: Scheme.Archive(config: "Release", revealArchiveInOrganizer: true),
    management: Scheme.Management(shared: true, orderHint: 10, isShown: true)
)
```

--------------------------------

### Usage example for AggregateTarget

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/aggregatetarget.md

Shows how to create an aggregate target, add it to a project, retrieve it, and iterate over all project targets.

```swift
import ProjectSpec

var project = try Project(path: Path("project.yml"))
project.aggregateTargets = [
    AggregateTarget(
        name: "Lint",
        targets: ["MyApp"],
        buildScripts: [
            BuildScript(script: .script("swiftlint lint --strict")),
        ]
    )
]

if let aggregate = project.getAggregateTarget("Lint") {
    print(aggregate.name, aggregate.targets) // Lint ["MyApp"]
}
// Both kinds are reachable through the common protocol:
for target in project.projectTargets {
    print(target.name, target.type.name)
}
```

--------------------------------

### Usage example: variable expansion through includes

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/specfile.md

Shows how to pass variables for ${VAR} expansion when loading a spec file.

```swift
let spec = try SpecFile(
    path: Path("project.yml"),
    variables: ["CONFIG": "Production"]
)
// any "name: ${CONFIG}" in the spec resolves to "Production"
```

--------------------------------

### Programmatic target construction

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/target.md

Shows how to create a Target instance programmatically using ProjectSpec, XcodeProj, and Version. The example sets a deployment target, build settings, sources, dependencies, and an Info.plist, then prints the target's filename.

```swift
import ProjectSpec
import XcodeProj
import Version

let target = Target(
    name: "MyApp",
    type: .application,
    platform: .iOS,
    deploymentTarget: try Version.parse("14.0"),
    settings: Settings(buildSettings: ["PRODUCT_BUNDLE_IDENTIFIER": .string("com.example.app")]),
    sources: [TargetSource(path: "MyApp")],
    dependencies: [Dependency(type: .framework, reference: "Vendor/MyFramework.framework")],
    info: Plist(path: "MyApp/Info.plist", attributes: ["NSAppTransportSecurity": ["NSAllowsArbitraryLoads": true]])
)
print(target.filename) // MyApp.app
```

--------------------------------

### FileWriter usage example

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/filewriter.md

Shows how to create a FileWriter, write plists first, then generate and write the Xcode project.

```swift
import ProjectSpec
import XcodeGenKit
import XcodeProj
import PathKit

let project = try Project(path: Path("project.yml"))
let fileWriter = FileWriter(project: project)

// 1) materialize any declared Info/entitlements plists first
try fileWriter.writePlists()

// 2) generate + write the project
let xcodeProject = try ProjectGenerator(project: project)
    .generateXcodeProject(userName: "jsmith")
try fileWriter.writeXcodeProject(xcodeProject, to: project.defaultProjectPath)
```

--------------------------------

### Programmatic SpecOptions configuration in Swift

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/specoptions.md

Programmatic usage example showing how to create and configure a SpecOptions instance in Swift. Requires importing ProjectSpec and Version. Sets bundleIdPrefix, settingPresets, disabledValidations, deploymentTarget, and pre/post generation commands.

```swift
import ProjectSpec
import Version

var options = SpecOptions()
options.bundleIdPrefix = "com.example"
options.settingPresets = .project
options.disabledValidations = [.missingConfigs]
options.deploymentTarget = DeploymentTarget(iOS: try Version.parse("15.0"))
options.preGenCommand = "swift package resolve"
options.postGenCommand = "pod install"
```

--------------------------------

### Include object example with relativePaths and enable

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Shows how to include other spec files, either as a simple path string or as an object with relativePaths and enable options. The enable option can be set via an environment variable.

```yaml
include:
  - includedFile.yml
  - path: path/to/includedFile.yml
    relativePaths: false
    enable: ${INCLUDE_ADDITIONAL_YAML}

```

--------------------------------

### Install XcodeGen with Mint

Source: https://github.com/yonaskolb/xcodegen/blob/master/README.md

Use Mint to install XcodeGen. Requires Mint to be installed and Xcode to be set up.

```sh
mint install yonaskolb/xcodegen
```

--------------------------------

### Install XcodeGen from source with Make

Source: https://github.com/yonaskolb/xcodegen/blob/master/README.md

Clone the XcodeGen repository and run `make install` to build and install from source.

```shell
git clone https://github.com/yonaskolb/XcodeGen.git
cd XcodeGen
make install
```

--------------------------------

### Install XcodeGen with Homebrew

Source: https://github.com/yonaskolb/xcodegen/blob/master/README.md

Install XcodeGen using the Homebrew package manager.

```shell
brew install xcodegen
```

--------------------------------

### Create and inspect a Project from a spec file or dictionary

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/project.md

Shows how to create a Project instance from a YAML/JSON spec file or a raw dictionary, then access targets, configs, and the default project path.

```swift
import ProjectSpec
import PathKit

// From a YAML/JSON spec file
let project = try Project(path: Path("project.yml"))

// From a raw dictionary
let project2 = try Project(
    basePath: "MyProject",
    jsonDictionary: [
        "name": "MyApp",
        "targets": [
            "MyApp": ["type": "application", "platform": "iOS"],
        ],
    ]
)

if let target = project.getTarget("MyApp") {
    print(target.name, project.getConfig("Debug")!.name)
}
print(project.defaultProjectPath) // MyApp.xcodeproj
```

--------------------------------

### Error handling for breakpoint generation

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/breakpoints.md

Error handling example for breakpoint generation. Catches SpecParsingError and prints the error description, with an example of an unknown breakpoint type.

```swift
do {
    let xcodeProject = try ProjectGenerator(project: project).generateXcodeProject(userName: "jsmith")
} catch let error as SpecParsingError {
    // e.g. .unknownBreakpointType("weirdBreakpoint")
    print("Breakpoint spec error: \(error.description)")
}
```

--------------------------------

### Carthage dependency spec example

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/carthagedependencyresolver.md

Example YAML snippet showing how to declare Carthage dependencies in the project spec, including options like findFrameworks, linkType, platforms, and embed.

```yaml
targets:
  MyApp:
    type: application
    platform: iOS
    dependencies:
      - carthage: Alamofire
      - carthage: RxSwift
        findFrameworks: true      # resolve related frameworks from .version
        linkType: static          # or dynamic
        platforms: [iOS]          # restrict to iOS
        embed: false
```

--------------------------------

### init(project:projectDirectory:)

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/pbxprojgenerator.md

Initializes a new PBXProjGenerator with the project to generate and an optional base directory for the .xcodeproj. Creates internal resolvers and seeds the PBXProj object.

```APIDOC
## init(project:projectDirectory:)

### Description
Initializes a new PBXProjGenerator with the project to generate and an optional base directory for the .xcodeproj. Creates internal resolvers and seeds the PBXProj object.

### Method
init

### Parameters
#### Parameters
- **project** (Project) - Required - The project to generate.
- **projectDirectory** (Path?) - Optional - Base directory used when the .xcodeproj is generated in a location other than the spec directory; forwarded to the internal SourceGenerator.

### Request Example
```swift
let generator = PBXProjGenerator(project: project, projectDirectory: somePath)
```
```

--------------------------------

### public init(path: Path) throws

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/project.md

Loads SpecFile(path:) then delegates to init(spec:). Throws Yams/JSON parse errors and SpecParsingError cases.

```swift
public init(path: Path) throws
```

--------------------------------

### Resolving a config

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/settings.md

Mirrors `SettingsBuilder` semantics to get build settings for a specific config.

```swift
import XcodeGenKit
import PathKit

let project = try Project(path: Path("project.yml"))
let debug = project.configs.first { $0.type == .debug }!
let buildSettings = project.getBuildSettings(settings: settings, config: debug)
print(buildSettings["SWIFT_VERSION"] ?? .string("(unset)"))
```

--------------------------------

### Initialize and use TargetReference and GroupOrdering

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/references.md

Demonstrates creating local and project-based target references, accessing package testable targets, and defining group ordering patterns.

```swift
import ProjectSpec

let ref = try TargetReference("MyFramework")            // local
let projRef = try TargetReference("Vendor/MyLib")       // project
print(projRef.location, projRef.reference)              // project("Vendor") "Vendor/MyLib"

let testable = TestableTargetReference.package("Yams/Yams")
print(testable.targetReference.name)                    // fatalError — package testables have no TargetReference

let ordering = GroupOrdering(
    pattern: "Products",
    order: ["Frameworks", "Sources"]   // hoist these groups first
)
```

--------------------------------

### Breakpoint Action YAML example

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Defines a breakpoint action of type 'Sound' with the sound 'Blow'.

```yaml
actions:
  - type: Sound
    sound: Blow
```

--------------------------------

### SpecFile public methods

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/specfile.md

Public methods to get the resolved dictionary and target declaration order.

```swift
public func resolvedDictionary() -> JSONDictionary
public func resolvedTargetDeclarationOrder() -> [String]
```

--------------------------------

### Settings

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/settings.md

Complete reference for the Settings struct, including initializers, merge operators, helpers, and usage examples.

```APIDOC
## Settings

### Description
Represents build settings at a single level: a `base` map, per-config overrides (`configs`), and references to reusable setting groups. Used by both `Project` and `Target`/`AggregateTarget`.

### Module
`ProjectSpec` — Source: `Sources/ProjectSpec/Settings.swift`

### Declaration
```swift
public struct Settings: Equatable, JSONObjectConvertible, CustomStringConvertible {

    public var buildSettings: BuildSettings
    public var configSettings: [String: Settings]
    public var groups: [String]

    public init(buildSettings: BuildSettings = [:], configSettings: [String: Settings] = [:], groups: [String] = [])

    public static let empty: Settings = Settings(buildSettings: [:])
}
```

### Members
| Member | Type | Default | Description |
|--------|------|---------|-------------|
| `buildSettings` | `BuildSettings` (= `[String: BuildSetting]`, XcodeProj) | `[:]` | The `base` settings. `BuildSetting` is `.string(String)` / `.array([String])`. |
| `configSettings` | `[String: Settings]` | `[:]` | Per-config settings; keys matched case-insensitively against config names. |
| `groups` | `[String]` | `[]` | Names of `settingGroups` to merge (resolved recursively). |
| `empty` | `Settings` (static) | — | Empty settings value. |

### Initializers

#### `init(jsonDictionary:)`
```swift
public init(jsonDictionary: JSONDictionary) throws
```

Two shapes:

1. **Flat** — no `configs`/`groups`/`base` keys: every key is a build setting (`buildSettings = jsonDictionary.mapValues { BuildSetting(any: $0) }`), `configSettings = [:]`, `groups = []`.
2. **Structured** — `base:` mapping, `groups`/`presets:` aliases, and `configs:` mapping. `configs` values that are not dictionaries throw `SpecParsingError.invalidConfigsMappingFormat(keys: Set<String>)`.

Conflicts against the flat shape: `base`/`groups`/`presets` reserved keys inside a flat settings dict are a common spec error; use the structured shape.

#### `init(dictionaryLiteral:)`
```swift
public init(dictionaryLiteral elements: (String, BuildSetting)...)
```

Conforms to `ExpressibleByDictionaryLiteral` — `["SWIFT_VERSION": .string("5.0")]` works.

### Merge operators

#### `+=` operator
```swift
public func += (lhs: inout BuildSettings, rhs: BuildSettings?)
```

Public global operator: merges `rhs` into `lhs` (no-op when `rhs` is `nil`).

#### Dictionary merge extensions
```swift
extension Dictionary where Key == String {
    public func merged(_ dictionary: [Key: Value]) -> [Key: Value]
    public mutating func merge(_ dictionary: [Key: Value])
}
```

Plain (non-recursive) dictionary merge used across the codebase.

### `BuildSetting` helpers

#### `init(any:)` and `toAny()`
```swift
extension BuildSetting {
    public init(any value: Any)
    public func toAny() -> Any
}
```

- `init(any:)` — `[String]` → `.array`, `Bool` → `.string("true"/"false")` via boolean literal, everything else → `.string("\(value)")`.
- `toAny()` — unwraps back to `String`/`[String]`.

#### `ProjectAttribute.init(any:)`
```swift
extension ProjectAttribute {
    public init(any value: Any)
}
```

XcodeProj's `ProjectAttribute`: added `.attributeDictionary` support for nested dictionaries (e.g. `SystemCapabilities`) so nested attributes serialize deterministically instead of as a stringified Swift dictionary description.

### `Settings.description`

Renders `base:`/`configs:`/`groups:` blocks, indenting nested settings; used by `xcodegen dump --type summary` and target descriptions.

### Conformances

`Equatable` (structural), `JSONObjectConvertible`, `ExpressibleByDictionaryLiteral`, `JSONEncodable`:

```swift
extension Settings: JSONEncodable {
    public func toJSONValue() -> Any
}
```

Round-trip writes `base`/`groups`/`configs` structure when either `groups` or `configSettings` is non-empty, else the flat map.

### Usage

```swift
import ProjectSpec
import XcodeProj // BuildSetting

let settings = Settings(
    buildSettings: [
        "SWIFT_VERSION": .string("5.0"),
        "OTHER_LDFLAGS": .array(["-ObjC"]),
    ],
    configSettings: [
        "Debug": Settings(buildSettings: ["DEBUG_INFORMATION_FORMAT": .string("dwarf")]),
    ],
    groups: ["Signing"]
)

// dictionary literal form
let shorthand: Settings = [
    "PRODUCT_NAME": .string("MyApp"),
]
```

Resolving a config (mirrors `SettingsBuilder` semantics used at generation time):

```swift
import XcodeGenKit
import PathKit

let project = try Project(path: Path("project.yml"))
let debug = project.configs.first { $0.type == .debug }!
let buildSettings = project.getBuildSettings(settings: settings, config: debug)
print(buildSettings["SWIFT_VERSION"] ?? .string("(unset)"))
```

Error handling — structured decode:

```swift
do {
    let settings = try Settings(jsonDictionary: [
        "base": ["SWIFT_VERSION": "5.0"],
        "configs": ["Debug": "this is not a mapping"],  // wrong shape
    ])
} catch let error as SpecParsingError {
    // .invalidConfigsMappingFormat(keys: ["Debug"])
    print(error.description)
}
```

Related pages: [SettingsBuilder](settingsbuilder.md), [Project](project.md), [Target](target.md), [configuration.md](../configuration.md).
```

--------------------------------

### init(project:pbxProj:)

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/schemegenerator.md

Initializes a SchemeGenerator with a parsed project and the generated PBXProj used to resolve buildable references.

```APIDOC
## init(project:pbxProj:)

### Description
Initializes a SchemeGenerator with a parsed project and the generated PBXProj used to resolve buildable references.

### Method
Initializer

### Parameters
- **project** (Project) - Required - Parsed spec.
- **pbxProj** (PBXProj) - Required - The generated PBXProj (from PBXProjGenerator.generate()) used to resolve buildable references.

### Response
No return value.
```

--------------------------------

### BuildPhaseSpec.CopyFilesSettings.init(destination:subpath:phaseOrder:)

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/targetsource.md

Initializes a CopyFilesSettings instance with a destination, subpath, and phase order. All parameters are required for the initializer, but JSON initialization provides defaults for subpath and phaseOrder.

```APIDOC
## BuildPhaseSpec.CopyFilesSettings.init(destination:subpath:phaseOrder:)

### Description
Initializes a CopyFilesSettings instance with a destination, subpath, and phase order. All parameters are required for the initializer, but JSON initialization provides defaults for subpath and phaseOrder.

### Parameters
- **destination** (Destination) - Required - The destination for the copy files phase.
- **subpath** (String) - Required - The subpath within the destination.
- **phaseOrder** (PhaseOrder) - Required - The order of the phase relative to compile sources.

### Example
```swift
let settings = CopyFilesSettings(destination: .productsDirectory, subpath: "$(CONTENTS_FOLDER_PATH)/XPCServices", phaseOrder: .postCompile)
```
```

--------------------------------

### Breakpoints YAML example

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Defines an exception breakpoint with default settings. The type is 'ExceptionBreakpoint' and other fields are set to their defaults.

```yaml
breakpoints:
  - type: ExceptionBreakpoint
    enabled: true
    ignoreCount: 0
    continueAfterRunningActions: false
```

--------------------------------

### Configure Deployment Targets and Supported Destinations

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/platform-config.md

Demonstrates how to define deployment targets using Version parsing, manage project configurations, and specify supported destinations for multiplatform applications.

```swift
import ProjectSpec
import Version

let deploymentTarget = DeploymentTarget(
    iOS: try Version.parse("15.0"),
    macOS: try Version.parse("12.0")
)

var configs = Config.defaultConfigs
configs.append(Config(name: "Staging", type: .debug))

// variant matching drives config-variant schemes ("MyApp Staging")
let staging = configs.first(including: "staging", for: .debug)

// supported destinations for a multiplatform app
let destinations: [SupportedDestination] = [.iOS, .macCatalyst, .watchOS]
print(destinations.map(\.priority))

let project = try Project(
    basePath: ".",
    name: "MyApp",
    configs: configs,
    options: SpecOptions(deploymentTarget: deploymentTarget)
)
```

--------------------------------

### Configure Supported Destinations

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Example of using supportedDestinations to manage build settings for multiple platforms, including destination-specific source filters.

```yaml
targets:
  MyFramework:
    type: framework
    supportedDestinations: [iOS, tvOS]
    deploymentTarget:
      iOS: 9.0
      tvOS: 10.0
    sources:
      - path: MySources
        inferDestinationFiltersByPath: true
      - path: OtherSources
        destinationFilters: [iOS]
```

--------------------------------

### Standalone preset lookup with getBuildSettings()

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/settingspresetfile.md

Demonstrates standalone lookup of preset build settings. Returns nil for product presets that don't exist on disk, e.g. `.product(.xcodeExtension)`.

```swift
let debugSettings = SettingsPresetFile.config(.debug).getBuildSettings()
let appSettings = SettingsPresetFile.productPlatform(.application, .iOS).getBuildSettings()

print(debugSettings?["SWIFT_OPTIMIZATION_LEVEL"] ?? .string("(unset)"))
```

--------------------------------

### Configure Multi-Platform Targets

Source: https://github.com/yonaskolb/xcodegen/blob/master/Docs/ProjectSpec.md

Example of defining a target for multiple platforms, which generates separate targets with platform-specific suffixes and build settings.

```yaml
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}
```

--------------------------------

### init(project:)

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/filewriter.md

Initializes a FileWriter instance with the target project used for default paths and plist generation.

```APIDOC
## init(project:)

### Description
Initializes a FileWriter instance with the target project used for default paths and plist generation.

### Method
init

### Parameters
- **project** (Project) - Required - Target project; used for `defaultProjectPath`, `basePath`, and its targets' plists.

### Request Example
```swift
let fileWriter = FileWriter(project: project)
```
```

--------------------------------

### Generate a PBXProj object

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/pbxprojgenerator.md

Demonstrates how to initialize a PBXProjGenerator with a Project specification and generate a live PBXProj object for post-processing.

```swift
import ProjectSpec
import XcodeGenKit
import XcodeProj
import PathKit

let project = try Project(path: Path("project.yml"))
let generator = PBXProjGenerator(project: project)
let pbxProj = try generator.generate()

// pbxProj is a live PBXProj — do any post-processing before serialization
print("Objects: \(pbxProj.objects.count)")
```

--------------------------------

### Configure SpecOptions.settingPresets

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/settingspresetfile.md

Shows how to configure `SpecOptions.settingPresets` to control preset application. The commented lines show alternative values for project-level or target-level presets only.

```swift
import ProjectSpec
import XcodeGenKit

var options = SpecOptions()
options.settingPresets = .none      // disable all presets
// options.settingPresets = .project // project-level presets only
// options.settingPresets = .targets // target-level presets only
```

--------------------------------

### FileWriter error handling example

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/filewriter.md

Shows how to catch errors from writePlists() and writeXcodeProject(), e.g., read-only target directory or invalid plist values.

```swift
do {
    try fileWriter.writePlists()
    try fileWriter.writeXcodeProject(xcodeProject)
} catch {
    // e.g. read-only target directory, invalid plist values
    print("Failed to write outputs: \(error.localizedDescription)")
}
```

--------------------------------

### SpecFile init(path:projectRoot:variables:)

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/specfile.md

Initializes a SpecFile by loading the spec file from the given path, expanding variables, parsing includes, and recursively loading sub-specs.

```APIDOC
## SpecFile init(path:projectRoot:variables:)

### Description
Initializes a SpecFile by loading the spec file from the given path, expanding variables, parsing includes, and recursively loading sub-specs.

### Method
Initializer

### Signature
```swift
public init(path: Path, projectRoot: Path? = nil, variables: [String: String] = [:]) throws
```

### Parameters
- **path** (Path) - Required - Absolute path to the spec file.
- **projectRoot** (Path?) - Optional - Base path override; nil uses the spec file's parent directory.
- **variables** ([String: String]) - Optional - Variables for ${VAR} expansion.

### Description
Loads the file (.json via JSONSerialization, otherwise YAML via loadYamlDictionary), expands variables in both keys and values, parses include entries, and recursively loads sub-specs. A file-level fatalError occurs when a JSON spec does not decode to a [String: Any] root.
```

--------------------------------

### Error handling with do-catch

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/projectgenerator.md

Error handling example for direct library callers. It catches SpecParsingError, SpecValidationError, and generic errors, printing appropriate messages.

```swift
import Version

do {
    let project = try Project(path: Path("project.yml"))
    let xcodeProject = try ProjectGenerator(project: project)
        .generateXcodeProject(userName: "jsmith")
    try FileWriter(project: project).writeXcodeProject(xcodeProject)
} catch let error as SpecParsingError {
    print("Spec parse error: \(error.description)")
} catch let error as SpecValidationError {
    print("Validation failed:\n\(error.description)")
} catch {
    print("Generation failed: \(error)")
}
```

--------------------------------

### BuildSetting helpers

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/settings.md

Initializer and conversion methods for `BuildSetting`.

```swift
extension BuildSetting {
    public init(any value: Any)
    public func toAny() -> Any
}
```

--------------------------------

### init(type:reference:embed:codeSign:link:implicit:weakLink:platformFilter:destinationFilters:platforms:copyPhase:)

Source: https://github.com/yonaskolb/xcodegen/blob/master/_autodocs/api-reference/dependency.md

Creates a Dependency instance with the required type and reference, and optional configuration for embedding, code signing, linking, platform filters, and copy phase settings.

```APIDOC
## init(type:reference:embed:codeSign:link:implicit:weakLink:platformFilter:destinationFilters:platforms:copyPhase:)

### Description
Creates a Dependency instance with the required type and reference, and optional configuration for embedding, code signing, linking, platform filters, and copy phase settings.

### Method
Initializer

### Signature
```swift
public init(
    type: DependencyType,
    reference: String,
    embed: Bool? = nil,
    codeSign: Bool? = nil,
    link: Bool? = nil,
    implicit: Bool = implicitDefault,
    weakLink: Bool = weakLinkDefault,
    platformFilter: PlatformFilter = platformFilterDefault,
    destinationFilters: [SupportedDestination]? = nil,
    platforms: Set<Platform>? = nil,
    copyPhase: BuildPhaseSpec.CopyFilesSettings? = nil
)
```

### Parameters
- **type** (`DependencyType`) - Required - Dependency kind.
- **reference** (`String`) - Required - Referenced name/path.
- **embed** (`Bool?`) - Optional (default `nil`) - Embed in the product; defaults to product-type behavior.
- **codeSign** (`Bool?`) - Optional (default `nil`) - Code-sign the embedded copy.
- **removeHeaders** (`Bool`) - Optional (default `true`) - Remove headers when copying frameworks.
- **link** (`Bool?`) - Optional (default `nil`) - Link against the product.
- **implicit** (`Bool`) - Optional (default `false`) - Implicit dependency.
- **weakLink** (`Bool`) - Optional (default `false`) - Weak-link (spec key `weak`).
- **platformFilter** (`PlatformFilter`) - Optional (default `.all`) - Platform filter (`all`/`iOS`/`macOS`).
- **destinationFilters** (`[SupportedDestination]?`) - Optional (default `nil`) - Restrict to supported destinations.
- **platforms** (`Set<Platform>?`) - Optional (default `nil`) - Restrict dependency to platforms; target parsing filters out non-matching dependencies.
- **copyPhase** (`BuildPhaseSpec.CopyFilesSettings?`) - Optional (default `nil`) - Custom copy-files phase settings.

### Return Value
A new `Dependency` instance.
```
Tokens:
Raw