XCFramework: nó là gì, định dạng phân phối nhị phân và ứng dụng

XCFramework là gì?

XCFramework là định dạng đóng gói cho thư viện nhị phân và framework được Apple giới thiệu tại WWDC 2019. Mục tiêu chính là tạo một bundle duy nhất chứa các phiên bản đã biên dịch của thư viện cho tất cả các nền tảng và kiến trúc mục tiêu.

Trước XCFramework, các nhà phát triển sử dụng .framework với fat binary kết hợp nhiều kiến trúc qua tiện ích lipo. Phương pháp này gây ra vấn đề: khi xây dựng dự án cho trình mô phỏng, fat binary chứa cả kiến trúc trình mô phỏng và thiết bị, dẫn đến lỗi khi gửi bản dựng lên App Store. Các nhà phát triển phải viết các giai đoạn Run Script để xóa các kiến trúc không cần thiết.

Theo Tài liệu dành cho Nhà phát triển Apple (2024), XCFramework hỗ trợ tất cả các nền tảng trong hệ sinh thái Apple: iOS, iPadOS, macOS, tvOS, watchOS, visionOS và ứng dụng Catalyst. Mỗi nền tảng nhận một slice riêng biệt bên trong gói, loại bỏ xung đột kiến trúc và đơn giản hóa việc phân phối SDK.

Khi nào cần XCFramework?

XCFramework được sử dụng trong ba kịch bản chính: phân phối SDK đóng cho nhà phát triển bên thứ ba, phân phối mô-đun gốc cho Flutter và React Native, và xuất bản thư viện yêu cầu biên dịch trước. Định dạng này là bắt buộc đối với tất cả SDK mới được xuất bản trong hệ sinh thái Apple.

Các nhà phát triển chọn XCFramework khi không thể tiết lộ mã nguồn, khi thư viện sử dụng thuật toán độc quyền hoặc khi cần bảo vệ bản quyền. Không giống như Swift Package Manager làm việc với mã nguồn, XCFramework phân phối các tệp nhị phân đã được biên dịch sẵn.

XCFramework giải quyết vấn đề fat binary như thế nào?

Vấn đề fat binary là một nhị phân phổ quát chứa nhiều kiến trúc trong một tệp Mach-O duy nhất. Khi xây dựng ứng dụng cho trình mô phỏng, Xcode bao gồm cả kiến trúc thiết bị arm64 và kiến trúc trình mô phỏng x86_64 — App Store chỉ chấp nhận kiến trúc thiết bị.

Giải pháp truyền thống bao gồm việc thêm giai đoạn Run Script gọi lipo để xóa kiến trúc trình mô phỏng khỏi bản dựng cuối cùng. Phương pháp này mong manh và hỏng khi cập nhật Xcode hoặc khi có kiến trúc mới (ví dụ: arm64 cho trình mô phỏng trên Apple Silicon).

Theo Swift.org (2023), nhóm Swift Package Manager ban đầu gặp phải vấn đề này khi cố gắng hỗ trợ các phụ thuộc nhị phân. XCFramework đã giải quyết nó ở cấp độ định dạng: mỗi slice là một thư mục riêng biệt với Info.plist mô tả nền tảng và kiến trúc mục tiêu. Xcode tự động chọn slice cần thiết khi xây dựng mà không yêu cầu xử lý hậu kỳ.

Lợi ích của phương pháp slice riêng biệt

Mỗi slice trong XCFramework chỉ chứa một tổ hợp nền tảng-kiến trúc duy nhất. Ví dụ: ios-arm64 chứa nhị phân chỉ dành cho thiết bị iOS và ios-x86_64-simulator chỉ dành cho trình mô phỏng Intel Mac. Xcode tự động chọn slice chính xác, loại bỏ nhu cầu về script xóa kiến trúc và giảm rủi ro lỗi xây dựng.

Slice ios-arm64-x86_64-simulator được giới thiệu để hỗ trợ Mac Apple Silicon. Trước đây, trình mô phỏng yêu cầu nhị phân riêng cho arm64 (Apple Silicon) và x86_64 (Intel). XCFramework cho phép fat binary bên trong một slice trình mô phỏng duy nhất — đây là ngoại lệ duy nhất mà fat binary được chấp nhận.

Cấu trúc gói XCFramework

Gói XCFramework là một thư mục có phần mở rộng .xcframework, chứa Info.plist ở cấp trên cùng và các thư mục với slice nhị phân. Mỗi slice bao gồm thư viện .framework hoặc .a cho một nền tảng cụ thể.

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 của gói chứa khóa AvailableLibraries, liệt kê LibraryIdentifier, LibraryPath và SupportedPlatform cho mỗi slice. Xcode đọc tệp này khi thêm XCFramework vào dự án và tự động cấu hình đường dẫn tìm kiếm và giai đoạn Embed Frameworks.

Mỗi slice là một .framework hoàn chỉnh hoặc thư viện tĩnh với Info.plist riêng. Điều này cho phép XCFramework hỗ trợ các loại hỗn hợp: thư viện tĩnh cho một số nền tảng và framework động cho các nền tảng khác, mặc dù trong thực tế một loại được sử dụng cho tất cả các slice.

Tạo XCFramework từ dòng lệnh

Việc tạo XCFramework được thực hiện qua xcodebuild -create-xcframework. Lệnh nhận các thư viện .framework hoặc .a đã được xây dựng cho mỗi nền tảng và kết hợp chúng thành một gói duy nhất.

Quy trình gồm hai bước: đầu tiên, nhị phân được xây dựng cho mỗi nền tảng mục tiêu, sau đó chúng được đóng gói thành XCFramework. Để xây dựng, các cờ destination tiêu chuẩn của Xcode được sử dụng.

# 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

Cờ -create-xcframework được giới thiệu trong Xcode 11. Lệnh tự động tạo cấu trúc thư mục chính xác và tạo Info.plist với mô tả của tất cả các nền tảng. Nếu một trong các .framework bị hỏng hoặc được xây dựng với kiến trúc sai, xcodebuild đưa ra lỗi ở giai đoạn xác thực.

Tự động hóa qua script xây dựng

Đối với CI/CD, một script shell được sử dụng để tự động hóa việc xây dựng cho tất cả các nền tảng và tạo XCFramework. Một phương pháp phổ biến là trình bao bọc dưới dạng Makefile hoặc Fastlane lane với tham số hóa scheme và đường dẫn đầu ra.

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

Script như vậy chạy trong đường ống CI (GitHub Actions, Bitrise, Jenkins) sau khi vượt qua kiểm thử. XCFramework kết quả được lưu trữ và tải lên như một artifact phát hành hoặc được xuất bản qua trình quản lý phụ thuộc như CocoaPods bằng pod spec.

Tích hợp XCFramework vào dự án Xcode

Tích hợp XCFramework vào dự án Xcode không yêu cầu cấu hình thủ công đường dẫn tìm kiếm. Chỉ cần kéo .xcframework vào phần Frameworks, Libraries, and Embedded Content trong cài đặt General của target.

Không giống như .framework, XCFramework không yêu cầu thêm giai đoạn Run Script để xóa kiến trúc trình mô phỏng. Xcode tự động xác định các slice có sẵn và chỉ bao gồm những slice cần thiết cho lược đồ xây dựng hiện tại. Đối với thiết bị vật lý, slice ios-arm64 được sử dụng; cho trình mô phỏng — ios-arm64-x86_64-simulator hoặc 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)
}

Đối với CocoaPods, tích hợp được thực hiện qua podspec với vendored_frameworks và danh sách các nền tảng được hỗ trợ. Trình quản lý phụ thuộc tự động xác định slice nào cần thiết cho dự án. Nhiều SDK thương mại — Firebase, Adjust, AppsFlyer — đã chuyển sang XCFramework để đơn giản hóa việc cài đặt.

So sánh XCFramework và Swift Package Manager

Swift Package Manager và XCFramework không cạnh tranh mà bổ sung cho nhau. SPM làm việc với mã nguồn và biên dịch các phụ thuộc ở mỗi lần xây dựng dự án. XCFramework cung cấp nhị phân sẵn sàng mà không yêu cầu biên dịch phía người tiêu dùng.

• XCFramework — phân phối nhị phân, bảo vệ mã nguồn, hỗ trợ tất cả nền tảng Apple trong một gói
• SPM — làm việc với mã nguồn mở, khả năng kiểm tra, xây dựng tự động cho nền tảng mục tiêu
• Phụ thuộc nhị phân SPM sử dụng XCFramework làm định dạng đóng gói, kết hợp cả hai phương pháp

Với việc phát hành Swift Package Manager 5.3, Apple đã thêm hỗ trợ cho phụ thuộc nhị phân — hiện tại SPM có thể tải xuống XCFramework như một phụ thuộc từ xa. Package.swift chỉ định URL của artifact nhị phân và checksum của nó để xác minh.

Theo tài liệu Swift Package Manager (2024), phụ thuộc nhị phân được khuyến nghị cho SDK không tiết lộ mã nguồn hoặc cho thư viện có thời gian xây dựng dài không tương xứng. Đối với dự án mã nguồn mở, phân phối mã nguồn qua SPM được ưu tiên.