XCFrameworks: One Bundle for Every Apple Platform

WHY IT EXISTS: Before XCFrameworks, iOS developers combined device and simulator binaries into a single fat framework using lipo. This broke when Apple Silicon Macs introduced arm64 simulator slices, because a single binary could not hold two different arm64 variants built for different platforms. XCFrameworks were created to package multiple platform-specific frameworks into one distributable bundle, eliminating slice collisions and simplifying binary distribution across the entire Apple ecosystem.

THE MENTAL MODEL: Treat an XCFramework like a shipping container with separate crates for each destination. Instead of stuffing everything into one box that customs might reject, each platform gets its own clearly labeled crate. Xcode acts as the delivery agent, opening only the crate that matches the current build destination and ignoring the rest.

HOW IT WORKS: An XCFramework is a bundle with the .xcframework extension. It contains a top-level Info.plist and platform-specific subfolders, each holding a complete .framework binary built for a specific architecture and platform combination such as iOS device, iOS simulator, macOS, tvOS, watchOS, or visionOS. At build time, Xcode inspects the bundle, matches the active destination to the correct slice, and links only that binary. Swift module interfaces and module maps live inside each slice, so the compiler sees a uniform API and symbol set regardless of platform.

WHEN TO USE IT: Reach for an XCFramework when you need to distribute a compiled library without source code, support multiple Apple platforms from a single artifact, or ship a framework that contains resources, C++ wrappers, or binary dependencies that Swift Package Manager cannot easily consume from source. They are the standard format for third-party SDK vendors and enterprise teams sharing proprietary code.

WHEN NOT TO USE IT: Avoid XCFrameworks for code you own and modify daily within the same workspace. Building from source yields faster incremental compiles, better debugging, and smaller Git history. They are also overkill if you only build for exactly one platform and architecture, where a plain framework or static library adds no complexity and integrates more naturally.

ONE CANONICAL EXAMPLE: Imagine a mapping SDK vendor shipping GeoMap.xcframework. The bundle contains distinct folders for iOS_arm64, iOS_simulator_arm64_x86_64, and macOS_arm64_x86_64. A developer drags the single XCFramework into an Xcode project, writes import GeoMap, and builds for an iPhone, an Apple Silicon simulator, or a native Mac app without running lipo or maintaining separate binaries.