本頁說明如何使用 Bazel 建構或測試 Xcode 專案。說明 Xcode 和 Bazel 之間的差異,並提供將 Xcode 專案轉換成 Bazel 專案的步驟。此外,也提供解決常見錯誤的疑難排解解決方案。
Xcode 和 Bazel 之間的差異
Bazel 會要求您明確指定每個建構目標及其依附元件,以及透過建構規則對應的建構設定。
Bazel 要求專案依附的所有檔案必須位於工作區目錄,或是指定為
WORKSPACE
檔案的匯入作業。使用 Bazel 建構 Xcode 專案時,
BUILD
檔案會成為可靠資料來源。如果您使用 Xcode 中的專案,每次更新BUILD
檔案時,都必須使用 rules_xcodeproj 產生與BUILD
檔案相符的新版 Xcode 專案。對BUILD
檔案進行某些變更 (例如將依附元件新增至目標) 不需要重新產生專案,可加快開發速度。如果您並未使用 Xcode,bazel build
和bazel test
指令提供的建構和測試功能會受到本指南稍後說明的特定限制。
事前準備
開始之前,請先執行下列操作:
如果您尚未安裝 Bazel,請先完成安裝。
如果您不熟悉 Bazel 及其概念,請完成 iOS 應用程式教學課程。您應瞭解 Bazel 工作區,包括
WORKSPACE
和BUILD
檔案,以及目標、建構規則和 Bazel 套件的概念。分析並瞭解專案的依附元件。
分析專案依附元件
與 Xcode 不同的是,Bazel 會要求您為 BUILD
檔案中每個目標明確宣告所有依附元件。
如要進一步瞭解外部依附元件,請參閱「使用外部依附元件」。
使用 Bazel 建構或測試 Xcode 專案
如要使用 Bazel 建構或測試 Xcode 專案,請按照下列步驟操作:
-
a. 新增應用程式目標
b. (選用) 新增測試目標
c. 新增程式庫目標
步驟 1:建立 WORKSPACE
檔案
在新目錄中建立 WORKSPACE
檔案。這個目錄會成為 Bazel 工作區根目錄。如果專案沒有使用外部依附元件,則這個檔案可以空白。如果專案依附的檔案或套件不在專案目錄中,請在 WORKSPACE
檔案中指定這些外部依附元件。
步驟 2:(實驗功能) 整合 SwiftPM 依附元件
如要將 SwiftPM 依附元件與 swift_bazel 整合到 Bazel 工作區,您必須按照以下教學課程中的說明,將這些依附元件轉換為 Bazel 套件。
步驟 3:建立 BUILD
檔案
定義工作區和外部依附元件後,您必須建立 BUILD
檔案來告知 Bazel 專案結構。在 Bazel 工作區的根目錄中建立 BUILD
檔案,並將其設為執行專案的初始建構作業,如下所示:
提示:如要進一步瞭解套件和其他 Bazel 概念,請參閱工作區、套件與目標一文。
步驟 3a:新增應用程式目標
新增 macos_application
或 ios_application
規則目標。這個目標會分別建構 macOS 或 iOS 應用程式套件。在目標中,至少指定下列項目:
bundle_id
:二進位檔的軟體包 ID (反向 DNS 路徑,後接應用程式名稱)。provisioning_profile
- 從 Apple 開發人員帳戶 (若為 iOS 裝置建構) 佈建設定檔。families
(僅限 iOS) - 是否建構適用於 iPhone、iPad 或兩者的應用程式。infoplists
- 要合併到最終 Info.plist 檔案的 .plist 檔案清單。minimum_os_version
:應用程式支援的 macOS 或 iOS 最低版本。這可確保 Bazel 使用正確的 API 級別建構應用程式。
步驟 3b:(選用) 新增測試目標
Bazel 的 Apple 建構規則支援在所有 Apple 平台上執行單元和 UI 測試。新增測試目標,如下所示:
macos_unit_test
:在 macOS 上執行程式庫和應用程式單元測試。ios_unit_test
:在 iOS 上建構及執行以程式庫為基礎的單元測試。ios_ui_test
:在 iOS 模擬器中建構及執行使用者介面測試。
請至少指定 minimum_os_version
屬性的值。雖然其他封裝屬性 (例如 bundle_identifier
和 infoplists
) 預設為最常用的值,但請確保這些預設值與專案相容,並視情況調整。如果是需要 iOS 模擬器的測試,請一併將 ios_application
目標名稱指定為 test_host
屬性的值。
步驟 3c:新增程式庫目標
為每個 Objective-C 程式庫新增 objc_library
目標,以及為應用程式和/或測試依附的每個 Swift 程式庫,並新增 swift_library
目標。
新增資料庫目標如下:
將應用程式程式庫目標新增為應用程式目標的依附元件。
將測試程式庫目標新增為測試目標的依附元件。
在
srcs
屬性中列出實作來源。請在
hdrs
屬性中列出標頭。
您可以直接在 rules_apple 範例目錄中瀏覽各種應用程式的現有範例。例如:
如要進一步瞭解建構規則,請參閱 Bazel 的 Apple 規則。
此時,建議您測試版本:
bazel build //:<application_target>
步驟 4:(選用) 將建構進行精細化
如果專案很大,或是專案規模增加,請考慮將專案分割為多個 Bazel 套件。這麼做可提升精細程度,帶來以下好處:
增加版本增幅
提高建構工作的平行處理能力,
日後使用者更容易維護
更有效地控管目標和套件中的原始碼。這可避免程式庫包含實作詳細資料外洩至公用 API 的問題。
將專案精細化的訣竅:
將每個程式庫都放在專屬的 Bazel 套件中。請先從需要最少依附元件的項目開始,然後向上擴充依附元件樹狀結構。
新增
BUILD
檔案並指定目標時,請將這些新的目標新增至依附目標的deps
屬性。glob()
函式不會跨套件邊界,因此隨著套件數量增加,glob()
比對相符的檔案會縮減。將
BUILD
檔案新增至main
目錄時,請一併新增BUILD
檔案至對應的test
目錄。在所有套件中強制執行健康的瀏覽權限限制。
每次對
BUILD
檔案進行重大變更之後,請建構專案,並在遇到建構錯誤時一併修正。
步驟 5:執行版本
執行完整遷移的建構作業,確保完成時沒有錯誤或警告。分別執行每個應用程式和測試目標,更容易找出任何錯誤的來源。
例如:
bazel build //:my-target
步驟 6:使用 rules_xcodeproj 產生 Xcode 專案
使用 Bazel 建構時,WORKSPACE
和 BUILD
檔案會成為建構作業的可靠資料來源。如要告知 Xcode 這一點,您必須使用 rules_xcodeproj 產生與 Bazel 相容的 Xcode 專案。
疑難排解
如果 Bazel 錯誤與所選 Xcode 版本未同步,例如套用更新時,就會發生 Bazel 錯誤。如果使用 Xcode 時發生錯誤,可採取以下做法,例如「必須指定 Xcode 版本,才能使用 Apple CROSSTOOL」。
手動執行 Xcode 並接受所有條款及細則。
使用 Xcode 選取表示正確版本、接受授權,並清除 Bazel 的狀態。
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license
bazel sync --configure
- 如果這個方法無效,也可以嘗試執行
bazel clean --expunge
。