XCFramework: ce este, format de livrare binară și aplicare

Ce este XCFramework?

XCFramework — un format de ambalare a bibliotecilor binare și framework-urilor, prezentat de Apple la WWDC 2019. Scopul principal este crearea unui singur bundle care conține versiunile compilate ale bibliotecii pentru toate platformele și arhitecturile țintă.

Înainte de apariția XCFramework, dezvoltatorii foloseau .framework cu fat binary, care combina mai multe arhitecturi prin utilitarul lipo. Această abordare crea probleme: la compilarea proiectului pentru simulator, fat binary conținea atât arhitectura simulatorului, cât și a dispozitivului, ceea ce ducea la erori la trimiterea build-ului în App Store. Dezvoltatorii trebuiau să scrie faze Run Script pentru eliminarea arhitecturilor inutile.

Conform Apple Developer Documentation (2024), XCFramework acceptă toate platformele ecosistemului Apple: iOS, iPadOS, macOS, tvOS, watchOS, visionOS și aplicații catalizator. Fiecare platformă primește un segment separat în interiorul pachetului, ceea ce elimină conflictele de arhitectură și simplifică distribuția SDK-urilor.

Când este necesar XCFramework?

XCFramework se aplică în trei scenarii principale: livrarea SDK-urilor închise dezvoltatorilor terți, distribuirea modulelor native pentru Flutter și React Native și publicarea bibliotecilor care necesită compilare prealabilă. Formatul este obligatoriu pentru toate SDK-urile noi publicate în ecosistemul Apple.

Dezvoltatorii aleg XCFramework atunci când codul sursă nu poate fi dezvăluit, când biblioteca utilizează algoritmi proprietari sau când este necesară protecția prin licență. Spre deosebire de Swift Package Manager, care lucrează cu cod sursă, XCFramework livrează fișiere binare deja compilate.

Cum rezolvă XCFramework problema fat binary?

Problema fat binary consta în faptul că binarul universal conținea mai multe arhitecturi într-un singur fișier Mach-O. La compilarea aplicației pentru simulator, Xcode includea în binar arhitectura arm64 a dispozitivului și x86_64 a simulatorului — App Store accepta doar arhitectura dispozitivului.

Soluția tradițională includea adăugarea unei faze Run Script cu apelarea lipo pentru eliminarea arhitecturilor de simulator din build-ul final. Această abordare era fragilă și se strica la actualizările Xcode sau la adăugarea de noi arhitecturi (de exemplu, arm64 pentru simulator pe Apple Silicon).

Conform Swift.org (2023), echipa Swift Package Manager a întâmpinat inițial această problemă când a încercat să accepte dependențe binare. XCFramework a rezolvat-o la nivel de format: fiecare segment este un folder separat cu Info.plist care descrie platforma și arhitectura țintă. Xcode selectează automat segmentul potrivit la compilare, fără a necesita post-procesare.

Avantajele abordării cu segmente separate

Fiecare segment în XCFramework conține doar o singură combinație de platformă și arhitectură. De exemplu, ios-arm64 conține binar doar pentru dispozitive iOS, iar ios-x86_64-simulator — doar pentru simulatorul Intel Mac. Xcode selectează automat segmentul corect, eliminând necesitatea scripturilor de eliminare a arhitecturilor și reducând riscul erorilor de compilare.

Segmentul ios-arm64-x86_64-simulator a apărut pentru suportul Apple Silicon Mac. Anterior, pentru simulator era necesar un binar separat pentru arm64 (Apple Silicon) și x86_64 (Intel). XCFramework permite fat binary în interiorul unui singur segment pentru simulator — aceasta este singura excepție când fat binary este justificat.

Structura pachetului XCFramework

Pachetul XCFramework este un director cu extensia .xcframework, care conține Info.plist la nivel superior și foldere cu segmente binare. Fiecare segment include o bibliotecă .framework sau .a pentru o platformă specifică.

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

Info.plist al pachetului conține cheia AvailableLibraries, care enumeră identificatorii LibraryIdentifier, LibraryPath și SupportedPlatform pentru fiecare segment. Xcode citește acest fișier la adăugarea XCFramework în proiect și configurează automat căile de căutare și faza Embed Frameworks.

Fiecare segment reprezintă un .framework complet sau o bibliotecă statică cu propriul Info.plist. Acest lucru permite XCFramework să accepte tipuri mixte: biblioteci statice pentru unele platforme și framework-uri dinamice pentru altele, deși în practică se folosește mai des un singur tip pentru toate segmentele.

Crearea XCFramework din linia de comandă

Crearea XCFramework se realizează prin xcodebuild -create-xcframework. Comanda primește bibliotecile .framework sau .a deja compilate pentru fiecare platformă și le combină într-un singur pachet.

Procesul constă în doi pași: mai întâi se compilează binarele pentru fiecare platformă țintă, apoi se ambalează în XCFramework. Pentru compilare se folosesc flagurile standard destination ale Xcode.

# Pasul 1: construiți framework-uri pentru fiecare 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"

# Pasul 2: creați XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

Flagul -create-xcframework a apărut în Xcode 11. Comanda creează automat structura corectă de directoare și generează Info.plist cu descrierea tuturor platformelor. Dacă unul dintre .framework este deteriorat sau compilat cu o arhitectură incorectă, xcodebuild emite o eroare în etapa de validare.

Automatizarea prin scripturi de compilare

Pentru CI/CD se folosește un script shell care automatizează compilarea pentru toate platformele și crearea XCFramework. O abordare populară este o învelitoare sub formă de Makefile sau Fastlane lane cu parametrizarea scheme și output path.

# build_xcframework.sh — script de automatizare
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"

Un astfel de script se execută în pipeline-ul CI (GitHub Actions, Bitrise, Jenkins) după rularea testelor. XCFramework rezultat este arhivat și încărcat ca artefact de lansare sau publicat printr-un manager de dependențe precum CocoaPods cu ajutorul pod spec.

Conectarea XCFramework într-un proiect Xcode

Conectarea XCFramework într-un proiect Xcode nu necesită configurarea manuală a căilor de căutare. Este suficient să trageți .xcframework în secțiunea Frameworks, Libraries, and Embedded Content din setările General ale target-ului.

Spre deosebire de .framework, XCFramework nu necesită adăugarea unei faze Run Script pentru eliminarea arhitecturilor de simulator. Xcode determină automat segmentele disponibile și include doar cele necesare pentru schema de compilare curentă. Pentru dispozitiv fizic se folosește segmentul ios-arm64, pentru simulator — ios-arm64-x86_64-simulator sau ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework rezolvă segmentul corect în timpul compilării
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Pentru CocoaPods integrarea are loc prin podspec cu specificarea vendored_frameworks și lista platformelor suportate. Managerul de dependențe determină automat ce segmente sunt necesare pentru proiect. Multe SDK-uri comerciale — Firebase, Adjust, AppsFlyer — au trecut la XCFramework pentru simplificarea instalării.

Comparație între XCFramework și Swift Package Manager

Swift Package Manager și XCFramework nu concurează, ci se completează reciproc. SPM lucrează cu cod sursă și compilează dependențele la fiecare compilare a proiectului. XCFramework oferă binare gata făcute, fără a necesita compilare la consumator.

• XCFramework — livrare binară, protecția codului sursă, suport pentru toate platformele Apple într-un singur pachet
• SPM — lucru cu cod sursă deschis, posibilitatea de inspecție, compilare automată pentru platforma țintă
• Dependențele binare SPM folosesc XCFramework ca format de ambalare, combinând ambele abordări

Odată cu lansarea Swift Package Manager 5.3, Apple a adăugat suport pentru dependențe binare — acum SPM poate încărca XCFramework ca dependență la distanță. Package.swift indică URL-ul artefactului binar și suma sa de control pentru verificare.

Conform Swift Package Manager documentation (2024), dependențele binare sunt recomandate pentru SDK-urile care nu dezvăluie codul sursă sau pentru bibliotecile a căror compilare durează disproporționat de mult. Pentru proiectele open-source, livrarea cu cod sursă prin SPM este preferată.