Scheme

API reference for the Scheme type in Tuist’s ProjectDescription framework

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.

Related APIs

• Project - Contains schemes
• Target - Referenced by scheme actions
• Settings - Configurations referenced by actions