Swift Package Compiler Flags in Tuist#

Tuist maps Swift Package Manager (SPM) packages into Xcode projects via PackageInfoMapper. A key part of that mapping is populating OTHER_SWIFT_FLAGS (and companion build settings) with the right compiler flags so each generated target behaves identically to how SwiftPM would build it.

Two source files drive this:

-package-name (Swift 5.9+)#

The package access level modifier introduced in Swift 5.9 requires the compiler to know what package a module belongs to. Tuist injects this at the project level in PackageInfo.projectSettings().

When the package's tools-version is >= 5.9.0, Tuist appends ["$(inherited)", "-package-name", <name>] to OTHER_SWIFT_FLAGS 1. The flag value is the package name, quoted if it contains spaces. The implementation merges cleanly with any pre-existing value in the setting — handling .array, .string, and .none variants — so that base settings supplied by the user are never overwritten 2.

Because this is set at project scope (not target scope), the flag is automatically inherited by every target in the generated .xcodeproj for that package.

-module-alias#

SPM allows a dependency to be imported under a different name via moduleAliases. Tuist tracks these during dependency resolution and surfaces them in OTHER_SWIFT_FLAGS for each target that uses an aliased dependency.

Collection phase — inside mapDependency, when a dependency has an alias entry, the mapping originalName → aliasedName is stored in dependencyModuleAliases 3. The target dependency itself is registered under the aliased name.

Application phase — in Settings.from(), the collected aliases are flattened into pairs ["-module-alias", "OriginalName=AliasedName", ...] and appended to OTHER_SWIFT_FLAGS. Like the -package-name logic, it handles both .array and .string forms of any pre-existing value 4.

This mirrors what SwiftPM itself passes to the compiler when a package uses module aliasing.

SettingsMapper: Per-Target Swift Flags#

SettingsMapper handles the build settings declared inside a target's manifest (.target(settings:)). Its map() function accumulates flags into typed arrays, then writes them all at once:

5

All collected swiftFlags are written to OTHER_SWIFT_FLAGS as ["$(inherited)"] + swiftFlags 6, ensuring parent build settings are always preserved.

SettingsMapper is instantiated inside Settings.from() in PackageInfoMapper 7, and mapSettings() is called before -module-alias flags are appended 8, so the final OTHER_SWIFT_FLAGS value is the union of all sources.

Prebuilt Dependencies and Include Paths#

For targets that depend on prebuilt libraries (e.g., cached XCFrameworks), Tuist also appends -I <path> include search path pairs to OTHER_SWIFT_FLAGS so the compiler can locate the prebuilt module's headers 9. This happens after SettingsMapper output and -module-alias flags have been merged.

Layering Order#

OTHER_SWIFT_FLAGS for each target is seeded with ["$(inherited)"] before any mapper runs 10. Flags are then appended in this order:

1. SettingsMapper output — manifest-declared settings merged on top 8.
2. -module-alias pairs — one pair per aliased dependency 11.
3. Prebuilt -I paths — include search paths for cached XCFrameworks 9.

The project-level OTHER_SWIFT_FLAGS (carrying -package-name) is set separately in projectSettings() and is inherited by every target in that project via Xcode's standard build setting inheritance.