XCFramework: ما هو، تنسيق التوزيع الثنائي وتطبيقه

ما هو XCFramework؟

XCFramework هو تنسيق لتغليف المكتبات الثنائية والأطر، قدمته Apple في WWDC 2019. الهدف الرئيسي هو إنشاء حزمة واحدة تحتوي على إصدارات مترجمة من المكتبة لجميع المنصات والبُنى المستهدفة.

قبل XCFramework، كان المطورون يستخدمون .framework مع الثنائيات الضخمة التي تدمج بُنى متعددة عبر أداة lipo. تسبب هذا النهج في مشاكل: عند بناء مشروع للمحاكي، كان الثنائي الضخم يحتوي على بنية المحاكي والجهاز معاً، مما أدى إلى أخطاء عند إرسال البناء إلى App Store. كان على المطورين كتابة مراحل Run Script لإزالة البنى غير الضرورية.

وفقاً لوثائق مطوري Apple (2024)، يدعم XCFramework جميع منصات نظام Apple البيئي: iOS وiPadOS وmacOS وtvOS وwatchOS وvisionOS وتطبيقات Catalyst. كل منصة تحصل على شريحة منفصلة داخل الحزمة، مما يلغي تعارضات البنى ويبسط توزيع SDK.

متى تحتاج XCFramework؟

يُستخدم XCFramework في ثلاثة سيناريوهات رئيسية: توزيع SDK مغلقة المصدر لمطورين خارجيين، توزيع وحدات أصلية لـ Flutter وReact Native، ونشر المكتبات التي تتطلب تجميعاً مسبقاً. التنسيق إلزامي لجميع SDK الجديدة المنشورة في نظام Apple البيئي.

يختار المطورون 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 لدعم Macs ذات Apple Silicon. سابقاً، كان المحاكي يتطلب ثنائياً منفصلاً لـ 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 flags) القياسية لـ Xcode.

# 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 في Xcode 11. يقوم الأمر تلقائياً بإنشاء هيكل الدليل الصحيح ويولد Info.plist مع وصف لجميع المنصات. إذا كان أحد ملفات .framework تالفاً أو مبنيّاً ببنية خاطئة، يُصدر xcodebuild خطأً في مرحلة التحقق.

الأتمتة عبر نصوص البناء

لـ CI/CD، يُستخدم نص شل (shell script) لأتمتة البناء لجميع المنصات وإنشاء XCFramework. النهج الشائع هو غلاف على شكل Makefile أو Fastlane lane مع وسائط لـ scheme ومسار الإخراج.

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

يتم تنفيذ هذا النص في خط أنابيب 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 resolves the correct slice at build time
    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 (2024)، يُوصى باستخدام التبعيات الثنائية لـ SDK التي لا تكشف عن كود المصدر، أو للمكتبات التي يستغرق بناؤها وقتاً غير متناسب. لمشاريع المصدر المفتوح، يُفضل توزيع كود المصدر عبر SPM.