2. Thiết lập dự án Xcode — tích hợp trực tiếp các xcframework

Ở đây không có bước hợp nhất manifest hay URL kho lưu trữ — bạn sẽ thêm thủ công hai framework nhị phân vào dự án Xcode (hoặc thông qua script thiết lập, nếu nhóm của bạn có sẵn).

2.1 Vị trí đặt các framework

Đặt AKSKit.xcframework và AppsKit.xcframework ngay trong thư mục chứa .xcodeproj — tức là cùng cấp với Podfile và thư mục mã nguồn của ứng dụng, không nằm trong thư mục mã nguồn hay trong Pods/. Điều này quan trọng vì Xcode phân giải tham chiếu đến framework bằng đường dẫn tương đối chỉ gồm tên framework (không cần tùy chỉnh FRAMEWORK_SEARCH_PATHS) — nếu bạn di chuyển chúng, tham chiếu trong tệp dự án sẽ không còn hợp lệ.

YourApp/                          <- CocoaPods project root (Podfile lives here)
├── Podfile
├── AKSKit.xcframework/            <- sibling of the .xcodeproj
├── AppsKit.xcframework/           <- sibling of the .xcodeproj
├── YourApp.xcodeproj/
├── YourApp.xcworkspace/           <- open THIS, not the .xcodeproj, once Pods are installed
└── YourApp/                       <- your app target's source folder
    ├── AppDelegate.swift
    └── ...

2.2 Thêm framework vào target

Trong Xcode, chọn target của ứng dụng → General → Frameworks, Libraries, and Embedded Content → thêm cả hai tệp .xcframework, rồi đặt Embed & Sign cho từng framework. Cụ thể, thao tác này cần tạo ra:

• một PBXFileReference cho mỗi framework với sourceTree = "<group>" và path chỉ gồm tên framework (không có tiền tố thư mục)
• cả hai framework được liệt kê trong Link Binary With Libraries (PBXFrameworksBuildPhase)
• cả hai framework được liệt kê trong giai đoạn build sao chép tệp Embed Frameworks (PBXCopyFilesBuildPhase, dstSubfolderSpec = 10) với các thuộc tính CodeSignOnCopy + RemoveHeadersOnCopy — đây chính là cấu hình được tạo khi chọn "Embed & Sign" trong giao diện Xcode

Đồng thời, hãy xác nhận LD_RUNPATH_SEARCH_PATHS có chứa @executable_path/Frameworks (Xcode tự động thêm giá trị này khi bạn nhúng framework qua giao diện; giá trị này cho phép tải các framework đã nhúng và ký khi ứng dụng chạy).

Nếu bạn dùng script thay vì giao diện Xcode (ví dụ: cho bước thiết lập CI), ba thành phần ở trên — tham chiếu tệp, giai đoạn liên kết và giai đoạn nhúng — chính là những gì bạn cần thêm vào project.pbxproj.

2.3 Mở workspace, không mở project

Sau khi chạy pod install, hãy mở YourApp.xcworkspace. Workspace này kết nối target của ứng dụng với Pods.xcodeproj do CocoaPods tạo; nếu mở trực tiếp .xcodeproj, quá trình build sẽ không liên kết đúng các thư viện phụ thuộc được khai báo trong Podfile.