XCFramework: wat is het, binair leveringsformaat en toepassing

Wat is XCFramework?

XCFramework — een formaat voor het verpakken van binaire bibliotheken en frameworks, geïntroduceerd door Apple op WWDC 2019. Het hoofddoel is het maken van één bundle die gecompileerde versies van de bibliotheek bevat voor alle doelplatforms en architecturen.

Vóór de komst van XCFramework gebruikten ontwikkelaars .framework met fat binary, die meerdere architecturen combineerde via het hulpprogramma lipo. Deze benadering veroorzaakte problemen: bij het compileren van een project voor de simulator bevatte de fat binary zowel de simulator- als de apparaatarchitectuur, wat leidde tot fouten bij het verzenden van de build naar de App Store. Ontwikkelaars moesten Run Script-fasen schrijven om onnodige architecturen te verwijderen.

Volgens Apple Developer Documentation (2024) ondersteunt XCFramework alle platforms van het Apple-ecosysteem: iOS, iPadOS, macOS, tvOS, watchOS, visionOS en katalysator-applicaties. Elk platform krijgt een aparte slice binnen het pakket, wat architectuurconflicten elimineert en de distributie van SDK's vereenvoudigt.

Wanneer is XCFramework nodig?

XCFramework wordt toegepast in drie hoofdscenario's: levering van gesloten SDK's aan externe ontwikkelaars, distributie van native modules voor Flutter en React Native, en publicatie van bibliotheken die voorafgaande compilatie vereisen. Het formaat is verplicht voor alle nieuwe SDK's die in het Apple-ecosysteem worden gepubliceerd.

Ontwikkelaars kiezen voor XCFramework wanneer de broncode niet kan worden onthuld, wanneer de bibliotheek propriëtaire algoritmen gebruikt of wanneer licentiebatescherming vereist is. In tegenstelling tot Swift Package Manager, die met broncode werkt, levert XCFramework reeds gecompileerde binaire bestanden.

Hoe lost XCFramework het fat binary-probleem op?

Het fat binary probleem was dat het universele binaire bestand meerdere architecturen in één Mach-O-bestand bevatte. Bij het compileren van een applicatie voor de simulator voegde Xcode de arm64-architectuur van het apparaat en de x86_64-architectuur van de simulator toe aan het binaire bestand — de App Store accepteerde alleen de apparaatarchitectuur.

De traditionele oplossing omvatte het toevoegen van een Run Script-fase met een aanroep van lipo om simulatorarchitecturen uit de uiteindelijke build te verwijderen. Deze benadering was fragiel en brak bij Xcode-updates of bij het toevoegen van nieuwe architecturen (bijv. arm64 voor simulator op Apple Silicon).

Volgens Swift.org (2023) stuitte het Swift Package Manager-team aanvankelijk op dit probleem bij het ondersteunen van binaire afhankelijkheden. XCFramework loste het op formatniveau op: elke slice is een aparte map met Info.plist die het doelplatform en de architectuur beschrijft. Xcode selecteert automatisch de juiste slice tijdens het compileren, zonder nabewerking.

Voordelen van de benadering met aparte slices

Elke slice in XCFramework bevat slechts één combinatie van platform en architectuur. Bijvoorbeeld ios-arm64 bevat een binair bestand alleen voor iOS-apparaten, en ios-x86_64-simulator alleen voor de Intel Mac-simulator. Xcode selecteert automatisch de juiste slice, waardoor scripts voor het verwijderen van architecturen overbodig worden en het risico op compilatiefouten afneemt.

De slice ios-arm64-x86_64-simulator is ontstaan voor ondersteuning van Apple Silicon Mac. Voorheen was voor de simulator een apart binair bestand nodig voor arm64 (Apple Silicon) en x86_64 (Intel). XCFramework staat fat binary toe binnen één slice voor de simulator — dit is de enige uitzondering waarbij fat binary gerechtvaardigd is.

Structuur van het XCFramework-pakket

Het XCFramework pakket is een directory met de extensie .xcframework, met Info.plist op het hoogste niveau en mappen met binaire slices. Elke slice bevat een .framework of .a bibliotheek voor een specifiek platform.

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

De Info.plist van het pakket bevat de sleutel AvailableLibraries, die de identifiers LibraryIdentifier, LibraryPath en SupportedPlatform voor elke slice opsomt. Xcode leest dit bestand bij het toevoegen van XCFramework aan een project en configureert automatisch de zoekpaden en de Embed Frameworks-fase.

Elke slice is een volwaardig .framework of statische bibliotheek met een eigen Info.plist. Hierdoor kan XCFramework gemengde typen ondersteunen: statische bibliotheken voor sommige platforms en dynamische frameworks voor andere, hoewel in de praktijk vaker één type voor alle slices wordt gebruikt.

XCFramework maken vanaf de opdrachtregel

Het maken van XCFramework gebeurt via xcodebuild -create-xcframework. De opdracht accepteert reeds gecompileerde .framework of .a bibliotheken voor elk platform en combineert ze in één pakket.

Het proces bestaat uit twee stappen: eerst worden de binaire bestanden gecompileerd voor elk doelplatform, daarna worden ze verpakt in XCFramework. Voor het compileren worden standaard Xcode destination-vlaggen gebruikt.

# Stap 1: bouw frameworks voor elk 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"

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

De vlag -create-xcframework verscheen in Xcode 11. De opdracht maakt automatisch de juiste directorystructuur en genereert Info.plist met een beschrijving van alle platforms. Als een van de .framework bestanden beschadigd is of met een verkeerde architectuur is gecompileerd, geeft xcodebuild een fout in de validatiefase.

Automatisering via compilatiescripts

Voor CI/CD wordt een shell-script gebruikt dat het compileren voor alle platforms en het maken van XCFramework automatiseert. Een populaire benadering is een wrapper in de vorm van een Makefile of Fastlane-lane met parameterisatie van scheme en output path.

# build_xcframework.sh — automatiseringsscript
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"

Zo'n script wordt uitgevoerd in de CI-pipeline (GitHub Actions, Bitrise, Jenkins) na het doorlopen van tests. Het resulterende XCFramework wordt gearchiveerd en geüpload als release-artefact of gepubliceerd via een afhankelijkheidsbeheerder zoals CocoaPods met behulp van pod spec.

XCFramework aansluiten in een Xcode-project

Het aansluiten van XCFramework in een Xcode-project vereist geen handmatige configuratie van zoekpaden. Het volstaat om .xcframework naar de sectie Frameworks, Libraries, and Embedded Content in de General-instellingen van het target te slepen.

In tegenstelling tot .framework vereist XCFramework geen toevoeging van een Run Script-fase voor het verwijderen van simulatorarchitecturen. Xcode bepaalt automatisch de beschikbare slices en voegt alleen de nodige toe voor het huidige compilatieschema. Voor een fysiek apparaat wordt de slice ios-arm64 gebruikt, voor de simulator — ios-arm64-x86_64-simulator of ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework lost de juiste slice op tijdens het compileren
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Voor CocoaPods vindt integratie plaats via podspec met vermelding van vendored_frameworks en de lijst met ondersteunde platforms. De afhankelijkheidsbeheerder bepaalt automatisch welke slices nodig zijn voor het project. Veel commerciële SDK's — Firebase, Adjust, AppsFlyer — zijn overgestapt op XCFramework om de installatie te vereenvoudigen.

Vergelijking van XCFramework en Swift Package Manager

Swift Package Manager en XCFramework concurreren niet, maar vullen elkaar aan. SPM werkt met broncode en compileert afhankelijkheden bij elke compilatie van het project. XCFramework bied kant-en-klare binaire bestanden aan zonder compilatie aan de kant van de consument.

• XCFramework — binaire levering, broncodebescherming, ondersteuning voor alle Apple-platforms in één pakket
• SPM — werken met open broncode, inspectiemogelijkheid, automatische compilatie voor het doelplatform
• Binaire SPM-afhankelijkheden gebruiken XCFramework als verpakkingsformaat en combineren beide benaderingen

Met de release van Swift Package Manager 5.3 voegde Apple ondersteuning toe voor binaire afhankelijkheden — nu kan SPM XCFramework laden als een externe afhankelijkheid. Package.swift geeft de URL naar het binaire artefact en de controlesom voor verificatie.

Volgens Swift Package Manager documentation (2024) worden binaire afhankelijkheden aanbevolen voor SDK's die de broncode niet onthullen of voor bibliotheken waarvan de compilatie onevenredig veel tijd kost. Voor open-source projecten heeft levering met broncode via SPM de voorkeur.