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.