Xcode build insights

REQUIREMENTS

• A Tuist account and project
• Tuist CLI 4.138.1 or later
• A Xcode project

Working on large projects should not require rebuilding the same code repeatedly. Tuist Build Insights lets you track build analytics so you can identify trends before local and CI build times become bottlenecks.

Build insights are driven by the tuist inspect build command, typically added to your scheme's post-action.

To start tracking local build times, you can leverage the tuist inspect build command by adding it to your scheme's post-action:

INFO

Set the "Provide build settings from" field to the executable or your main build target to capture build configuration.

INFO

If you are not using generated projects, the post-scheme action is not executed when the build fails.

You can execute it in that case by setting runPostActionsOnFailure to YES in the relevant project.pbxproj BuildAction:

<BuildAction
   buildImplicitDependencies="YES"
   parallelizeBuildables="YES"
+  runPostActionsOnFailure="YES">

For Mise, activate tuist in the post-action environment:

# -C ensures that Mise loads the configuration from the Mise configuration
# file in the project's root directory.
$HOME/.local/bin/mise x -C $SRCROOT -- tuist inspect build

MISE & PROJECT PATHS

Your environment's PATH is not inherited by the scheme post action, so use Mise's absolute path. This depends on how you installed Mise. Build settings should be inherited from a target so mise can run from $SRCROOT.

Once logged in, local builds are tracked and available from the Tuist dashboard:

TIP

To quickly access the dashboard, run tuist project show --web from the CLI.

Generated projects

INFO

Auto-generated schemes automatically include the tuist inspect build post-action.

If you do not want to track build insights in generated schemes, disable it using buildInsightsDisabled.

If you are using generated projects with custom schemes, add post-actions:

let project = Project(
    name: "MyProject",
    targets: [
        // Your targets
    ],
    schemes: [
        .scheme(
            name: "MyApp",
            shared: true,
            buildAction: .buildAction(
                targets: ["MyApp"],
                postActions: [
                    .executionAction(
                        title: "Inspect Build",
                        scriptText: """
                        $HOME/.local/bin/mise x -C $SRCROOT -- tuist inspect build
                        """,
                        target: "MyApp"
                    )
                ],
                runPostActionsOnFailure: true
            ),
            runAction: .runAction(configuration: "Debug")
        )
    ]
)

If you are not using Mise, simplify to:

buildAction: .buildAction(
    targets: ["MyApp"],
    postActions: [
        .executionAction(
            title: "Inspect Build",
            scriptText: "tuist inspect build",
            target: "MyApp"
        )
    ],
    runPostActionsOnFailure: true
)

Build Insights in CI

To track build insights on CI, make sure CI is authenticated.

For Xcodebuild-driven CI you need to:

• Use tuist xcodebuild when invoking xcodebuild actions.
• Add -resultBundlePath to your xcodebuild command.

Without -resultBundlePath, required activity logs and result bundles are not generated and tuist inspect build cannot analyze the build.

Custom metadata

You can attach metadata to builds with environment variables to improve filtering.

Environment variables

Variable	Format	Description
TUIST_BUILD_TAGS	Comma-separated	Multiple tags in one variable.
TUIST_BUILD_VALUE_*	Single value	Key-value pair where suffix is the key.

Examples

Set these values in CI or your shell before invoking your build:

export TUIST_BUILD_TAGS="nightly,ios-team,release-candidate"

export TUIST_BUILD_VALUE_TICKET="PROJ-1234"
export TUIST_BUILD_VALUE_PR_URL="https://github.com/myorg/myrepo/pull/123"

Gradle build insights

If you are using Gradle, configure build insights in the Gradle build insights guide.