XCFramework: шта је то, формат бинарне испоруке и примена

Шта је XCFramework?

XCFramework — формат паковања бинарних библиотека и фрејмворка, представљен од стране Apple-а на WWDC 2019. Главни циљ је стварање једног bundle-а који садржи компилиране верзије библиотеке за све циљне платформе и архитектуре.

Пре појаве XCFramework-а, програмери су користили .framework са fat binary-јем, који је обједињавао више архитектура кроз алатку lipo. Овај приступ стварао је проблеме: при компилацији пројекта за симулатор, fat binary је садржао и архитектуру симулатора и уређаја, што је доводило до грешака при слању компилације у App Store. Програмери су морали да пишу Run Script фазе за уклањање непотребних архитектура.

Према Apple Developer Documentation (2024), XCFramework подржава све платформе Apple екосистема: iOS, iPadOS, macOS, tvOS, watchOS, visionOS и катализаторске апликације. Свака платформа добија засебан слој унутар пакета, што елиминише конфликте архитектура и поједностављује дистрибуцију SDK-ова.

Када је потребан XCFramework?

XCFramework се примењује у три главна сценарија: испорука затворених SDK-ова трећим програмерима, дистрибуција изворних модула за Flutter и React Native, и објављивање библиотека које захтевају претходну компилацију. Формат је обавезан за све нове SDK-ове који се објављују у Apple екосистему.

Програмери бирају XCFramework када се изворни код не може открити, када библиотека користи власничке алгоритме или када је потребна лиценцна заштита. За разлику од Swift Package Manager-а који ради са изворним кодом, XCFramework испоручује већ компилиране бинарне датотеке.

Како XCFramework решава проблем fat binary-ја?

Проблем fat binary-ја састојао се у томе што је универзална бинарна датотека садржала више архитектура у једном Mach-O фајлу. При компилацији апликације за симулатор, Xcode је у бинарну датотеку укључивао архитектуру arm64 уређаја и x86_64 симулатора — App Store је прихватао само архитектуру уређаја.

Традиционално решење укључивало је додавање Run Script фазе са позивом lipo-а за уклањање архитектура симулатора из коначне компилације. Овај приступ био је крхак и ломио се при ажурирањима Xcode-а или додавању нових архитектура (нпр. arm64 за симулатор на Apple Silicon).

Према Swift.org (2023), тим Swift Package Manager-а је у почетку наишао на овај проблем при покушају подршке бинарним зависностима. XCFramework га је решио на нивоу формата: сваки слој је засебан фолдер са Info.plist-ом који описује циљну платформу и архитектуру. Xcode аутоматски бира одговарајући слој при компилацији, не захтевајући накнадну обраду.

Предности приступа са одвојеним слојевима

Сваки слој у XCFramework-у садржи само једну комбинацију платформе и архитектуре. На пример, ios-arm64 садржи бинарну датотеку само за iOS уређаје, а ios-x86_64-simulator — само за симулатор Intel Mac-а. Xcode аутоматски бира прави слој, елиминишући потребу за скриптама за уклањање архитектура и смањујући ризик од грешака при компилацији.

Слој ios-arm64-x86_64-simulator појавио се за подршку Apple Silicon Mac-у. Раније је за симулатор била потребна засебна бинарна датотека за arm64 (Apple Silicon) и x86_64 (Intel). XCFramework дозвољава fat binary унутар једног слоја за симулатор — ово је једини изузетак када је fat binary оправдан.

Структура XCFramework пакета

Пакет XCFramework представља директоријум са екстензијом .xcframework, који садржи Info.plist на горњем нивоу и фолдере са бинарним слојевима. Сваки слој укључује .framework или .a библиотеку за одређену платформу.

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 пакета садржи кључ AvailableLibraries, који наводи идентификаторе LibraryIdentifier, LibraryPath и SupportedPlatform за сваки слој. Xcode чита овај фајл при додавању XCFramework-а у пројекат и аутоматски конфигурише путање претраге и Embed Frameworks фазу.

Сваки слој представља пуноправни .framework или статичку библиотеку са сопственим Info.plist-ом. Ово омогућава XCFramework-у да подржава мешовите типове: статичке библиотеке за једне платформе и динамичке фрејмворке за друге, мада се у пракси чешће користи један тип за све слојеве.

Креирање XCFramework-а из командне линије

Креирање XCFramework-а се врши кроз xcodebuild -create-xcframework. Команда прима већ компилиране .framework или .a библиотеке за сваку платформу и обједињује их у јединствени пакет.

Процес се састоји од два корака: прво се компилирају бинарне датотеке за сваку циљну платформу, затим се пакују у XCFramework. За компилацију се користе стандардни destination флагови Xcode-а.

# Корак 1: направите фрејмворке за сваку платформу
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: креирајте XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

Флаг -create-xcframework појавио се у Xcode 11. Команда аутоматски креира исправну структуру директоријума и генерише Info.plist са описом свих платформи. Ако је један од .framework-ова оштећен или компилиран са погрешном архитектуром, xcodebuild даје грешку у фази валидације.

Аутоматизација кроз скрипте компилације

За CI/CD се користи shell скрипта која аутоматизује компилацију под све платформе и креирање XCFramework-а. Популаран приступ је омотач у облику Makefile-а или Fastlane lane-а са параметризацијом scheme и output path.

# build_xcframework.sh — скрипт за аутоматизацију
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"

Таква скрипта се извршава у CI пајплајну (GitHub Actions, Bitrise, Jenkins) након покретања тестова. Резултујући XCFramework се архивира и отпрема као артефакт издања или објављује преко менаџера зависности попут CocoaPods-а помоћу pod spec.

Повезивање XCFramework-а у Xcode пројекту

Повезивање XCFramework-а у Xcode пројекту не захтева ручно конфигурисање путања претраге. Довољно је превући .xcframework у секцију Frameworks, Libraries, and Embedded Content у General подешавањима target-а.

За разлику од .framework-а, XCFramework не захтева додавање Run Script фазе за уклањање архитектура симулатора. Xcode аутоматски одређује доступне слојеве и укључује само оне потребне за тренутну шему компилације. За физички уређај користи се слој ios-arm64, за симулатор — ios-arm64-x86_64-simulator или ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework решава прави слој у време компилације
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

За CocoaPods интеграција се врши кроз podspec са навођењем vendored_frameworks и листе подржаних платформи. Менаџер зависности аутоматски одређује који слојеви су потребни за пројекат. Многи комерцијални SDK-ови — Firebase, Adjust, AppsFlyer — прешли су на XCFramework ради поједностављења инсталације.

Поређење XCFramework-а и Swift Package Manager-а

Swift Package Manager и XCFramework се не такмиче, већ се допуњују. SPM ради са изворним кодом и компилира зависности при свакој компилацији пројекта. XCFramework пружа готове бинарне датотеке, не захтевајући компилацију на страни потрошача.

• XCFramework — бинарна испорука, заштита изворног кода, подршка за све Apple платформе у једном пакету
• SPM — рад са отвореним изворним кодом, могућност инспекције, аутоматска компилација за циљну платформу
• Бинарне зависности SPM-а користе XCFramework као формат паковања, обједињујући оба приступа

Са издавањем Swift Package Manager 5.3, Apple је додао подршку за бинарне зависности — сада SPM може да учита XCFramework као удаљену зависност. Package.swift наводи URL на бинарни артефакт и његов контролни збир за верификацију.

Према Swift Package Manager documentation (2024), бинарне зависности се препоручују за SDK-ове који не откривају изворни код или за библиотеке чија компилација траје несразмерно дуго. За open-source пројекте пожељна је испорука изворним кодом кроз SPM.