Skip to main content

​
Settings

A group of build settings configuration for projects and targets.

​
Overview

The Settings type allows you to define build settings, configurations, and xcconfig files for both projects and targets. Settings can be defined at different levels and are merged according to Xcode’s build setting resolution rules.

​
Basic Usage

import ProjectDescription

let settings = Settings.settings(
    base: [
        "SWIFT_VERSION": "5.9",
        "ENABLE_BITCODE": "NO"
    ],
    debug: [
        "SWIFT_OPTIMIZATION_LEVEL": "-Onone",
        "GCC_PREPROCESSOR_DEFINITIONS": ["DEBUG=1"]
    ],
    release: [
        "SWIFT_OPTIMIZATION_LEVEL": "-O",
        "SWIFT_COMPILATION_MODE": "wholemodule"
    ]
)

​
Custom Configurations

let settings = Settings.settings(
    base: [
        "SWIFT_VERSION": "5.9"
    ],
    configurations: [
        .debug(name: "Debug", settings: [
            "SWIFT_OPTIMIZATION_LEVEL": "-Onone"
        ]),
        .debug(name: "Staging", settings: [
            "SWIFT_OPTIMIZATION_LEVEL": "-Onone",
            "API_URL": "https://staging.example.com"
        ]),
        .release(name: "Release", settings: [
            "SWIFT_OPTIMIZATION_LEVEL": "-O"
        ])
    ]
)

​
With XCConfig Files

let settings = Settings.settings(
    base: [
        "SWIFT_VERSION": "5.9"
    ],
    configurations: [
        .debug(name: "Debug", settings: [:], xcconfig: "Configs/Debug.xcconfig"),
        .release(name: "Release", settings: [:], xcconfig: "Configs/Release.xcconfig")
    ]
)

​
Simple Settings (Default Configurations)

​
.settings() Method

Creates settings with default Debug and Release configurations.
​
base
SettingsDictionary
default:"[:]"
A dictionary with build settings inherited by all configurations.
​
debug
SettingsDictionary
default:"[:]"
Build settings specific to the Debug configuration.
​
release
SettingsDictionary
default:"[:]"
Build settings specific to the Release configuration.
​
defaultSettings
DefaultSettings
default:".recommended"
An enum specifying the set of default settings. See DefaultSettings section below.
​
defaultConfiguration
String?
default:"nil"
The default configuration to be used when building from the command line.

​
Custom Configurations Settings

​
.settings(configurations:) Method

Creates settings with custom configurations.
​
base
SettingsDictionary
default:"[:]"
A dictionary with build settings inherited by all configurations.
​
configurations
[Configuration]
required
A list of custom configurations. Should not be empty - use the simpler method for default Debug/Release configurations.
​
defaultSettings
DefaultSettings
default:".recommended"
An enum specifying the set of default settings.
​
defaultConfiguration
String?
default:"nil"
The default configuration to be used when building from the command line.

​
Configuration

Represents a build configuration (Debug or Release variant).

​
Debug Configuration

Configuration.debug(
    name: "Debug",
    settings: [
        "SWIFT_OPTIMIZATION_LEVEL": "-Onone",
        "DEBUG_INFORMATION_FORMAT": "dwarf-with-dsym"
    ],
    xcconfig: "Configs/Debug.xcconfig"
)
​
name
ConfigurationName
required
The name of the configuration to use.
​
settings
SettingsDictionary
default:"[:]"
The build settings to apply for this configuration.
​
xcconfig
Path?
default:"nil"
The xcconfig file to associate with this configuration.

​
Release Configuration

Configuration.release(
    name: "Release",
    settings: [
        "SWIFT_OPTIMIZATION_LEVEL": "-O",
        "SWIFT_COMPILATION_MODE": "wholemodule"
    ],
    xcconfig: "Configs/Release.xcconfig"
)
Parameters are the same as debug configuration.

​
SettingValue

Represents a build setting value, which can be a string, array of strings, or boolean.

​
String Value

"SWIFT_VERSION": "5.9"

​
Array Value

"OTHER_SWIFT_FLAGS": ["-D", "DEBUG", "-enable-testing"]

​
Boolean Value

"ENABLE_BITCODE": true  // Converts to "YES"
"ENABLE_TESTABILITY": false  // Converts to "NO"

​
From RawRepresentable

enum Environment: String {
    case development = "DEVELOPMENT"
    case production = "PRODUCTION"
}

"ENVIRONMENT": SettingValue(Environment.development)

​
DefaultSettings

Specifies the default set of settings applied to projects and targets. 
defaultSettings: .recommended
Recommended settings including warning flags to help catch bugs early. This is the default. 
defaultSettings: .recommended(excluding: ["SWIFT_VERSION", "IPHONEOS_DEPLOYMENT_TARGET"])
Recommended settings with specific keys excluded, allowing you to override them in custom configurations.

​
.essential

defaultSettings: .essential
A minimal set of settings to make the project compile (e.g., PRODUCT_NAME, TARGETED_DEVICE_FAMILY).

​
.essential(excluding:)

defaultSettings: .essential(excluding: ["PRODUCT_NAME"])
Essential settings with specific keys excluded.

​
.none

defaultSettings: .none
Tuist won’t generate any default build settings. You must provide all necessary settings manually.

​
Examples

​
Project-Level Settings

let project = Project(
    name: "MyProject",
    settings: .settings(
        base: [
            "SWIFT_VERSION": "5.9",
            "IPHONEOS_DEPLOYMENT_TARGET": "15.0"
        ],
        configurations: [
            .debug(name: "Debug"),
            .release(name: "Release")
        ],
        defaultSettings: .recommended
    ),
    targets: [...]
)

​
Target-Level Settings

let target = Target.target(
    name: "MyApp",
    destinations: .iOS,
    product: .app,
    bundleId: "com.example.myapp",
    settings: .settings(
        base: [
            "PRODUCT_BUNDLE_IDENTIFIER": "com.example.myapp",
            "CODE_SIGN_STYLE": "Automatic"
        ],
        debug: [
            "CODE_SIGN_ENTITLEMENTS": "Debug.entitlements"
        ],
        release: [
            "CODE_SIGN_ENTITLEMENTS": "Release.entitlements"
        ]
    )
)

​
Multiple Environments

let settings = Settings.settings(
    base: [
        "SWIFT_VERSION": "5.9"
    ],
    configurations: [
        .debug(name: "Debug", settings: [
            "API_URL": "http://localhost:8080"
        ]),
        .debug(name: "Staging", settings: [
            "API_URL": "https://staging-api.example.com"
        ]),
        .release(name: "Production", settings: [
            "API_URL": "https://api.example.com"
        ])
    ],
    defaultConfiguration: "Debug"
)

​
Setting Resolution Order

Build settings are resolved in this order (later overrides earlier):
  1. Tuist’s default settings (if .recommended or .essential)
  2. Project base settings
  3. Project configuration settings
  4. Project xcconfig file
  5. Target base settings
  6. Target configuration settings
  7. Target xcconfig file
  • Project - Can have project-level settings
  • Target - Can have target-level settings
  • Scheme - References configurations in actions