XCFramework: nedir, ikili dağıtım biçimi ve kullanımı

XCFramework Nedir?

XCFramework, Apple tarafından WWDC 2019'da tanıtılan ikili kitaplıklar ve framework'ler için bir paketleme biçimidir. Temel amaç, bir kitaplığın tüm hedef platformlar ve mimariler için derlenmiş sürümlerini içeren tek bir paket oluşturmaktır.

XCFramework'den önce geliştiriciler, lipo yardımcı programı aracılığıyla birden çok mimariyi birleştiren fat binary ile .framework kullanıyordu. Bu yaklaşım sorunlara neden oluyordu: simülatör için bir proje derlerken, fat binary hem simülatör hem de cihaz mimarisini içeriyordu ve bu da derlemeyi App Store'a gönderirken hatalara yol açıyordu. Geliştiriciler, gereksiz mimarileri kaldırmak için Run Script aşamaları yazmak zorundaydı.

Apple Geliştirici Belgelerine (2024) göre XCFramework, Apple ekosistemindeki tüm platformları destekler: iOS, iPadOS, macOS, tvOS, watchOS, visionOS ve Catalyst uygulamaları. Her platform, paket içinde ayrı bir slice alır, bu da mimari çakışmalarını ortadan kaldırır ve SDK dağıtımını basitleştirir.

XCFramework Ne Zaman Gerekir?

XCFramework üç ana senaryoda kullanılır: kapalı SDK'ları üçüncü taraf geliştiricilere dağıtmak, Flutter ve React Native için yerel modüller dağıtmak ve ön derleme gerektiren kitaplıkları yayınlamak. Bu biçim, Apple ekosisteminde yayınlanan tüm yeni SDK'lar için zorunludur.

Geliştiriciler, kaynak kodu açıklanamadığında, kitaplık tescilli algoritmalar kullandığında veya lisans koruması gerektiğinde XCFramework'ü seçer. Kaynak koduyla çalışan Swift Package Manager'ın aksine XCFramework, zaten derlenmiş ikili dosyaları teslim eder.

XCFramework Fat Binary Sorununu Nasıl Çözer?

Fat binary sorunu, evrensel bir ikili dosyanın tek bir Mach-O dosyasında birden çok mimari içermesiydi. Simülatör için bir uygulama derlerken Xcode, hem cihaz mimarisi arm64'ü hem de simülatör mimarisi x86_64'ü dahil ediyordu — App Store yalnızca cihaz mimarisini kabul ediyordu.

Geleneksel çözüm, son derlemeden simülatör mimarilerini kaldırmak için lipo'yu çağıran bir Run Script aşaması eklemeyi içeriyordu. Bu yaklaşım kırılgandı ve Xcode güncellemeleri veya yeni mimariler (Apple Silicon'da simülatör için arm64 gibi) ortaya çıktığında bozuluyordu.

Swift.org'a (2023) göre Swift Package Manager ekibi, ikili bağımlılıkları desteklemeye çalışırken başlangıçta bu sorunla karşılaştı. XCFramework bunu biçim düzeyinde çözdü: her slice, hedef platformu ve mimariyi tanımlayan bir Info.plist içeren ayrı bir klasördür. Xcode, derleme sırasında otomatik olarak gerekli slice'ı seçer ve son işlem gerektirmez.

Ayrı Slice Yaklaşımının Avantajları

XCFramework içindeki her slice yalnızca bir platform-mimari kombinasyonu içerir. Örneğin, ios-arm64 yalnızca iOS cihazları için ikili dosyayı içerir ve ios-x86_64-simulator yalnızca Intel Mac simülatörü içindir. Xcode otomatik olarak doğru slice'ı seçer, mimari kaldırma komut dosyalarına olan ihtiyacı ortadan kaldırır ve derleme hatası riskini azaltır.

ios-arm64-x86_64-simulator slice'ı, Apple Silicon Mac'leri desteklemek için tanıtıldı. Daha önce simülatör, arm64 (Apple Silicon) ve x86_64 (Intel) için ayrı ikili dosyalar gerektiriyordu. XCFramework, tek bir simülatör slice'ı içinde fat binary'ye izin verir — bu, fat binary'nin haklı görüldüğü tek istisnadır.

XCFramework Paket Yapısı

XCFramework paketi, .xcframework uzantılı bir dizindir ve üst düzeyde bir Info.plist ile ikili slice'ları içeren klasörler içerir. Her slice, belirli bir platform için bir .framework veya .a kitaplığı içerir.

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

Paketin Info.plist'i, her slice için LibraryIdentifier, LibraryPath ve SupportedPlatform değerlerini listeleyen AvailableLibraries anahtarını içerir. Xcode, projeye bir XCFramework eklerken bu dosyayı okur ve arama yollarını ile Embed Frameworks aşamasını otomatik olarak yapılandırır.

Her slice, kendi Info.plist'ine sahip tam bir .framework veya statik kitaplıktır. Bu, XCFramework'ün karma türleri desteklemesine olanak tanır: bazı platformlar için statik kitaplıklar ve diğerleri için dinamik framework'ler, ancak pratikte tüm slice'lar için bir tür kullanılır.

Komut Satırından XCFramework Oluşturma

XCFramework oluşturma, xcodebuild -create-xcframework aracılığıyla yapılır. Komut, her platform için önceden derlenmiş .framework veya .a kitaplıklarını girdi olarak alır ve bunları tek bir pakette birleştirir.

Süreç iki adımdan oluşur: önce her hedef platform için ikili dosyalar derlenir, ardından bunlar bir XCFramework içinde paketlenir. Derleme için standart Xcode destination bayrakları kullanılır.

# Step 1: build frameworks for each 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"

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

-create-xcframework bayrağı Xcode 11'de tanıtıldı. Komut otomatik olarak doğru dizin yapısını oluşturur ve tüm platformların açıklamasıyla bir Info.plist üretir. .framework dosyalarından biri hasarlıysa veya yanlış mimariyle derlenmişse, xcodebuild doğrulama aşamasında hata verir.

Derleme Komut Dosyalarıyla Otomasyon

CI/CD için, tüm platformlar için derlemeyi ve XCFramework oluşturmayı otomatikleştiren bir shell komut dosyası kullanılır. Popüler bir yaklaşım, parametreleştirilmiş scheme ve çıktı yolu ile Makefile veya Fastlane lane biçiminde bir sarmalayıcıdır.

# 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"

Böyle bir komut dosyası, testler geçtikten sonra bir CI hattında (GitHub Actions, Bitrise, Jenkins) çalışır. Ortaya çıkan XCFramework arşivlenir ve bir sürüm yapıtı olarak yüklenir veya pod spec aracılığıyla CocoaPods gibi bir bağımlılık yöneticisi aracılığıyla yayınlanır.

Xcode Projesine XCFramework Entegre Etme

XCFramework'ü bir Xcode projesine entegre etmek, arama yollarının manuel olarak yapılandırılmasını gerektirmez. Hedefin Genel ayarlarındaki Frameworks, Libraries, and Embedded Content bölümüne .xcframework dosyasını sürüklemek yeterlidir.

.framework'ün aksine XCFramework, simülatör mimarilerini kaldırmak için bir Run Script aşaması eklenmesini gerektirmez. Xcode, mevcut slice'ları otomatik olarak belirler ve yalnızca geçerli derleme şeması için gerekli olanları dahil eder. Fiziksel bir cihaz için ios-arm64 slice'ı kullanılır, simülatör için — ios-arm64-x86_64-simulator veya ios-x86_64-simulator.

import MyLibrary

func processData() {
    // XCFramework resolves the correct slice at build time
    let processor = DataProcessor()
    let result = processor.analyze(input: "sample")
    print(result)
}

CocoaPods için entegrasyon, vendored_frameworks ve desteklenen platformların bir listesiyle podspec aracılığıyla yapılır. Bağımlılık yöneticisi, proje için hangi slice'ların gerekli olduğunu otomatik olarak belirler. Firebase, Adjust, AppsFlyer gibi birçok ticari SDK, kurulumu basitleştirmek için XCFramework'e geçmiştir.

XCFramework ve Swift Package Manager Karşılaştırması

Swift Package Manager ve XCFramework rakip değil, birbirini tamamlayıcıdır. SPM, kaynak koduyla çalışır ve her proje derlemesinde bağımlılıkları derler. XCFramework, tüketici tarafında derleme gerektirmeden hazır ikili dosyalar sağlar.

• XCFramework — ikili dağıtım, kaynak kodu koruması, tek pakette tüm Apple platformlarını destekleme
• SPM — açık kaynak koduyla çalışma, inceleme imkanı, hedef platform için otomatik derleme
• SPM ikili bağımlılıkları, her iki yaklaşımı birleştirerek paketleme biçimi olarak XCFramework kullanır

Swift Package Manager 5.3'ün piyasaya sürülmesiyle Apple, ikili bağımlılık desteği ekledi — artık SPM, uzak bir bağımlılık olarak XCFramework indirebilir. Package.swift, ikili yapıtın URL'sini ve doğrulama için sağlama toplamını belirtir.

Swift Package Manager belgelerine (2024) göre, ikili bağımlılıklar kaynak kodunu açıklamayan SDK'lar veya derleme süresi orantısız derecede uzun olan kitaplıklar için önerilir. Açık kaynak projeler için SPM aracılığıyla kaynak kodu dağıtımı tercih edilir.