XCFramework: ano ito, format ng binary delivery at aplikasyon

Ano ang XCFramework?

XCFramework — isang format para sa pag-iimpake ng mga binary library at framework, na ipinakilala ng Apple sa WWDC 2019. Ang pangunahing layunin ay lumikha ng isang bundle na naglalaman ng mga naka-compile na bersyon ng library para sa lahat ng target na platform at arkitektura.

Bago ang pagdating ng XCFramework, ang mga developer ay gumagamit ng .framework na may fat binary, na pinagsasama ang maraming arkitektura sa pamamagitan ng utility na lipo. Ang approach na ito ay lumilikha ng mga problema: sa pag-compile ng proyekto para sa simulator, ang fat binary ay naglalaman ng parehong arkitektura ng simulator at device, na humantong sa mga error kapag nagpapadala ng build sa App Store. Ang mga developer ay kailangang sumulat ng Run Script phases para tanggalin ang hindi kinakailangang arkitektura.

Ayon sa Apple Developer Documentation (2024), ang XCFramework ay sumusuporta sa lahat ng platform ng ecosystem ng Apple: iOS, iPadOS, macOS, tvOS, watchOS, visionOS at catalyst application. Ang bawat platform ay tumatanggap ng hiwalay na slice sa loob ng package, na nag-aalis ng mga conflict ng arkitektura at nagpapasimple sa pamamahagi ng SDK.

Kailan kailangan ang XCFramework?

XCFramework ay ginagamit sa tatlong pangunahing senaryo: paghahatid ng mga closed SDK sa mga third-party developer, pamamahagi ng native modules para sa Flutter at React Native, at pag-publish ng mga library na nangangailangan ng paunang pag-compile. Ang format ay sapilitan para sa lahat ng bagong SDK na nai-publish sa ecosystem ng Apple.

Pinipili ng mga developer ang XCFramework kapag hindi maaaring ibunyag ang source code, kapag ang library ay gumagamit ng proprietary algorithm, o kapag kinakailangan ang proteksyon ng lisensya. Hindi tulad ng Swift Package Manager na gumagana sa source code, ang XCFramework ay naghahatid ng mga naka-compile na binary file.

Paano nilulutas ng XCFramework ang problema ng fat binary?

Ang problema ng fat binary ay na ang universal binary ay naglalaman ng maraming arkitektura sa isang Mach-O file. Sa pag-compile ng application para sa simulator, isinama ng Xcode ang arkitekturang arm64 ng device at x86_64 ng simulator sa binary — ang App Store ay tumatanggap lamang ng arkitektura ng device.

Ang tradisyonal na solusyon ay kasama ang pagdaragdag ng Run Script phase na may tawag sa lipo upang alisin ang mga arkitektura ng simulator mula sa huling build. Ang approach na ito ay marupok at nasira sa mga update ng Xcode o sa pagdaragdag ng mga bagong arkitektura (hal. arm64 para sa simulator sa Apple Silicon).

Ayon sa Swift.org (2023), ang koponan ng Swift Package Manager ay una nang nakatagpo ng problemang ito sa pagsisikap na suportahan ang binary dependencies. Nilutas ito ng XCFramework sa antas ng format: bawat slice ay isang hiwalay na folder na may Info.plist na naglalarawan ng target na platform at arkitektura. Awtomatikong pinipili ng Xcode ang tamang slice sa pag-compile, hindi nangangailangan ng post-processing.

Mga bentahe ng approach na may magkakahiwalay na slice

Bawat slice sa XCFramework ay naglalaman lamang ng isang kombinasyon ng platform at arkitektura. Halimbawa, ang ios-arm64 ay naglalaman ng binary para lamang sa iOS device, at ang ios-x86_64-simulator ay para lamang sa Intel Mac simulator. Awtomatikong pinipili ng Xcode ang tamang slice, inaalis ang pangangailangan para sa mga script ng pagtanggal ng arkitektura at binabawasan ang panganib ng mga error sa pag-compile.

Ang slice na ios-arm64-x86_64-simulator ay lumitaw para sa suporta ng Apple Silicon Mac. Dati, ang simulator ay nangangailangan ng hiwalay na binary para sa arm64 (Apple Silicon) at x86_64 (Intel). Pinapayagan ng XCFramework ang fat binary sa loob ng isang slice para sa simulator — ito ang tanging exception kung kailan nabibigyang-katwiran ang fat binary.

Istraktura ng XCFramework package

Ang XCFramework package ay isang direktoryo na may extension na .xcframework, na naglalaman ng Info.plist sa pinakamataas na antas at mga folder na may binary slices. Bawat slice ay naglalaman ng .framework o .a library para sa isang partikular na platform.

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

Ang Info.plist ng package ay naglalaman ng key na AvailableLibraries, na naglilista ng mga identifier na LibraryIdentifier, LibraryPath at SupportedPlatform para sa bawat slice. Binabasa ng Xcode ang file na ito kapag nagdaragdag ng XCFramework sa proyekto at awtomatikong nagko-configure ng mga search path at Embed Frameworks phase.

Bawat slice ay isang ganap na .framework o static library na may sariling Info.plist. Ito ay nagpapahintulot sa XCFramework na suportahan ang mga mixed type: static library para sa ilang platform at dynamic framework para sa iba, bagaman sa praktika isang uri ang mas madalas na ginagamit para sa lahat ng slice.

Paglikha ng XCFramework mula sa command line

Ang paglikha ng XCFramework ay ginagawa sa pamamagitan ng xcodebuild -create-xcframework. Ang command ay tumatanggap ng mga naka-compile na .framework o .a library para sa bawat platform at pinagsasama ang mga ito sa isang pakete.

Ang proseso ay binubuo ng dalawang hakbang: una ang mga binary ay naka-compile para sa bawat target na platform, pagkatapos ay naka-package sa XCFramework. Para sa pag-compile, ginagamit ang standard destination flags ng Xcode.

# Hakbang 1: bumuo ng mga framework para sa bawat 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"

# Hakbang 2: lumikha ng XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

Ang flag na -create-xcframework ay lumitaw sa Xcode 11. Awtomatikong ginagawa ng command ang tamang istraktura ng direktoryo at bumubuo ng Info.plist na may paglalarawan ng lahat ng platform. Kung ang isa sa .framework ay nasira o naka-compile na may maling arkitektura, ang xcodebuild ay nagbibigay ng error sa yugto ng validation.

Automation sa pamamagitan ng compilation script

Para sa CI/CD ginagamit ang isang shell script na nag-automate ng pag-compile sa lahat ng platform at paglikha ng XCFramework. Ang popular na approach ay isang wrapper sa anyo ng Makefile o Fastlane lane na may parameterization ng scheme at output path.

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

Ang naturang script ay isinasagawa sa CI pipeline (GitHub Actions, Bitrise, Jenkins) pagkatapos ng pagpapatakbo ng mga test. Ang resultang XCFramework ay ina-archive at ina-upload bilang release artifact o nai-publish sa pamamagitan ng dependency manager tulad ng CocoaPods gamit ang pod spec.

Pagkonekta ng XCFramework sa proyekto ng Xcode

Ang pagkonekta ng XCFramework sa proyekto ng Xcode ay hindi nangangailangan ng manu-manong pag-configure ng mga search path. Sapat na i-drag ang .xcframework sa seksyong Frameworks, Libraries, and Embedded Content sa General settings ng target.

Hindi tulad ng .framework, ang XCFramework ay hindi nangangailangan ng pagdaragdag ng Run Script phase para sa pagtanggal ng mga arkitektura ng simulator. Awtomatikong tinutukoy ng Xcode ang mga available na slice at isinasama lamang ang mga kailangan para sa kasalukuyang compilation scheme. Para sa pisikal na device ginagamit ang slice na ios-arm64, para sa simulator — ios-arm64-x86_64-simulator o ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework ay nilulutas ang tamang slice sa oras ng pag-compile
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Para sa CocoaPods ang integrasyon ay sa pamamagitan ng podspec na may pagtukoy ng vendored_frameworks at listahan ng mga supported platform. Awtomatikong tinutukoy ng dependency manager kung aling slice ang kailangan para sa proyekto. Maraming commercial SDK — Firebase, Adjust, AppsFlyer — ay lumipat na sa XCFramework para pasimplehin ang pag-install.

Paghahambing ng XCFramework at Swift Package Manager

Swift Package Manager at XCFramework ay hindi nagkumpitensya, bagkus ay nagpupuno sa isa't isa. Ang SPM ay gumagana sa source code at nag-co-compile ng mga dependency sa bawat compilation ng proyekto. Ang XCFramework ay nagbibigay ng ready-made binary files nang hindi nangangailangan ng compilation sa panig ng consumer.

• XCFramework — binary delivery, proteksyon ng source code, suporta para sa lahat ng Apple platform sa isang pakete
• SPM — trabaho sa open source code, kakayahang mag-inspeksyon, awtomatikong compilation para sa target platform
• Binary dependencies ng SPM ay gumagamit ng XCFramework bilang packaging format, pinagsasama ang parehong approach

Sa paglabas ng Swift Package Manager 5.3, nagdagdag ang Apple ng suporta para sa binary dependencies — ngayon ang SPM ay maaaring mag-load ng XCFramework bilang remote dependency. Ang Package.swift ay tumutukoy ng URL sa binary artifact at ang checksum nito para sa pag-verify.

Ayon sa Swift Package Manager documentation (2024), ang binary dependencies ay inirerekomenda para sa mga SDK na hindi nagbubunyag ng source code o para sa mga library na ang compilation ay tumatagal ng hindi proporsyonal na oras. Para sa open-source projects, ang delivery na may source code sa pamamagitan ng SPM ay mas pinipili.