本頁面由 Cloud Translation API 翻譯而成。

從 Xcode 遷移至 Bazel

回報問題查看來源

本頁說明如何使用 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 專案，請按照下列步驟操作：

建立 WORKSPACE 檔案
(實驗功能) 整合 SwiftPM 依附元件
建立 BUILD 檔案：

a. 新增應用程式目標

b. (選用) 新增測試目標

c. 新增程式庫目標
(選用) 將建構作業精細化
執行建構
使用 Rules_xcodeproj 產生 Xcode 專案

步驟 1：建立 `WORKSPACE` 檔案

在新目錄中建立 WORKSPACE 檔案。這個目錄會成為 Bazel 工作區根目錄。如果專案沒有使用外部依附元件，則這個檔案可以空白。如果專案依附的檔案或套件不在專案目錄中，請在 WORKSPACE 檔案中指定這些外部依附元件。

步驟 2：(實驗功能) 整合 SwiftPM 依附元件

如要將 SwiftPM 依附元件與 swift_bazel 整合到 Bazel 工作區，您必須按照以下教學課程中的說明，將這些依附元件轉換為 Bazel 套件。

步驟 3：建立 `BUILD` 檔案

定義工作區和外部依附元件後，您必須建立 BUILD 檔案來告知 Bazel 專案結構。在 Bazel 工作區的根目錄中建立 BUILD 檔案，並將其設為執行專案的初始建構作業，如下所示：

步驟 3a：新增應用程式目標
步驟 3b：(選用) 新增測試目標
步驟 3c：新增程式庫目標

提示：如要進一步瞭解套件和其他 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 建構規則支援在 iOS 和 macOS 上執行程式庫型單元測試，以及在 macOS 上執行應用程式測試。至於 iOS 上的應用程式測試，或任一平台上的 UI 測試，Bazel 會建構測試輸出內容，但必須在 Xcode 中透過規則_xcodeproj 產生的專案執行測試。新增測試目標，如下所示：

macos_unit_test：在 macOS 上執行程式庫和應用程式單元測試。
ios_unit_test：在 iOS 上執行程式庫式單元測試。針對需要 iOS 模擬器的測試，Bazel 會建構測試輸出內容，但不會執行測試。您必須使用 rules_xcodeproj 產生 Xcode 專案，然後從 Xcode 內執行測試。
ios_ui_test 可建構使用 Xcode 在 iOS 模擬工具中執行使用者介面測試所需的輸出內容。您必須使用 rules_xcodeproj 產生 Xcode 專案，然後從 Xcode 內執行測試。Bazel 無法原生執行 UI 測試。

請至少指定 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。