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 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 đặ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 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 build phase sao chép tệp Embed Frameworks (PBXCopyFilesBuildPhase, dstSubfolderSpec = 10) với các thuộc tính CodeSignOnCopy + RemoveHeadersOnCopy — đây chính xác 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; nhờ đó, các framework đã nhúng và ký có thể được nạp khi ứng dụng chạy).

Nếu bạn dùng script thay vì giao diện Xcode (ví dụ: trong bước thiết lập CI), ba thành phần nêu trên — tham chiếu tệp, build phase liên kết và build phase 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, 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.