Structuring XCFrameworks for Cross-Platform Swift

In the era of visionOS and Multiplatform apps, the single-platform framework is a relic. Senior engineers must now design XCFrameworks that provide a unified API while handling platform-specific constraints like camera access on iOS vs. menu bars on macOS.

The Hook: The Fat Binary Failure

Old-school “Fat Binaries” (using lipo) are no longer sufficient. They fail to handle the overlap between simulator architectures (x86_64) and Apple Silicon (arm64), and they cannot bundle platform-specific variants of the same dependency.

The “Why”: Resilient Distribution

XCFramework is the only distribution format that supports Library Evolution, allowing your framework to remain compatible with future versions of the Swift compiler without needing a recompile.

The Implementation: The Build Pipeline

A robust XCFramework requires a multi-step build process that archives each platform individually before bundling them.

# 1. Archive for iOS
xcodebuild archive -scheme MySDK -destination "generic/platform=iOS" -archivePath "./archives/ios.xcarchive" SKIP_INSTALL=NO

# 2. Archive for iOS Simulator
xcodebuild archive -scheme MySDK -destination "generic/platform=iOS Simulator" -archivePath "./archives/ios_sim.xcarchive" SKIP_INSTALL=NO

# 3. Create the XCFramework
xcodebuild -create-xcframework \
    -framework ./archives/ios.xcarchive/Products/Library/Frameworks/MySDK.framework \
    -framework ./archives/ios_sim.xcarchive/Products/Library/Frameworks/MySDK.framework \
    -output ./MySDK.xcframework

Inside your code, use Conditional Compilation to ensure your public API remains clean across platforms:

public struct DeviceCapabilities {
    public static var hasLiDAR: Bool {
        #if os(iOS) || os(visionOS)
        return true // Logic for LiDAR detection
        #else
        return false
        #endif
    }
}

The Verdict: Professionalism in Packaging

• Pros: Full support for Apple Silicon; avoids lipo hacks; simplifies distribution via Swift Package Manager.
• Cons: Complex build scripts; larger initial file size for the bundled framework.
• When to use: Any library intended for multi-platform use or third-party distribution.

Internal Connectivity

• Foundation: Optimizing Swift Compilation: Module Interfaces
• Next Step: Roadmap Stage 9: Senior System Design

External Resources

• Apple: Distributing Binary Frameworks
• WWDC: Binary Frameworks in Swift