XCFramework: mi ez, bináris szállítási formátum és alkalmazás

Mi az XCFramework?

XCFramework — bináris könyvtárak és keretrendszerek csomagolási formátuma, amelyet az Apple a WWDC 2019-en mutatott be. A fő cél egy olyan bundle létrehozása, amely a könyvtár lefordított verzióit tartalmazza az összes célplatformhoz és architektúrához.

Az XCFramework megjelenése előtt a fejlesztők .framework-ot használtak fat binary-vel, amely több architektúrát egyesített a lipo segédprogramon keresztül. Ez a megközelítés problémákat okozott: a projekt szimulátorra történő fordításakor a fat binary tartalmazta a szimulátor és az eszköz architektúráját is, ami hibákhoz vezetett a build App Store-ba történő elküldésekor. A fejlesztőknek Run Script fázisokat kellett írniuk a szükségtelen architektúrák eltávolításához.

Az Apple Developer Documentation (2024) szerint az XCFramework támogatja az Apple ökoszisztéma összes platformját: iOS, iPadOS, macOS, tvOS, watchOS, visionOS és katalizátor alkalmazások. Minden platform külön szeletet kap a csomagon belül, ami kiküszöböli az architektúra-ütközéseket és egyszerűsíti az SDK-k terjesztését.

Mikor van szükség XCFramework-re?

XCFramework három fő forgatókönyvben alkalmazható: zárt SDK-k szállítása harmadik fél fejlesztőinek, natív modulok terjesztése Flutter és React Native számára, valamint előzetes fordítást igénylő könyvtárak publikálása. A formátum kötelező az Apple ökoszisztémában publikált összes új SDK számára.

A fejlesztők az XCFramework-ot választják, amikor a forráskód nem hozható nyilvánosságra, amikor a könyvtár szabadalmaztatott algoritmusokat használ, vagy amikor licencvédelem szükséges. Ellentétben a Swift Package Managerrel, amely forráskóddal dolgozik, az XCFramework már lefordított bináris fájlokat szállít.

Hogyan oldja meg az XCFramework a fat binary problémát?

A fat binary probléma az volt, hogy az univerzális bináris fájl több architektúrát tartalmazott egyetlen Mach-O fájlban. Az alkalmazás szimulátorra történő fordításakor az Xcode belefoglalta a binárisba az eszköz arm64 architektúráját és a szimulátor x86_64 architektúráját — az App Store csak az eszköz architektúráját fogadta el.

A hagyományos megoldás magában foglalta egy Run Script fázis hozzáadását lipo hívással a szimulátor architektúrák eltávolításához a végső buildből. Ez a megközelítés törékeny volt és elromlott az Xcode frissítésekkor vagy új architektúrák hozzáadásakor (pl. arm64 a szimulátorhoz Apple Silicon-on).

A Swift.org (2023) szerint a Swift Package Manager csapata kezdetben ebbe a problémába ütközött a bináris függőségek támogatásának kísérlete során. Az XCFramework formátum szinten oldotta meg: minden szelet egy külön mappa Info.plist fájllal, amely leírja a célplatformot és architektúrát. Az Xcode automatikusan kiválasztja a megfelelő szeletet a fordítás során, nem igényel utófeldolgozást.

A külön szeletekkel történő megközelítés előnyei

Minden szelet az XCFramework-ben csak egy platform és architektúra kombinációt tartalmaz. Például az ios-arm64 csak iOS eszközökhöz tartalmaz binárist, az ios-x86_64-simulator pedig csak az Intel Mac szimulátorhoz. Az Xcode automatikusan kiválasztja a megfelelő szeletet, kiküszöbölve az architektúra-eltávolító szkriptek szükségességét és csökkentve a fordítási hibák kockázatát.

Az ios-arm64-x86_64-simulator szelet az Apple Silicon Mac támogatásához jött létre. Korábban a szimulátorhoz külön bináris kellett az arm64 (Apple Silicon) és x86_64 (Intel) számára. Az XCFramework engedélyezi a fat binary-t egyetlen szeleten belül a szimulátor számára — ez az egyetlen kivétel, amikor a fat binary indokolt.

Az XCFramework csomag szerkezete

Az XCFramework csomag egy .xcframework kiterjesztésű könyvtár, amely a legfelső szinten Info.plist fájlt és bináris szeletekkel rendelkező mappákat tartalmaz. Minden szelet egy .framework vagy .a könyvtárat tartalmaz egy adott platformhoz.

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

A csomag Info.plist fájlja tartalmazza az AvailableLibraries kulcsot, amely felsorolja a LibraryIdentifier, LibraryPath és SupportedPlatform azonosítókat minden szelethez. Az Xcode ezt a fájlt olvassa be az XCFramework projekthez adásakor, és automatikusan konfigurálja a keresési útvonalakat és az Embed Frameworks fázist.

Minden szelet egy teljes értékű .framework vagy statikus könyvtár saját Info.plist fájllal. Ez lehetővé teszi az XCFramework számára, hogy vegyes típusokat támogasson: statikus könyvtárakat egyes platformokhoz és dinamikus keretrendszereket másokhoz, bár a gyakorlatban gyakrabban használnak egy típust az összes szelethez.

XCFramework létrehozása parancssorból

Az XCFramework létrehozása az xcodebuild -create-xcframework parancson keresztül történik. A parancs már lefordított .framework vagy .a könyvtárakat fogad el minden platformhoz, és egyesíti őket egyetlen csomagba.

A folyamat két lépésből áll: először a bináris fájlok lefordításra kerülnek minden célplatformhoz, majd becsomagolásra kerülnek XCFramework-be. A fordításhoz szabványos Xcode destination flag-eket használnak.

# 1. lépés: keretrendszerek felépítése minden platformhoz
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"

# 2. lépés: XCFramework létrehozása
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

A -create-xcframework flag az Xcode 11-ben jelent meg. A parancs automatikusan létrehozza a megfelelő könyvtárszerkezetet és generálja az Info.plist fájlt az összes platform leírásával. Ha az egyik .framework sérült vagy rossz architektúrával lett lefordítva, az xcodebuild hibát ad az érvényesítési szakaszban.

Automatizálás fordítási szkriptekkel

A CI/CD számára egy shell szkriptet használnak, amely automatizálja a fordítást az összes platformra és az XCFramework létrehozását. Népszerű megközelítés egy wrapper Makefile vagy Fastlane lane formájában, a scheme és output path paraméterezésével.

# build_xcframework.sh — automatizálási szkript
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"

Egy ilyen szkript a CI pipeline-ban (GitHub Actions, Bitrise, Jenkins) fut a tesztek lefutása után. Az eredményül kapott XCFramework archiválásra kerül és release artefaktumként feltöltésre kerül, vagy függőségkezelőn, például CocoaPods-on keresztül publikálásra kerül a pod spec segítségével.

XCFramework csatlakoztatása Xcode projektben

Az XCFramework csatlakoztatása Xcode projektben nem igényli a keresési útvonalak kézi konfigurálását. Elég a .xcframework fájlt a target General beállításainál a Frameworks, Libraries, and Embedded Content szakaszba húzni.

A .framework-tól eltérően az XCFramework nem igényel Run Script fázis hozzáadását a szimulátor architektúrák eltávolításához. Az Xcode automatikusan meghatározza a rendelkezésre álló szeleteket, és csak a jelenlegi fordítási sémához szükségeseket tartalmazza. Fizikai eszközhöz az ios-arm64 szelet használatos, szimulátorhoz — ios-arm64-x86_64-simulator vagy ios-x86_64-simulator.

import MyLibrary

func processData() {
    // Az XCFramework a megfelelő szeletet oldja fel fordítási időben
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

A CocoaPods esetében az integráció podspec-en keresztül történik a vendored_frameworks és a támogatott platformok listájának megadásával. A függőségkezelő automatikusan meghatározza, hogy mely szeletekre van szükség a projekthez. Számos kereskedelmi SDK — Firebase, Adjust, AppsFlyer — áttért az XCFramework-re a telepítés egyszerűsítése érdekében.

XCFramework és Swift Package Manager összehasonlítása

Swift Package Manager és XCFramework nem versenyeznek, hanem kiegészítik egymást. Az SPM forráskóddal dolgozik, és minden projektfordításkor lefordítja a függőségeket. Az XCFramework kész bináris fájlokat biztosít, nem igényel fordítást a fogyasztó oldalán.

• XCFramework — bináris szállítás, forráskód védelem, az összes Apple platform támogatása egy csomagban
• SPM — nyílt forráskóddal való munka, ellenőrizhetőség, automatikus fordítás a célplatformra
• SPM bináris függőségei az XCFramework-ot használják csomagolási formátumként, egyesítve mindkét megközelítést

A Swift Package Manager 5.3 kiadásával az Apple hozzáadta a bináris függőségek támogatását — most az SPM betöltheti az XCFramework-ot távoli függőségként. A Package.swift megadja a bináris artefaktum URL-jét és annak ellenőrző összegét a hitelesítéshez.

A Swift Package Manager documentation (2024) szerint a bináris függőségek olyan SDK-khoz ajánlottak, amelyek nem fedik fel a forráskódot, vagy olyan könyvtárakhoz, amelyek fordítása aránytalanul sok időt vesz igénybe. Nyílt forráskódú projektek esetén a forráskóddal történő szállítás SPM-en keresztül előnyösebb.