本頁說明如何使用 Bazel 建構或測試 Xcode 專案。本文說明 Xcode 和 Bazel 的差異，並提供將 Xcode 專案轉換為 Bazel 專案的步驟。並針對常見錯誤提供疑難排解解決方案。
Xcode 和 Bazel 的差異
Bazel 要求您明確指定每個建構目標及其依附元件，以及透過建構規則指定的對應建構設定。
Bazel 要求專案所依附的所有檔案都必須位於工作區目錄中，或在
MODULE.bazel檔案中指定為依附元件。使用 Bazel 建構 Xcode 專案時，
BUILD檔案會成為事實來源。如果您在 Xcode 中處理專案，更新BUILD檔案時，必須使用 rules_xcodeproj 產生與BUILD檔案相符的新版 Xcode 專案。對BUILD檔案進行特定變更 (例如將依附元件新增至目標) 時，不需要重新產生專案，因此可加快開發速度。如果您未使用 Xcode，bazel build和bazel test指令會提供建構和測試功能，但有某些限制，詳情請參閱本指南後續內容。
事前準備
開始之前，請先執行下列操作：
如果尚未安裝，請安裝 Bazel。
如果您不熟悉 Bazel 及其概念，請完成 iOS 應用程式教學課程。您應瞭解 Bazel 工作區，包括
MODULE.bazel和BUILD檔案，以及目標、建構規則和 Bazel 套件的概念。分析及瞭解專案的依附元件。
分析專案依附元件
與 Xcode 不同，Bazel 要求您在 BUILD 檔案中，明確宣告每個目標的所有依附元件。
如要進一步瞭解外部依附元件，請參閱「處理外部依附元件」。
使用 Bazel 建構或測試 Xcode 專案
如要使用 Bazel 建構或測試 Xcode 專案，請按照下列步驟操作：
-
a. 新增應用程式目標
b. (選用) 新增測試目標
c. 新增程式庫目標
步驟 1：建立 MODULE.bazel 檔案
在新目錄中建立 MODULE.bazel 檔案。這個目錄會成為 Bazel 工作區根目錄。如果專案未使用任何外部依附元件，這個檔案可以空白。如果專案依附於專案目錄以外的檔案或套件，請在 MODULE.bazel 檔案中指定這些外部依附元件。
步驟 2：(實驗功能) 整合 SwiftPM 依附元件
如要使用 swift_bazel 將 SwiftPM 依附元件整合至 Bazel 工作區，您必須按照下列教學課程的說明，將這些依附元件轉換為 Bazel 套件。
步驟 3：建立 BUILD 檔案
定義工作區和外部依附元件後，您需要建立 BUILD 檔案，告知 Bazel 專案結構。在 Bazel 工作區的根目錄建立 BUILD 檔案，並設定為專案的初始建構，如下所示：
提示：如要進一步瞭解套件和其他 Bazel 概念，請參閱「工作區、套件和目標」。
步驟 3a：新增應用程式目標
新增 macos_application 或 ios_application 規則目標。這個目標會分別建構 macOS 或 iOS 應用程式套件。在目標中，至少要指定下列項目：
bundle_id- 二進位檔的軟體包 ID (反向 DNS 路徑，後接應用程式名稱)。provisioning_profile- Apple Developer 帳戶的佈建設定檔 (如要為 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 建構時，MODULE.bazel 和 BUILD 檔案會成為建構作業的真值來源。如要讓 Xcode 瞭解這點，您必須使用 rules_xcodeproj
產生與 Bazel 相容的 Xcode 專案。
疑難排解
如果 Bazel 與所選 Xcode 版本不同步 (例如更新時)，可能會發生錯誤。如果 Xcode 發生錯誤 (例如「Xcode version must be specified to use an Apple CROSSTOOL」)，請嘗試下列做法。
手動執行 Xcode，並接受所有條款及細則。
使用 Xcode 選取工具指出正確版本、接受授權，並清除 Bazel 的狀態。
sudo xcode-select -s /Applications/Xcode.app/Contents/Developersudo xcodebuild -licensebazel sync --configure
- 如果這個方法無效，也可以嘗試執行
bazel clean --expunge。