PackageInfoMapper#

PackageInfoMapper is the core component in TuistLoader that translates Swift Package Manager manifest data (PackageInfo) into Tuist's ProjectDescription.Project representation. It lives at cli/Sources/TuistLoader/SwiftPackageManager/PackageInfoMapper.swift (~2,800 lines) and conforms to the PackageInfoMapping protocol 1.

Its two primary entry points are:

• resolveExternalDependencies(...) — maps all resolved SPM packages into [String: [TargetDependency]]
• map(...) — maps a single PackageInfo into a ProjectDescription.Project?

Build Settings Generation#

The Settings.from(target:...) static method 2 is the central routine for producing build settings for each generated target. It:

1. Delegates SPM-to-Xcode flag translation to SettingsMapper (mapSettings() returns a base SettingsDictionary; settingsForBuildConfiguration(_:) layers in config-conditional overrides)
2. Emits MODULEMAP_FILE when a generated module map path is available 3
3. Sets DEFINES_MODULE = NO and appends -fmodule-name=<moduleName> to OTHER_CFLAGS for .directory, .header, and .custom module map cases 4
4. Appends prebuilt library flags (OTHER_SWIFT_FLAGS -I, LIBRARY_SEARCH_PATHS, LD_RUNPATH_SEARCH_PATHS, OTHER_LDFLAGS -l) for prebuilt static library artifacts 5
5. Merges package base settings into the target's baseSettingsDictionary, with PRODUCT_BUNDLE_IDENTIFIER explicitly excluded to avoid clobbering sanitized per-target identifiers 6
6. Merges user-defined per-target overrides from PackageSettings.targetSettings, with arrays unioned and scalars overriding 7

Module Map Generation#

Module map generation is delegated to SwiftPackageManagerModuleMapGenerator (injected into PackageInfoMapper at init time). Generated files are written into Derived/ModuleMaps/ for local packages 8. The generator's writeIfDifferent method preserves file modification times when content hasn't changed 9 — a fix introduced in PR #11351 to stop Xcode from invalidating Swift compilation due to phantom mtime changes on module map files.

The downstream ModuleMapMapper (a graph mapper in TuistGenerator) propagates -Xcc -fmodule-map-file= flags and HEADER_SEARCH_PATHS across the dependency graph. Since PR #11797, it skips appending these flags to configurations that already contain $(inherited), preventing duplication in inheriting configurations.

Framework Search Paths & Response Files#

When a target has ≥20 precompiled framework search paths, FrameworkSearchPathsGraphMapper consolidates them into a response file at Derived/FrameworkSearchPaths/<Target>.resp 10. The response file is referenced via @file in OTHER_CFLAGS and OTHER_LDFLAGS, but OTHER_SWIFT_FLAGS receives -F flags directly 11. This was changed in PR #11023 to fix an Xcode 26 breakage where -Xcc @<resp> in OTHER_SWIFT_FLAGS caused ClangImporter to generate two -cc1 jobs, failing with "expected exactly one compiler job."

Trait-Conditional Settings#

When enabledTraits is non-empty, Settings.from(...) resolves trait conditions and appends matching names to SWIFT_ACTIVE_COMPILATION_CONDITIONS 12. Dependencies and prebuilts guarded by .when(traits:) conditions are excluded if none of their required traits appear in enabledTraits 13. PR #11370 fixed a prior gap where trait-conditional build settings were silently dropped because SettingsMapper didn't receive trait information.

Base Settings Propagation#

PackageSettings.baseSettings defines package-wide Xcode settings (e.g., deployment targets). These are merged into every generated target's base settings dictionary, with target-specific overrides taking final precedence 14. PR #11574 closed a gap where macro targets were excluded from this merge, causing build failures when MACOSX_DEPLOYMENT_TARGET was set at the package level.

Caching#

PR #11760 added SwiftPackageManagerGraphCache to serialize the fully-mapped DependenciesGraph to disk. The cache key hashes workspace-state.json, root manifest content, local package fingerprints, Swift/Tuist versions, and environment variables. The cache is invalidated if any recorded derived file (generated module map, XCFramework) is missing. This cuts ~2–4 s from tuist generate invocations when SPM dependencies are unchanged.

Key Related Files#