XCFramework: co to jest, format dostawy binarnej i zastosowanie

Czym jest XCFramework?

XCFramework — format pakowania bibliotek binarnych i frameworków, przedstawiony przez Apple na WWDC 2019. Głównym celem jest stworzenie jednego bundle, który zawiera skompilowane wersje biblioteki dla wszystkich docelowych platform i architektur.

Przed pojawieniem się XCFramework programiści używali .framework z fat binary, łączącym wiele architektur za pomocą narzędzia lipo. To podejście stwarzało problemy: podczas kompilacji projektu dla symulatora fat binary zawierał zarówno architekturę symulatora, jak i urządzenia, co prowadziło do błędów przy wysyłaniu kompilacji do App Store. Programiści musieli pisać fazy Run Script do usuwania niepotrzebnych architektur.

Według Apple Developer Documentation (2024), XCFramework obsługuje wszystkie platformy ekosystemu Apple: iOS, iPadOS, macOS, tvOS, watchOS, visionOS i aplikacje katalizatorowe. Każda platforma otrzymuje oddzielny wycinek wewnątrz pakietu, co eliminuje konflikty architektur i upraszcza dystrybucję SDK.

Kiedy potrzebny jest XCFramework?

XCFramework jest stosowany w trzech głównych scenariuszach: dostarczanie zamkniętych SDK zewnętrznym programistom, dystrybucja natywnych modułów dla Flutter i React Native oraz publikacja bibliotek wymagających wstępnej kompilacji. Format jest obowiązkowy dla wszystkich nowych SDK publikowanych w ekosystemie Apple.

Programiści wybierają XCFramework, gdy kod źródłowy nie może być ujawniony, gdy biblioteka używa zastrzeżonych algorytmów lub gdy wymagana jest ochrona licencyjna. W przeciwieństwie do Swift Package Manager, który działa z kodem źródłowym, XCFramework dostarcza już skompilowane pliki binarne.

Jak XCFramework rozwiązuje problem fat binary?

Problem fat binary polegał na tym, że uniwersalny binarnik zawierał wiele architektur w jednym pliku Mach-O. Podczas kompilacji aplikacji dla symulatora Xcode włączał do binarnika architekturę arm64 urządzenia i x86_64 symulatora — App Store akceptował tylko architekturę urządzenia.

Tradycyjne rozwiązanie obejmowało dodanie fazy Run Script z wywołaniem lipo do usuwania architektur symulatora z końcowej kompilacji. To podejście było kruche i psuło się przy aktualizacjach Xcode lub dodawaniu nowych architektur (np. arm64 dla symulatora na Apple Silicon).

Według Swift.org (2023), zespół Swift Package Manager początkowo napotkał ten problem przy próbie obsługi zależności binarnych. XCFramework rozwiązał go na poziomie formatu: każdy wycinek to osobny folder z Info.plist opisującym docelową platformę i architekturę. Xcode automatycznie wybiera odpowiedni wycinek podczas kompilacji, nie wymagając post-processingu.

Zalety podejścia z oddzielnymi wycinkami

Każdy wycinek w XCFramework zawiera tylko jedną kombinację platformy i architektury. Na przykład ios-arm64 zawiera binarnik tylko dla urządzeń iOS, a ios-x86_64-simulator — tylko dla symulatora Intel Mac. Xcode automatycznie wybiera właściwy wycinek, eliminując potrzebę skryptów usuwania architektur i zmniejszając ryzyko błędów kompilacji.

Wycinek ios-arm64-x86_64-simulator pojawił się dla obsługi Apple Silicon Mac. Wcześniej dla symulatora wymagany był osobny binarnik pod arm64 (Apple Silicon) i x86_64 (Intel). XCFramework dopuszcza fat binary wewnątrz jednego wycinka dla symulatora — to jedyne wyjątek, gdy fat binary jest uzasadniony.

Struktura pakietu XCFramework

Pakiet XCFramework to katalog z rozszerzeniem .xcframework, zawierający Info.plist na najwyższym poziomie i foldery z wycinkami binarnymi. Każdy wycinek zawiera .framework lub .a bibliotekę dla konkretnej platformy.

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 pakietu zawiera klucz AvailableLibraries, wymieniający identyfikatory LibraryIdentifier, LibraryPath i SupportedPlatform dla każdego wycinka. Xcode czyta ten plik przy dodawaniu XCFramework do projektu i automatycznie konfiguruje ścieżki wyszukiwania oraz fazę Embed Frameworks.

Każdy wycinek stanowi pełnoprawny .framework lub statyczną bibliotekę z własnym Info.plist. Pozwala to XCFramework obsługiwać mieszane typy: statyczne biblioteki dla jednych platform i dynamiczne frameworki dla innych, choć w praktyce częściej używa się jednego typu dla wszystkich wycinków.

Tworzenie XCFramework z wiersza poleceń

Tworzenie XCFramework odbywa się przez xcodebuild -create-xcframework. Polecenie przyjmuje już skompilowane .framework lub .a biblioteki dla każdej platformy i łączy je w jeden pakiet.

Proces składa się z dwóch kroków: najpierw kompilowane są binarniki dla każdej docelowej platformy, następnie pakowane są do XCFramework. Do kompilacji używane są standardowe flagi destination Xcode.

# Krok 1: zbuduj frameworki dla każdej platformy
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"

# Krok 2: utwórz XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

Flaga -create-xcframework pojawiła się w Xcode 11. Polecenie automatycznie tworzy poprawną strukturę katalogów i generuje Info.plist z opisem wszystkich platform. Jeśli jeden z .framework jest uszkodzony lub skompilowany z nieprawidłową architekturą, xcodebuild zgłasza błąd na etapie walidacji.

Automatyzacja przez skrypty kompilacji

Do CI/CD używa się skryptu shell, automatyzującego kompilację pod wszystkie platformy i tworzenie XCFramework. Popularne podejście to owijka w postaci Makefile lub Fastlane lana z parametryzacją scheme i output path.

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

Taki skrypt jest wykonywany w pipeline CI (GitHub Actions, Bitrise, Jenkins) po przebiegu testów. Wynikowy XCFramework jest archiwizowany i ładowany jako artefakt wydania lub publikowany przez menedżera zależności, takiego jak CocoaPods, za pomocą pod spec.

Podłączanie XCFramework w projekcie Xcode

Podłączanie XCFramework w projekcie Xcode nie wymaga ręcznego konfigurowania ścieżek wyszukiwania. Wystarczy przeciągnąć .xcframework do sekcji Frameworks, Libraries, and Embedded Content w General ustawieniach targetu.

W przeciwieństwie do .framework, XCFramework nie wymaga dodawania fazy Run Script do usuwania architektur symulatora. Xcode automatycznie określa dostępne wycinki i dołącza tylko potrzebne dla bieżącego schematu kompilacji. Dla fizycznego urządzenia używany jest wycinek ios-arm64, dla symulatora — ios-arm64-x86_64-simulator lub ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework rozwiązuje właściwy wycinek w czasie kompilacji
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Dla CocoaPods integracja odbywa się przez podspec z określeniem vendored_frameworks i listą obsługiwanych platform. Menedżer zależności automatycznie określa, które wycinki są potrzebne dla projektu. Wiele komercyjnych SDK — Firebase, Adjust, AppsFlyer — przeszło na XCFramework dla uproszczenia instalacji.

Porównanie XCFramework i Swift Package Manager

Swift Package Manager i XCFramework nie konkurują, ale się uzupełniają. SPM działa z kodem źródłowym i kompiluje zależności przy każdej kompilacji projektu. XCFramework dostarcza gotowe binarniki, nie wymagając kompilacji po stronie konsumenta.

• XCFramework — dostawa binarna, ochrona kodu źródłowego, obsługa wszystkich platform Apple w jednym pakiecie
• SPM — praca z otwartym kodem źródłowym, możliwość inspekcji, automatyczna kompilacja pod docelową platformę
• Zależności binarne SPM używają XCFramework jako formatu pakowania, łącząc oba podejścia

Z wydaniem Swift Package Manager 5.3 Apple dodała obsługę zależności binarnych — teraz SPM może ładować XCFramework jako zdalną zależność. Package.swift wskazuje URL na binarny artefakt i jego sumę kontrolną do weryfikacji.

Według Swift Package Manager documentation (2024), zależności binarne są zalecane dla SDK, które nie ujawniają kodu źródłowego, lub dla bibliotek, których kompilacja zajmuje nieproporcjonalnie dużo czasu. Dla projektów open-source preferowana jest dostawa kodem źródłowym przez SPM.