2. Thiết lập dự án Xcode — thêm trực tiếp các xcframework vào dự án

Ở đâ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 dùng 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 trực tiếp trong cùng 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 đặt bên 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 framework bằng đường dẫn tương đối không có tiền tố thư mục (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 tệp. 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 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 bước 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 đã được 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 một bước thiết lập CI), ba thành phần ở trên — tham chiếu tệp, bước liên kết và bước 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 ra; nếu mở trực tiếp .xcodeproj riêng lẻ, quá trình build sẽ không liên kết đúng các phần phụ thuộc được khai báo trong Podfile.