Skip to main content

​
Scheme

A custom scheme for a project that defines how to build, run, test, profile, analyze, and archive.

​
Overview

A Scheme defines a collection of targets to build, run, test, profile, analyze, and archive. Schemes control the behavior of these actions in Xcode and from the command line.

​
Usage

import ProjectDescription

let scheme = Scheme.scheme(
    name: "MyApp-Debug",
    shared: true,
    buildAction: .buildAction(targets: ["MyApp", "MyFramework"]),
    testAction: .targets(
        ["MyAppTests"],
        configuration: .debug,
        options: .options(coverage: true)
    ),
    runAction: .runAction(
        configuration: .debug,
        executable: "MyApp",
        arguments: .arguments(
            launchArguments: [
                .launchArgument(name: "-UITests", isEnabled: true)
            ]
        )
    ),
    archiveAction: .archiveAction(configuration: .release),
    profileAction: .profileAction(configuration: .release),
    analyzeAction: .analyzeAction(configuration: .debug)
)

​
Minimal Example

let scheme = Scheme.scheme(
    name: "MyApp",
    shared: true,
    buildAction: .buildAction(targets: ["MyApp"]),
    runAction: .runAction(executable: "MyApp")
)

​
Initializer

​
.scheme() Static Method

​
name
String
required
The name of the scheme.
​
shared
Bool
default:"true"
Marks the scheme as shared (i.e., checked into the repository and visible to xcodebuild from the command line).
​
hidden
Bool
default:"false"
When true, the scheme doesn’t show up in Xcode’s scheme dropdown list.
​
buildAction
BuildAction?
default:"nil"
Action that builds the project targets.
​
testAction
TestAction?
default:"nil"
Action that runs the project tests.
​
runAction
RunAction?
default:"nil"
Action that runs project built products.
​
archiveAction
ArchiveAction?
default:"nil"
Action that runs the project archive.
​
profileAction
ProfileAction?
default:"nil"
Action that profiles the project.
​
analyzeAction
AnalyzeAction?
default:"nil"
Action that analyzes the project.

​
Action Types

​
BuildAction

Defines which targets to build and in what order. 
.buildAction(
    targets: ["MyApp", "MyFramework"],
    preActions: [],
    postActions: []
)

​
TestAction

Defines which test targets to run and testing options. 
.targets(
    ["MyAppTests", "MyFrameworkTests"],
    configuration: .debug,
    options: .options(
        coverage: true,
        codeCoverageTargets: ["MyApp"],
        language: "en",
        region: "US"
    )
)

​
RunAction

Defines how to run the app, including which executable to run and runtime options. 
.runAction(
    configuration: .debug,
    executable: "MyApp",
    arguments: .arguments(
        environmentVariables: [
            "API_URL": .environmentVariable(value: "https://api.example.com", isEnabled: true)
        ],
        launchArguments: [
            .launchArgument(name: "-UITests", isEnabled: true)
        ]
    )
)

​
ArchiveAction

Defines how to archive the app for distribution. 
.archiveAction(
    configuration: .release,
    revealArchiveInOrganizer: true
)

​
ProfileAction

Defines how to profile the app using Instruments. 
.profileAction(
    configuration: .release,
    executable: "MyApp"
)

​
AnalyzeAction

Defines how to run static analysis. 
.analyzeAction(configuration: .debug)

​
Best Practices

  1. Shared Schemes: Set shared: true for schemes you want to commit to version control and use in CI/CD.
  2. Configuration-Specific Schemes: Create separate schemes for different configurations: 
    Scheme.scheme(name: "MyApp-Debug", shared: true, buildAction: ..., runAction: .runAction(configuration: .debug)),
Scheme.scheme(name: "MyApp-Release", shared: true, buildAction: ..., runAction: .runAction(configuration: .release))
  3. Test Coverage: Enable code coverage in test actions: 
    testAction: .targets(["MyAppTests"], options: .options(coverage: true))
  4. Hidden Schemes: Use hidden: true for internal or experimental schemes you don’t want to clutter the UI.
  • Project - Contains schemes
  • Target - Referenced by scheme actions
  • Settings - Configurations referenced by actions