XCFramework: apa itu, format pengiriman biner dan penerapan

Apa itu XCFramework?

XCFramework — format pengemasan pustaka biner dan framework, diperkenalkan oleh Apple di WWDC 2019. Tujuan utamanya adalah membuat satu bundle yang berisi versi kompilasi pustaka untuk semua platform dan arsitektur target.

Sebelum munculnya XCFramework, pengembang menggunakan .framework dengan fat binary, yang menggabungkan beberapa arsitektur melalui utilitas lipo. Pendekatan ini menimbulkan masalah: saat kompilasi proyek untuk simulator, fat binary berisi arsitektur simulator dan perangkat, yang menyebabkan kesalahan saat mengirim build ke App Store. Pengembang harus menulis fase Run Script untuk menghapus arsitektur yang tidak perlu.

Menurut Apple Developer Documentation (2024), XCFramework mendukung semua platform ekosistem Apple: iOS, iPadOS, macOS, tvOS, watchOS, visionOS, dan aplikasi katalis. Setiap platform mendapatkan irisan terpisah di dalam paket, yang menghilangkan konflik arsitektur dan menyederhanakan distribusi SDK.

Kapan XCFramework diperlukan?

XCFramework diterapkan dalam tiga skenario utama: pengiriman SDK tertutup kepada pengembang pihak ketiga, distribusi modul native untuk Flutter dan React Native, dan publikasi pustaka yang memerlukan kompilasi awal. Format ini wajib untuk semua SDK baru yang diterbitkan di ekosistem Apple.

Pengembang memilih XCFramework ketika kode sumber tidak dapat diungkapkan, ketika pustaka menggunakan algoritme kepemilikan, atau ketika perlindungan lisensi diperlukan. Tidak seperti Swift Package Manager yang bekerja dengan kode sumber, XCFramework mengirimkan file biner yang sudah dikompilasi.

Bagaimana XCFramework memecahkan masalah fat binary?

Masalah fat binary adalah bahwa biner universal berisi beberapa arsitektur dalam satu file Mach-O. Saat kompilasi aplikasi untuk simulator, Xcode menyertakan arsitektur arm64 perangkat dan x86_64 simulator ke dalam biner — App Store hanya menerima arsitektur perangkat.

Solusi tradisional mencakup penambahan fase Run Script dengan pemanggilan lipo untuk menghapus arsitektur simulator dari build akhir. Pendekatan ini rapuh dan rusak saat pembaruan Xcode atau saat menambahkan arsitektur baru (misalnya arm64 untuk simulator di Apple Silicon).

Menurut Swift.org (2023), tim Swift Package Manager awalnya menghadapi masalah ini saat mencoba mendukung dependensi biner. XCFramework menyelesaikannya di tingkat format: setiap irisan adalah folder terpisah dengan Info.plist yang menjelaskan platform dan arsitektur target. Xcode secara otomatis memilih irisan yang tepat saat kompilasi, tanpa memerlukan pemrosesan lanjutan.

Keuntungan pendekatan dengan irisan terpisah

Setiap irisan di XCFramework hanya berisi satu kombinasi platform dan arsitektur. Misalnya, ios-arm64 berisi biner hanya untuk perangkat iOS, dan ios-x86_64-simulator hanya untuk simulator Intel Mac. Xcode secara otomatis memilih irisan yang tepat, menghilangkan kebutuhan skrip penghapusan arsitektur dan mengurangi risiko kesalahan kompilasi.

Irisan ios-arm64-x86_64-simulator muncul untuk dukungan Apple Silicon Mac. Sebelumnya, simulator memerlukan biner terpisah untuk arm64 (Apple Silicon) dan x86_64 (Intel). XCFramework mengizinkan fat binary di dalam satu irisan untuk simulator — ini satu-satunya pengecualian ketika fat binary dibenarkan.

Struktur paket XCFramework

Paket XCFramework adalah direktori dengan ekstensi .xcframework, berisi Info.plist di tingkat atas dan folder dengan irisan biner. Setiap irisan berisi pustaka .framework atau .a untuk platform tertentu.

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 paket berisi kunci AvailableLibraries, yang mendaftarkan pengenal LibraryIdentifier, LibraryPath, dan SupportedPlatform untuk setiap irisan. Xcode membaca file ini saat menambahkan XCFramework ke proyek dan secara otomatis mengonfigurasi jalur pencarian serta fase Embed Frameworks.

Setiap irisan adalah .framework lengkap atau pustaka statis dengan Info.plist sendiri. Ini memungkinkan XCFramework mendukung tipe campuran: pustaka statis untuk beberapa platform dan framework dinamis untuk yang lain, meskipun dalam praktiknya satu jenis lebih sering digunakan untuk semua irisan.

Membuat XCFramework dari baris perintah

Pembuatan XCFramework dilakukan melalui xcodebuild -create-xcframework. Perintah menerima pustaka .framework atau .a yang sudah dikompilasi untuk setiap platform dan menggabungkannya menjadi satu paket.

Proses terdiri dari dua langkah: pertama biner dikompilasi untuk setiap platform target, kemudian dikemas ke dalam XCFramework. Untuk kompilasi digunakan flag destination standar Xcode.

# Langkah 1: bangun framework untuk setiap 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"

# Langkah 2: buat XCFramework
xcodebuild -create-xcframework -framework ./iOS/MyLibrary.framework -framework ./iOSSim/MyLibrary.framework -framework ./macOS/MyLibrary.framework -output ./MyLibrary.xcframework

Flag -create-xcframework muncul di Xcode 11. Perintah secara otomatis membuat struktur direktori yang benar dan menghasilkan Info.plist dengan deskripsi semua platform. Jika salah satu .framework rusak atau dikompilasi dengan arsitektur yang salah, xcodebuild memberikan kesalahan pada tahap validasi.

Otomatisasi melalui skrip kompilasi

Untuk CI/CD digunakan skrip shell yang mengotomatiskan kompilasi di semua platform dan pembuatan XCFramework. Pendekatan populer adalah wrapper dalam bentuk Makefile atau Fastlane lane dengan parameterisasi scheme dan output path.

# build_xcframework.sh — skrip otomatisasi
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"

Skrip semacam itu dijalankan di pipeline CI (GitHub Actions, Bitrise, Jenkins) setelah pengujian. XCFramework yang dihasilkan diarsipkan dan diunggah sebagai artefak rilis atau dipublikasikan melalui manajer dependensi seperti CocoaPods menggunakan pod spec.

Menghubungkan XCFramework di proyek Xcode

Menghubungkan XCFramework di proyek Xcode tidak memerlukan konfigurasi manual jalur pencarian. Cukup seret .xcframework ke bagian Frameworks, Libraries, and Embedded Content di pengaturan General target.

Tidak seperti .framework, XCFramework tidak memerlukan penambahan fase Run Script untuk menghapus arsitektur simulator. Xcode secara otomatis menentukan irisan yang tersedia dan hanya menyertakan yang diperlukan untuk skema kompilasi saat ini. Untuk perangkat fisik digunakan irisan ios-arm64, untuk simulator — ios-arm64-x86_64-simulator atau ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework menyelesaikan irisan yang tepat pada waktu kompilasi
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

Untuk CocoaPods integrasi dilakukan melalui podspec dengan menentukan vendored_frameworks dan daftar platform yang didukung. Manajer dependensi secara otomatis menentukan irisan mana yang diperlukan untuk proyek. Banyak SDK komersial — Firebase, Adjust, AppsFlyer — telah beralih ke XCFramework untuk menyederhanakan instalasi.

Perbandingan XCFramework dan Swift Package Manager

Swift Package Manager dan XCFramework tidak bersaing, melainkan saling melengkapi. SPM bekerja dengan kode sumber dan mengompilasi dependensi pada setiap kompilasi proyek. XCFramework menyediakan biner siap pakai tanpa memerlukan kompilasi di pihak konsumen.

• XCFramework — pengiriman biner, perlindungan kode sumber, dukungan untuk semua platform Apple dalam satu paket
• SPM — bekerja dengan kode sumber terbuka, kemampuan inspeksi, kompilasi otomatis untuk platform target
• Dependensi biner SPM menggunakan XCFramework sebagai format pengemasan, menggabungkan kedua pendekatan

Dengan dirilisnya Swift Package Manager 5.3, Apple menambahkan dukungan untuk dependensi biner — sekarang SPM dapat memuat XCFramework sebagai dependensi jarak jauh. Package.swift menentukan URL artefak biner dan checksum-nya untuk verifikasi.

Menurut Swift Package Manager documentation (2024), dependensi biner direkomendasikan untuk SDK yang tidak mengungkapkan kode sumber atau untuk pustaka yang kompilasinya memakan waktu tidak proporsional. Untuk proyek open-source, pengiriman dengan kode sumber melalui SPM lebih diutamakan.