skip to content

In Xcode, how do a target, a scheme and a build configuration differ, and which level wins when a build setting is set twice?

level: juniorimportance: must knowfreq 80%

answer

  1. product, recipe for actions, named value set
  2. a scheme picks configuration per action
  3. Levels filter and the Resolved column
  4. target beats its .xcconfig, then project
  5. $(inherited) pulls in the level below

basics

~20 s

A target builds one product, a scheme picks the targets and the configuration each action uses, and a configuration such as Debug names one set of values. Target settings beat the target's .xcconfig, then project settings, the project's .xcconfig and defaults.

solid answer

~50 s

A **target** produces one product, such as the app, a widget extension or a test bundle, from its own sources, build phases and build settings. A **build configuration** (Debug, Staging, Release) is a named set of setting values every target carries. A **scheme** says what Xcode does when you build, run, test, profile or archive: which targets build and, for Run, Test and Profile, which configuration, arguments and environment to use. When a setting is set in several places, Xcode resolves it in this order, highest first: the target's Build Settings, the `.xcconfig` mapped to the target, the project's Build Settings, the `.xcconfig` mapped to the project, then system defaults. The **Levels** filter shows each level and the **Resolved** column the winner; `$(inherited)` appends to the value from the level below instead of replacing it.

code

plaintext · 9 lines
plaintext
// Base.xcconfig: shared by every configuration of the app target
PRODUCT_BUNDLE_IDENTIFIER = com.example.mealkit
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon

// Staging.xcconfig: mapped to the Staging configuration on the project's Info tab
#include "Base.xcconfig"
PRODUCT_BUNDLE_IDENTIFIER = com.example.mealkit.staging
ASSETCATALOG_COMPILER_APPICON_NAME = AppIconStaging
SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) STAGING

go deeper

for a junior

Define target, scheme and configuration in one sentence each, and recite the five precedence levels from target down to system defaults.

for a middle

Show how a Staging configuration is built from .xcconfig files with #include and $(inherited), and how the Levels view proves which value won.

for a senior

Explain how a stray target-level override or the wrong scheme ships the wrong bundle identifier, and how you would catch it in review or CI.

for a principal

Argue for a team rule that keeps settings in reviewed .xcconfig files and the project editor empty, and weigh what that costs people used to the editor.

## Three things that are easy to mix up Xcode separates *what* gets built from *how* and *when* it is built. Three nouns carry that split: - **Target**: one product. In a meal-kit project the iOS app, its widget extension, its watch app, an in-house framework and each test bundle are separate targets. A target owns its source files (the Compile Sources build phase), its other build phases and its own build settings. - **Build configuration**: a named set of build-setting values defined at the project level. Templates start with Debug and Release; the meal-kit team adds **Staging**. Apple's scheme documentation describes the usual split: a debug configuration disables optimizations and generates debugging information, a release configuration enables optimizations and drops debug information to reduce app size. - **Scheme**: the instructions Xcode follows for an action. It lists the targets to build and, for Run, Test and Profile, the **Build Configuration**, launch arguments, environment variables, diagnostics and, for Test, the test plans. Xcode shares schemes with the team by default. So the meal-kit project can have a single app target, three configurations and three schemes, **MealKit Debug**, **MealKit Staging** and **MealKit Release**, whose Run actions each point at a different configuration. Same target, same sources, different settings. ## Where one build setting can be set A build setting such as `PRODUCT_BUNDLE_IDENTIFIER` can have a value at several levels. Apple's documentation on configuring build settings gives the precedence, highest first: 1. Target-level values (the target's Build Settings tab). 2. Values from the configuration settings file (`.xcconfig`) mapped to that target. 3. Project-level values. 4. Values from the `.xcconfig` mapped to the project. 5. System default values. At each level, a value typed into the project editor beats the configuration file mapped at that same level. That surprises people who expect a checked-in `.xcconfig` to be the final word: a stray value left in the target's Build Settings tab silently overrides it. | Level | Where you edit it | Typical use | |---|---|---| | Target | target > Build Settings | one-off overrides, ideally none | | Target `.xcconfig` | project > Info > Configurations | per-target, per-configuration values in review-friendly text | | Project | project > Build Settings | values shared by every target | | Project `.xcconfig` | project > Info > Configurations | shared values in text | | Default | the SDK and the target type | the baseline | ## Reading which value won Select the target's Build Settings and switch to the **Levels** filter. Xcode shows a column per level plus a **Resolved** column with the final value it builds with; highlighted values are the ones taking precedence, and modified settings are shown in bold. To remove an override, delete it at the level where it was set, not at a lower one. ## Layering .xcconfig files A build configuration file is plain text, one `SETTING = value` per line, chosen per configuration on the project's **Info** tab. Useful rules: - Only one file can be mapped per configuration and level, but it can pull in others with `#include "Base.xcconfig"`; `#include?` silences the warning when the file is missing. - If a file assigns a setting twice, the last assignment wins. - `$(inherited)` inserts the value from the level below, so `SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) STAGING` adds a condition instead of wiping the `DEBUG` one a template set at project level. - `$(SETTING_NAME)` substitutes another setting's value. - A setting can be conditional: `[config=Debug]`, `[sdk=iphoneos*]` or `[arch=arm64]` after its name. - When creating the file, leave every target unchecked so Xcode does not copy it into the app bundle as a resource. ## The command line sits on top `xcodebuild` accepts `SETTING=value` arguments, and Apple's documentation says it gives settings passed to it the highest precedence. The man page refines that: a file passed with `-xcconfig` overrides all other settings, including ones passed individually on the command line, and a file named by the `XCODE_XCCONFIG_FILE` environment variable overrides even the `-xcconfig` file. A CI machine that exports that variable can therefore change every build it runs without touching the project. ## Why interviewers ask Most "it works on my machine" release bugs come from one of these levels: the wrong scheme selected, so the wrong configuration was built, or an override sitting at a higher level than the file everybody reviews.

  • How does a value passed to xcodebuild rank against the target's Build Settings tab?
    It wins. Apple's documentation says `xcodebuild` gives settings you pass to it the highest precedence. Within the command line, the man page adds two further layers: a file passed with `-xcconfig` overrides settings passed individually, and a file named by the `XCODE_XCCONFIG_FILE` environment variable overrides even that file.
  • Why can two schemes of the same target produce two different apps?
    Each scheme's Run, Test and Profile actions name a build configuration. If **MealKit Staging** runs the Staging configuration, Xcode resolves settings from the Staging `.xcconfig`, so the bundle identifier, the app icon and the compilation conditions differ from the Release build, although the target and its sources are identical.
  • A value in your reviewed .xcconfig is ignored. Where do you look first?
    Open the target's Build Settings with the **Levels** filter. A value in the target column, shown highlighted, outranks the target's `.xcconfig`, so someone probably typed an override into the editor. Delete it at the target level and the file's value becomes the resolved one.

A target is a recipe, a build configuration is the portion size, and a scheme is the order ticket telling the kitchen which recipes to cook, at which size, for which service.

  • A scheme is a product, so adding a scheme adds an app
  • An .xcconfig file always overrides the Build Settings tab
  • The project value wins because targets inherit from the project
  • Leaving out $(inherited) still appends to the inherited value
  • Debug and Release are schemes, not build configurations