XCFramework: co to je, formát binární dodávky a použití

Co je XCFramework?

XCFramework — formát balení binárních knihoven a frameworků, představený společností Apple na WWDC 2019. Hlavním cílem je vytvoření jednoho bundle, který obsahuje zkompilované verze knihovny pro všechny cílové platformy a architektury.

Před příchodem XCFramework používali vývojáři .framework s fat binary, který spojoval více architektur pomocí nástroje lipo. Tento přístup vytvářel problémy: při kompilaci projektu pro simulátor fat binary obsahoval jak architekturu simulátoru, tak zařízení, což vedlo k chybám při odesílání sestavení do App Store. Vývojáři museli psát fáze Run Script pro odstranění nepotřebných architektur.

Podle Apple Developer Documentation (2024) XCFramework podporuje všechny platformy ekosystému Apple: iOS, iPadOS, macOS, tvOS, watchOS, visionOS a katalyzátorové aplikace. Každá platforma dostává samostatný řez uvnitř balíčku, což eliminuje konflikty architektur a zjednodušuje distribuci SDK.

Kdy je XCFramework potřeba?

XCFramework se používá ve třech hlavních scénářích: dodávka uzavřených SDK třetím stranám, distribuce nativních modulů pro Flutter a React Native a publikování knihoven vyžadujících předběžnou kompilaci. Formát je povinný pro všechna nová SDK publikovaná v ekosystému Apple.

Vývojáři volí XCFramework, když zdrojový kód nelze zveřejnit, když knihovna používá proprietární algoritmy nebo když je vyžadována licenční ochrana. Na rozdíl od Swift Package Manager, který pracuje se zdrojovým kódem, XCFramework dodává již zkompilované binární soubory.

Jak XCFramework řeší problém fat binary?

Problém fat binary spočíval v tom, že univerzální binární soubor obsahoval několik architektur v jednom souboru Mach-O. Při kompilaci aplikace pro simulátor Xcode zahrnul do binárního souboru architekturu arm64 zařízení a x86_64 simulátoru — App Store přijímal pouze architekturu zařízení.

Tradiční řešení zahrnovalo přidání fáze Run Script s voláním lipo pro odstranění architektur simulátoru z konečného sestavení. Tento přístup byl křehký a rozbíjel se při aktualizacích Xcode nebo přidávání nových architektur (např. arm64 pro simulátor na Apple Silicon).

Podle Swift.org (2023) tým Swift Package Manager zpočátku narazil na tento problém při pokusu o podporu binárních závislostí. XCFramework jej vyřešil na úrovni formátu: každý řez je samostatná složka s Info.plist popisujícím cílovou platformu a architekturu. Xcode automaticky vybírá správný řez při kompilaci, aniž by vyžadoval následné zpracování.

Výhody přístupu s oddělenými řezy

Každý řez v XCFramework obsahuje pouze jednu kombinaci platformy a architektury. Například ios-arm64 obsahuje binární soubor pouze pro zařízení iOS a ios-x86_64-simulator pouze pro simulátor Intel Mac. Xcode automaticky vybírá správný řez, čímž eliminuje potřebu skriptů pro odstraňování architektur a snižuje riziko chyb kompilace.

Řez ios-arm64-x86_64-simulator vznikl pro podporu Apple Silicon Mac. Dříve simulátor vyžadoval samostatný binární soubor pro arm64 (Apple Silicon) a x86_64 (Intel). XCFramework povoluje fat binary uvnitř jednoho řezu pro simulátor — to je jediná výjimka, kdy je fat binary ospravedlnitelný.

Struktura balíčku XCFramework

Balíček XCFramework je adresář s příponou .xcframework, obsahující Info.plist na nejvyšší úrovni a složky s binárními řezy. Každý řez obsahuje knihovnu .framework nebo .a pro konkrétní platformu.

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 balíčku obsahuje klíč AvailableLibraries, který vypisuje identifikátory LibraryIdentifier, LibraryPath a SupportedPlatform pro každý řez. Xcode čte tento soubor při přidávání XCFramework do projektu a automaticky konfiguruje cesty vyhledávání a fázi Embed Frameworks.

Každý řez představuje plnohodnotný .framework nebo statickou knihovnu s vlastním Info.plist. To umožňuje XCFramework podporovat smíšené typy: statické knihovny pro některé platformy a dynamické frameworky pro jiné, i když v praxi se častěji používá jeden typ pro všechny řezy.

Vytvoření XCFramework z příkazového řádku

Vytvoření XCFramework se provádí pomocí xcodebuild -create-xcframework. Příkaz přijímá již zkompilované knihovny .framework nebo .a pro každou platformu a spojuje je do jednoho balíčku.

Proces se skládá ze dvou kroků: nejprve se zkompilují binární soubory pro každou cílovou platformu, poté se zabalí do XCFramework. Pro kompilaci se používají standardní destination příznaky Xcode.

# Krok 1: sestavte frameworky pro každou platformu
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: vytvořte XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

Příznak -create-xcframework se objevil v Xcode 11. Příkaz automaticky vytvoří správnou strukturu adresářů a vygeneruje Info.plist s popisem všech platforem. Pokud je jeden z .framework poškozen nebo zkompilován s nesprávnou architekturou, xcodebuild vydá chybu ve fázi ověření.

Automatizace pomocí skriptů kompilace

Pro CI/CD se používá shell skript, který automatizuje kompilaci pro všechny platformy a vytvoření XCFramework. Oblíbeným přístupem je obálka ve formě Makefile nebo Fastlane lane s parametrizací scheme a output path.

# build_xcframework.sh — automatizační skript
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"

Takový skript se spouští v CI pipeline (GitHub Actions, Bitrise, Jenkins) po spuštění testů. Výsledný XCFramework je archivován a nahrán jako artefakt vydání nebo publikován prostřednictvím správce závislostí, jako je CocoaPods, pomocí pod spec.

Připojení XCFramework v projektu Xcode

Připojení XCFramework v projektu Xcode nevyžaduje ruční konfiguraci cest vyhledávání. Stačí přetáhnout .xcframework do sekce Frameworks, Libraries, and Embedded Content v nastavení General targetu.

Na rozdíl od .framework, XCFramework nevyžaduje přidání fáze Run Script pro odstranění architektur simulátoru. Xcode automaticky určuje dostupné řezy a zahrnuje pouze ty potřebné pro aktuální schéma kompilace. Pro fyzické zařízení se používá řez ios-arm64, pro simulátor — ios-arm64-x86_64-simulator nebo ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework řeší správný řez v době kompilace
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Pro CocoaPods probíhá integrace prostřednictvím podspec s uvedením vendored_frameworks a seznamu podporovaných platforem. Správce závislostí automaticky určuje, které řezy jsou pro projekt potřeba. Mnoho komerčních SDK — Firebase, Adjust, AppsFlyer — přešlo na XCFramework pro zjednodušení instalace.

Srovnání XCFramework a Swift Package Manager

Swift Package Manager a XCFramework si nekonkurují, ale vzájemně se doplňují. SPM pracuje se zdrojovým kódem a kompiluje závisnosti při každé kompilaci projektu. XCFramework poskytuje hotové binární soubory, aniž by vyžadoval kompilaci na straně spotřebitele.

• XCFramework — binární dodávka, ochrana zdrojového kódu, podpora všech platforem Apple v jednom balíčku
• SPM — práce s otevřeným zdrojovým kódem, možnost inspekce, automatická kompilace pro cílovou platformu
• Binární závislosti SPM používají XCFramework jako formát balení, kombinují oba přístupy

S vydáním Swift Package Manager 5.3 Apple přidal podporu pro binární závislosti — nyní SPM může načíst XCFramework jako vzdálenou závislost. Package.swift uvádí URL binárního artefaktu a jeho kontrolní součet pro ověření.

Podle Swift Package Manager documentation (2024) jsou binární závislosti doporučeny pro SDK, která nezveřejňují zdrojový kód, nebo pro knihovny, jejichž kompilace trvá neúměrně dlouho. Pro open-source projekty je preferována dodávka se zdrojovým kódem prostřednictvím SPM.