Swift Macro Support in Tuist#

Tuist models Swift macros as a first-class product type and routes them through Xcode's native macro dependency mechanism rather than shell-copy workarounds. Three distinct concerns drive the implementation:

1. Graph modeling — dedicated .macro nodes in the dependency graph
2. Build settings generation — native Xcode settings for source and precompiled macro targets
3. Framework search path exclusion — macro references are not linkable products and must be kept out of FRAMEWORK_SEARCH_PATHS

This design was established in PR #11825 (merged 2026-07-14), which replaced an earlier workaround that copied macro executables to a hardcoded Debug path and injected -load-plugin-executable flags into every consumer.

Graph Modeling#

Product and Dependency Types#

The Product enum in XcodeGraph/Models/Product.swift carries a .macro case. At the dependency-graph layer, two parallel types represent macros:

• GraphDependency.macro(path:) — a runtime node for a macro executable on disk
• GraphDependencyReference.macro(path:) — the resolved reference type used downstream by generators

GraphDependencyReference.macro carries no PlatformCondition 1 — macros are platform-independent at the reference level — and its precompiledPath is nil 2, which is the key property that keeps macros out of framework search path generation.

Traversal Helpers in GraphTraverser#

isDependencyPrecompiledMacro(_:) is the central boolean filter: it returns true only for .macro nodes. It is passed as a skip predicate throughout filterDependencies calls so macro nodes are never traversed into by the standard linking and embedding logic.

allPrecompiledSwiftMacroExecutables(path:name:) collects precompiled macro executables for a given target. It matches both direct .macro nodes and XCFrameworks whose inner .macro sub-dependency indicates a cached macro. Results are formatted as path#baseName strings — the format expected by SWIFT_LOAD_BINARY_MACROS — and memoized in precompiledSwiftMacroExecutablesCache. 3

Native Xcode Build Settings#

Both macro producer and consumer settings are emitted in ConfigGenerator.swift.

Source Macro Targets#

swiftMacroImplementationDerivedSettings(_:) fires when target.product == .macro and emits:

With these settings, Xcode derives the macro executable path from the target dependency graph and propagates the macro implementation transitively. No shell copy phase is needed. 4

Binary / Precompiled Macros#

precompiledSwiftMacrosDerivedSettings(_:graphTraverser:projectPath:) calls allPrecompiledSwiftMacroExecutables and, if the result is non-empty, sets:

SWIFT_LOAD_BINARY_MACROS = ["path/to/macro#MacroName", ...]

This is the Xcode-native path for cached or vendored macro binaries. 5

PackageInfoMapper: SPM Macro Targets#

PackageInfoMapper identifies SPM macro targets through isHostOnlyTarget() and macOSTargets(), then:

• Assigns them exclusively to the .mac destination 6
• Maps them to the .macro product type 7
• Ensures PackageSettings.baseSettings (e.g., MACOSX_DEPLOYMENT_TARGET) is merged into macro targets — a gap that had caused build failures before PR #11574 8

Exclusion from Framework Search Paths#

Macro executables are compile-time tools — they are never linked into a final binary. FrameworkSearchPathsGraphMapper must therefore exclude them when computing FRAMEWORK_SEARCH_PATHS, OTHER_CFLAGS, and related settings.

The exclusion is achieved at the graph traversal layer, before the mapper runs:

1. searchablePathDependencies (called at line 71 of FrameworkSearchPathsGraphMapper) delegates to linkableDependencies and related helpers, all of which use isDependencyPrecompiledMacro as a skip predicate.

2. isDependencyPrecompiledMacro 9 returns true for .macro nodes, causing them to be skipped in every filterDependencies traversal. It is used as a skip filter in:

   • embeddableFrameworks — skips macro nodes when collecting dynamically-embedded frameworks
   • transitiveStaticDependencies — skips macro nodes when collecting static products to link

3. precompiledPath is nil for .macro 2. FrameworkSearchPathsGraphMapper derives search paths by calling .compactMap(\.precompiledPath) on the dependency set 10, so .macro references automatically produce no path and contribute nothing to FRAMEWORK_SEARCH_PATHS.

The net result: macro references flow through only the SWIFT_LOAD_BINARY_MACROS / SWIFT_IMPLEMENTS_MACROS_FOR_MODULE_NAMES channel, not through any linker search path setting.

Key Files#