XCFramework: Was es ist, binäres Distributionsformat und Anwendung

Was ist XCFramework?

XCFramework ist ein Verpackungsformat für binäre Bibliotheken und Frameworks, das von Apple auf der WWDC 2019 vorgestellt wurde. Das Hauptziel ist die Erstellung eines einzigen Bundles, das kompilierte Versionen einer Bibliothek für alle Zielplattformen und Architekturen enthält.

Vor XCFramework verwendeten Entwickler .framework mit Fat Binaries, die mehrere Architekturen über das Dienstprogramm lipo kombinierten. Dieser Ansatz verursachte Probleme: Beim Erstellen eines Projekts für den Simulator enthielt die Fat Binary sowohl die Simulator- als auch die Gerätearchitektur, was zu Fehlern beim Einreichen des Builds in den App Store führte. Entwickler mussten Run Script-Phasen schreiben, um unnötige Architekturen zu entfernen.

Laut Apple Developer Documentation (2024) unterstützt XCFramework alle Plattformen des Apple-Ökosystems: iOS, iPadOS, macOS, tvOS, watchOS, visionOS und Catalyst-Anwendungen. Jede Plattform erhält ein separates Slice innerhalb des Pakets, was Architekturkonflikte beseitigt und die SDK-Verteilung vereinfacht.

Wann wird XCFramework benötigt?

XCFramework wird in drei Hauptszenarien verwendet: Verteilung geschlossener SDKs an Drittanbieter, Verteilung nativer Module für Flutter und React Native sowie Veröffentlichung von Bibliotheken, die eine Vorkompilierung erfordern. Das Format ist für alle neuen SDKs, die im Apple-Ökosystem veröffentlicht werden, obligatorisch.

Entwickler wählen XCFramework, wenn Quellcode nicht offengelegt werden kann, wenn die Bibliothek proprietäre Algorithmen verwendet oder wenn Lizenzschutz erforderlich ist. Im Gegensatz zu Swift Package Manager, der mit Quellcode arbeitet, liefert XCFramework bereits kompilierte Binärdateien aus.

Wie löst XCFramework das Fat-Binary-Problem?

Das Fat-Binary-Problem bestand darin, dass eine universelle Binärdatei mehrere Architekturen in einer einzigen Mach-O-Datei enthielt. Beim Erstellen einer App für den Simulator fügte Xcode sowohl die Gerätearchitektur arm64 als auch die Simulatorarchitektur x86_64 hinzu — der App Store akzeptierte nur die Gerätearchitektur.

Die traditionelle Lösung bestand darin, eine Run Script-Phase hinzuzufügen, die lipo aufrief, um Simulatorarchitekturen aus dem endgültigen Build zu entfernen. Dieser Ansatz war zerbrechlich und brach bei Xcode-Updates oder beim Hinzufügen neuer Architekturen (z. B. arm64 für den Simulator auf Apple Silicon).

Laut Swift.org (2023) stieß das Swift Package Manager-Team zunächst auf dieses Problem, als es versuchte, binäre Abhängigkeiten zu unterstützen. XCFramework löste es auf Formatebene: Jedes Slice ist ein separater Ordner mit einer Info.plist, die die Zielplattform und Architektur beschreibt. Xcode wählt beim Build automatisch das erforderliche Slice aus, ohne dass eine Nachbearbeitung erforderlich ist.

Vorteile des Ansatzes mit separaten Slices

Jedes Slice in XCFramework enthält nur eine Plattform-Architektur-Kombination. Beispielsweise enthält ios-arm64 die Binärdatei nur für iOS-Geräte und ios-x86_64-simulator nur für den Intel Mac-Simulator. Xcode wählt automatisch das richtige Slice aus, wodurch die Notwendigkeit von Architekturentfernungsskripten entfällt und das Risiko von Build-Fehlern verringert wird.

Das Slice ios-arm64-x86_64-simulator wurde zur Unterstützung von Apple Silicon Macs eingeführt. Zuvor benötigte der Simulator separate Binärdateien für arm64 (Apple Silicon) und x86_64 (Intel). XCFramework erlaubt eine Fat Binary innerhalb eines einzelnen Simulator-Slices — dies ist die einzige Ausnahme, bei der eine Fat Binary gerechtfertigt ist.

Struktur eines XCFramework-Pakets

Ein XCFramework-Paket ist ein Verzeichnis mit der Erweiterung .xcframework, das eine Info.plist auf der obersten Ebene und Ordner mit binären Slices enthält. Jedes Slice enthält eine .framework- oder .a-Bibliothek für eine bestimmte Plattform.

MyLibrary.xcframework/
  Info.plist
  ios-arm64/
    MyLibrary.framework/
      Info.plist
      MyLibrary
  ios-x86_64-simulator/
    MyLibrary.framework/
      Info.plist
      MyLibrary
  macos-arm64-x86_64/
    MyLibrary.framework/
      Info.plist
      MyLibrary

Die Info.plist des Pakets enthält den Schlüssel AvailableLibraries, der LibraryIdentifier, LibraryPath und SupportedPlatform für jedes Slice auflistet. Xcode liest diese Datei beim Hinzufügen eines XCFrameworks zum Projekt und konfiguriert automatisch die Suchpfade und die Embed Frameworks-Phase.

Jedes Slice ist ein vollständiges .framework oder eine statische Bibliothek mit eigener Info.plist. Dadurch kann XCFramework gemischte Typen unterstützen: statische Bibliotheken für einige Plattformen und dynamische Frameworks für andere, obwohl in der Praxis ein Typ für alle Slices verwendet wird.

XCFramework von der Befehlszeile aus erstellen

Die Erstellung eines XCFrameworks erfolgt über xcodebuild -create-xcframework. Der Befehl nimmt bereits erstellte .framework- oder .a-Bibliotheken für jede Plattform entgegen und kombiniert sie zu einem einzigen Paket.

Der Prozess besteht aus zwei Schritten: Zuerst werden Binärdateien für jede Zielplattform erstellt, dann werden sie zu einem XCFramework verpackt. Für die Erstellung werden die standardmäßigen Xcode-Destination-Flags verwendet.

# Step 1: build frameworks for each platform
xcodebuild archive -scheme MyLibrary -destination "generic/platform=iOS Simulator"
xcodebuild archive -scheme MyLibrary -destination "generic/platform=iOS"
xcodebuild archive -scheme MyLibrary -destination "generic/platform=macOS"

# Step 2: create XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

Das Flag -create-xcframework wurde in Xcode 11 eingeführt. Der Befehl erstellt automatisch die richtige Verzeichnisstruktur und generiert eine Info.plist mit Beschreibungen aller Plattformen. Wenn eine der .framework-Dateien beschädigt oder mit der falschen Architektur erstellt wurde, gibt xcodebuild in der Validierungsphase einen Fehler aus.

Automatisierung durch Build-Skripte

Für CI/CD wird ein Shell-Skript verwendet, das das Erstellen für alle Plattformen und die Erstellung des XCFrameworks automatisiert. Ein beliebter Ansatz ist ein Wrapper in Form eines Makefiles oder einer Fastlane-Lane mit parametrisiertem Scheme und Ausgabepfad.

# build_xcframework.sh - automation script
set -e
SCHEME="MyLibrary"
OUTPUT="./build"

xcodebuild archive -scheme "$SCHEME" -sdk iphonesimulator -archivePath "$OUTPUT/sim.xcarchive"
xcodebuild archive -scheme "$SCHEME" -sdk iphoneos -archivePath "$OUTPUT/dev.xcarchive"
xcodebuild -create-xcframework -framework "$OUTPUT/dev.xcarchive/Products/Library/Frameworks/MyLibrary.framework" -framework "$OUTPUT/sim.xcarchive/Products/Library/Frameworks/MyLibrary.framework" -output "$OUTPUT/MyLibrary.xcframework"

Ein solches Skript wird in einer CI-Pipeline (GitHub Actions, Bitrise, Jenkins) nach bestandenen Tests ausgeführt. Das resultierende XCFramework wird archiviert und als Release-Artefakt hochgeladen oder über einen Abhängigkeitsmanager wie CocoaPods mit pod spec veröffentlicht.

XCFramework in ein Xcode-Projekt einbinden

Die Einbindung eines XCFrameworks in ein Xcode-Projekt erfordert keine manuelle Konfiguration der Suchpfade. Ziehen Sie einfach das .xcframework in den Abschnitt Frameworks, Libraries, and Embedded Content in den General-Einstellungen des Targets.

Im Gegensatz zu .framework erfordert XCFramework kein Hinzufügen einer Run Script-Phase zum Entfernen von Simulatorarchitekturen. Xcode ermittelt automatisch verfügbare Slices und fügt nur die für das aktuelle Build-Schema erforderlichen hinzu. Für ein physisches Gerät wird das Slice ios-arm64 verwendet, für den Simulator — ios-arm64-x86_64-simulator oder ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework resolves the correct slice at build time
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Für CocoaPods erfolgt die Integration über ein podspec mit vendored_frameworks und einer Liste unterstützter Plattformen. Der Abhängigkeitsmanager ermittelt automatisch, welche Slices für das Projekt benötigt werden. Viele kommerzielle SDKs — Firebase, Adjust, AppsFlyer — sind auf XCFramework umgestiegen, um die Installation zu vereinfachen.

Vergleich von XCFramework und Swift Package Manager

Swift Package Manager und XCFramework sind keine Konkurrenten, sondern ergänzen sich gegenseitig. SPM arbeitet mit Quellcode und erstellt Abhängigkeiten bei jedem Projekt-Build. XCFramework bietet fertige Binärdateien, ohne dass eine Kompilierung auf der Verbraucherseite erforderlich ist.

• XCFramework — binäre Verteilung, Quellcode-Schutz, Unterstützung aller Apple-Plattformen in einem Paket
• SPM — Arbeit mit offenem Quellcode, Überprüfbarkeit, automatischer Build für die Zielplattform
• Binäre SPM-Abhängigkeiten verwenden XCFramework als Verpackungsformat und kombinieren beide Ansätze

Mit der Veröffentlichung von Swift Package Manager 5.3 hat Apple die Unterstützung für binäre Abhängigkeiten hinzugefügt — jetzt kann SPM ein XCFramework als Remote-Abhängigkeit herunterladen. Package.swift gibt die URL des binären Artefakts und seine Prüfsumme zur Verifizierung an.

Laut Swift Package Manager-Dokumentation (2024) werden binäre Abhängigkeiten für SDKs empfohlen, die keinen Quellcode offenlegen, oder für Bibliotheken, deren Build-Zeit unverhältnismäßig lang ist. Für Open-Source-Projekte wird die Quellcode-Verteilung über SPM bevorzugt.