XCFramework: vad är det, binärt leveransformat och tillämpning

Vad är XCFramework?

XCFramework — ett format för paketering av binära bibliotek och ramverk, introducerat av Apple på WWDC 2019. Huvudmålet är att skapa en bundle som innehåller kompilerade versioner av biblioteket för alla målplattformar och arkitekturer.

Fre XCFramework kom använde utvecklare .framework med fat binary, som kombinerade flera arkitekturer via verktyget lipo. Denna metod skapade problem: vid kompilering av projektet för simulatorn innehöll fat binary både simulatorns och enhetens arkitektur, vilket ledde till fel vid sändning av bygget till App Store. Utvecklare var tvungna att skriva Run Script-faser för att ta bort onödiga arkitekturer.

Enligt Apple Developer Documentation (2024) stöder XCFramework alla plattformar i Apples ekosystem: iOS, iPadOS, macOS, tvOS, watchOS, visionOS och katalysatorapplikationer. Varje plattform får en separat sektion i paketet, vilket eliminerar arkitekturkonflikter och förenklar distributionen av SDK.

När behövs XCFramework?

XCFramework används i tre huvudscenarier: leverans av stängda SDK till tredjepartsutvecklare, distribution av inbyggda moduler för Flutter och React Native, och publicering av bibliotek som kräver förkompilering. Formatet är obligatoriskt för alla nya SDK som publiceras i Apples ekosystem.

Utvecklare väljer XCFramework när källkoden inte kan avslöjas, när biblioteket använder proprietära algoritmer eller när licensskydd krävs. Till skillnad från Swift Package Manager som arbetar med källkod, levererar XCFramework redan kompilerade binära filer.

Hur löser XCFramework problemet med fat binary?

Problemet med fat binary var att den universella binären innehöll flera arkitekturer i en enda Mach-O-fil. Vid kompilering av applikationen för simulatorn inkluderade Xcode enhetens arm64-arkitektur och simulators x86_64-arkitektur i binären — App Store accepterade endast enhetens arkitektur.

Den traditionella lösningen innebar att lägga till en Run Script-fas med anrop av lipo för att ta bort simulatorarkitekturer från det slutliga bygget. Denna metod var skör och gick sönder vid Xcode-uppdateringar eller vid tillägg av nya arkitekturer (t.ex. arm64 för simulator på Apple Silicon).

Enligt Swift.org (2023) stötte Swift Package Manager-teamet initialt på detta problem vid försök att stödja binära beroenden. XCFramework löste det på formatnivå: varje sektion är en separat mapp med Info.plist som beskriver målplattformen och arkitekturen. Xcode väljer automatiskt rätt sektion vid kompilering, utan att kräva efterbearbetning.

Fördelar med metoden med separata sektioner

Varje sektion i XCFramework innehåller endast en kombination av plattform och arkitektur. Till exempel innehåller ios-arm64 binär endast för iOS-enheter, och ios-x86_64-simulator endast för Intel Mac-simulatorn. Xcode väljer automatiskt rätt sektion, vilket eliminerar behovet av skript för borttagning av arkitekturer och minskar risken för kompileringsfel.

Sektionen ios-arm64-x86_64-simulator skapades för stöd av Apple Silicon Mac. Tidigare krävde simulatorn en separat binär för arm64 (Apple Silicon) och x86_64 (Intel). XCFramework tillåter fat binary inom en enda sektion för simulatorn — detta är det enda undantaget där fat binary är motiverat.

Struktur för XCFramework-paketet

XCFramework-paketet är en katalog med tillägget .xcframework, som innehåller Info.plist på den högsta nivån och mappar med binära sektioner. Varje sektion innehåller ett .framework eller .a-bibliotek för en specifik 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

Paketets Info.plist innehåller nyckeln AvailableLibraries, som listar identifierarna LibraryIdentifier, LibraryPath och SupportedPlatform för varje sektion. Xcode läser denna fil när XCFramework läggs till i projektet och konfigurerar automatiskt sökvägar och Embed Frameworks-fasen.

Varje sektion är ett fullfjädrat .framework eller statiskt bibliotek med egen Info.plist. Detta gör att XCFramework kan stödja blandade typer: statiska bibliotek för vissa plattformar och dynamiska ramverk för andra, även om en typ i praktiken används oftare för alla sektioner.

Skapa XCFramework från kommandoraden

Skapande av XCFramework görs via xcodebuild -create-xcframework. Kommandot tar emot redan kompilerade .framework eller .a-bibliotek för varje plattform och kombinerar dem i ett enda paket.

Processen består av två steg: först kompileras binärerna för varje målplattform, sedan paketeras de i XCFramework. För kompilering används standard destination-flaggor i Xcode.

# Steg 1: bygg ramverk för varje plattform
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"

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

Flaggan -create-xcframework dök upp i Xcode 11. Kommandot skapar automatiskt rätt katalogstruktur och genererar Info.plist med beskrivning av alla plattformar. Om ett av .framework är skadat eller kompilerat med fel arkitektur ger xcodebuild ett fel i valideringsfasen.

Automatisering genom kompileringsskript

För CI/CD används ett shell-skript som automatiserar kompilering för alla plattformar och skapande av XCFramework. En populär metod är en wrapper i form av en Makefile eller Fastlane-lane med parameterisering av scheme och output path.

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

Ett sådant skript körs i CI-pipelinen (GitHub Actions, Bitrise, Jenkins) efter att testerna har körts. Det resulterande XCFramework arkiveras och laddas upp som en release-artefakt eller publiceras via en beroendehanterare som CocoaPods med hjälp av pod spec.

Ansluta XCFramework i ett Xcode-projekt

Att ansluta XCFramework i ett Xcode-projekt kräver ingen manuell konfiguration av sökvägar. Det räcker att dra .xcframework till sektionen Frameworks, Libraries, and Embedded Content i targetets General-inställningar.

Till skillnad från .framework kräver XCFramework ingen tilläggning av Run Script-fas för borttagning av simulatorarkitekturer. Xcode bestämmer automatiskt tillgängliga sektioner och inkluderar endast de som behövs för det aktuella kompileringsschemat. För fysisk enhet används sektionen ios-arm64, för simulatorn — ios-arm64-x86_64-simulator eller ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework löser rätt sektion vid kompileringstid
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

För CocoaPods sker integration via podspec med angivande av vendored_frameworks och lista över stödda plattformar. Beroendehanteraren bestämmer automatiskt vilka sektioner som behövs för projektet. Många kommersiella SDK — Firebase, Adjust, AppsFlyer — har gått över till XCFramework för att förenkla installationen.

Jämförelse mellan XCFramework och Swift Package Manager

Swift Package Manager och XCFramework konkurrerar inte utan kompletterar varandra. SPM arbetar med källkod och kompilerar beroenden vid varje projektkompilering. XCFramework tillhandahåller färdiga binärer utan att kräva kompilering hos konsumenten.

• XCFramework — binär leverans, källkodsskydd, stöd för alla Apple-plattformar i ett paket
• SPM — arbete med öppen källkod, inspektionsmöjlighet, automatisk kompilering för målplattform
• Binära SPM-beroenden använder XCFramework som paketeringsformat och kombinerar båda metoderna

Med lanseringen av Swift Package Manager 5.3 lade Apple till stöd för binära beroenden — nu kan SPM ladda XCFramework som ett fjärrberoende. Package.swift anger URL till den binära artefakten och dess kontrollsumma för verifiering.

Enligt Swift Package Manager documentation (2024) rekommenderas binära beroenden för SDK som inte avslöjar källkoden eller för bibliotek vars kompilering tar oproportionerligt lång tid. För open source-projekt föredras leverans med källkod via SPM.