Framework Bundle Structure#

Tuist controls how the Modules/ directory is laid out inside .framework bundles through its graph mapping pipeline — specifically ModuleMapMapper, a GraphMapping pass inside TuistGenerator.

Canonical Path: Top-Level Modules/, Not Versioned#

When a framework target has a MODULEMAP_FILE build setting, ModuleMapMapper injects a post-build script that writes the module map to the top-level Modules/ directory of the bundle 1:

$TARGET_BUILD_DIR/$WRAPPER_NAME/Modules/module.modulemap

There is no Versions/A/Modules/ hierarchy. This is a deliberate design choice: Tuist mirrors the convention used by swift-build (SWBTaskConstruction), which models framework module maps at Modules/module.modulemap for its ExtractAPI pass 2. Aligning with this canonical path ensures that generated Xcode projects are compatible with ExtractAPI and related Apple toolchain workflows.

The script uses mkdir -p + cp -f rather than a plain copy because Xcode's compilation-caching (CAS) can materialise the destination as a read-only file; cp -f forces an overwrite 3.

Why the Modules/ Directory Is Stripped During Embedding#

The embed-frameworks script generated by Tuist explicitly excludes Modules/ when rsync-ing frameworks into the app bundle 4. This prevents non-portable paths (which may be absolute paths from the developer's machine) from leaking into the distributed product. If a module map is needed at runtime, it must be re-added by the framework consumer's build system, not carried inside the embedded copy.

When the Post-Build Script Is Added#

The "Copy Module Map" script is added only when both conditions hold 5:

1. The target's MODULEMAP_FILE setting resolves to a path.
2. The target's product type is .framework (not .staticFramework, not .xcframework).

Static frameworks (.staticFramework) are handled differently: rather than embedding a module map into a bundle, the mapper propagates -fmodule-map-file flags transitively to consuming targets.

XCFramework Bundles#

XCFrameworks are loaded and processed separately from regular frameworks. Their Info.plist is parsed to extract metadata including moduleMaps and swiftModules 6. For XCFrameworks that contain static libraries, the StaticXCFrameworkModuleMapGraphMapper handles additional rewriting — it distinguishes between flat layouts (headers next to the module map, passed via -fmodule-map-file) and nested layouts (headers in a Headers/<ModuleName>/ subdirectory, where clang discovers the module map automatically via header search paths) 7 8.

Key Source Files#