XCFramework: چیست، قالب تحویل باینری و کاربرد

XCFramework چیست؟

XCFramework — قالبی برای بسته‌بندی کتابخانه‌های باینری و فریمورک‌ها است که توسط اپل در WWDC 2019 معرفی شد. هدف اصلی ایجاد یک باندل واحد است که شامل نسخه‌های کامپایل‌شده کتابخانه برای تمام پلتفرم‌ها و معماری‌های هدف است.

قبل از ظهور XCFramework، توسعه‌دهندگان از .framework با باینری چاق استفاده می‌کردند که چندین معماری را از طریق ابزار lipo ترکیب می‌کرد. این رویکرد مشکلاتی ایجاد می‌کرد: هنگام ساخت پروژه برای شبیه‌ساز، باینری چاق هم معماری شبیه‌ساز و هم دستگاه را شامل می‌شد که منجر به خطا هنگام ارسال بیلد به App Store می‌شد. توسعه‌دهندگان مجبور بودند فازهای Run Script برای حذف معماری‌های غیرضروری بنویسند.

بر اساس Apple Developer Documentation (2024)، XCFramework از تمام پلتفرم‌های اکوسیستم اپل پشتیبانی می‌کند: iOS، iPadOS، macOS، tvOS، watchOS، visionOS و برنامه‌های کاتالیست. هر پلتفرم یک برش جداگانه در داخل بسته دریافت می‌کند که تعارضات معماری را از بین می‌برد و توزیع SDK را ساده می‌کند.

چه زمانی به XCFramework نیاز است؟

XCFramework در سه سناریوی اصلی استفاده می‌شود: تحویل SDKهای بسته به توسعه‌دهندگان شخص ثالث، توزیع ماژول‌های بومی برای Flutter و React Native، و انتشار کتابخانه‌هایی که نیاز به کامپایل اولیه دارند. این قالب برای تمام SDKهای جدید منتشرشده در اکوسیستم اپل اجباری است.

توسعه‌دهندگان XCFramework را انتخاب می‌کنند وقتی کد منبع قابل افشا نیست، وقتی کتابخانه از الگوریتم‌های اختصاصی استفاده می‌کند یا وقتی حفاظت از مجوز مورد نیاز است. برخلاف Swift Package Manager که با کد منبع کار می‌کند، XCFramework فایل‌های باینری از پیش کامپایل‌شده را تحویل می‌دهد.

XCFramework چگونه مشکل باینری چاق را حل می‌کند؟

مشکل باینری چاق این بود که باینری جهانی شامل چندین معماری در یک فایل 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 به باینری چاق در داخل یک برش برای شبیه‌ساز اجازه می‌دهد — این تنها استثنایی است که باینری چاق توجیه‌پذیر است.

ساختار بسته 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 از اسکریپت شل استفاده می‌شود که ساخت زیر همه پلتفرم‌ها و ایجاد XCFramework را خودکار می‌کند. رویکرد محبوب یک پوسته به شکل Makefile یا لین Fastlane با پارامترسازی 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 — تحویل باینری، حفاظت از کد منبع، پشتیبانی از تمام پلتفرم‌های اپل در یک بسته
• SPM — کار با کد منبع باز، امکان بازرسی، کامپایل خودکار برای پلتفرم هدف
• وابستگی‌های باینری SPM از XCFramework به عنوان قالب بسته‌بندی استفاده می‌کنند و هر دو رویکرد را ترکیب می‌کنند

با انتشار Swift Package Manager 5.3، اپل پشتیبانی از وابستگی‌های باینری را اضافه کرد — اکنون SPM می‌تواند XCFramework را به عنوان یک وابستگی راه دور بارگیری کند. Package.swift URL را به مصنوع باینری و چک‌سام آن برای تأیید مشخص می‌کند.

بر اساس Swift Package Manager documentation (2024)، وابستگی‌های باینری برای SDKهایی که کد منبع را افشا نمی‌کنند یا برای کتابخانه‌هایی که ساخت آنها زمان نامتناسبی می‌برد توصیه می‌شود. برای پروژه‌های متن‌باز، تحویل با کد منبع از طریق SPM ترجیح داده می‌شود.