本頁說明如何使用 Bazel 建構或測試 Xcode 專案。本文會說明 Xcode 和 Bazel 之間的差異,並提供將 Xcode 專案轉換成 Bazel 專案的步驟。同時也提供排解常見錯誤的疑難排解解決方案。
Xcode 和 Bazel 的差異
Bazel 要求您明確指定每個建構目標及其依附元件,以及透過建構規則對應的建構設定。
Bazel 要求專案所需的所有檔案必須存在於工作區目錄中,或是在
WORKSPACE
檔案中指定為匯入項目。使用 Bazel 建構 Xcode 專案時,
BUILD
檔案會成為可靠資料來源。如果您在 Xcode 中處理專案,則必須在每次更新BUILD
檔案時,使用 Tulsi 產生與BUILD
檔案相符的新版 Xcode 專案。如果您並未使用 Xcode,bazel build
和bazel test
指令會提供建構和測試功能,但有本指南所述的特定限制。由於建構設定結構定義的差異 (例如目錄版面配置或建構旗標),Xcode 可能無法完全瞭解建構的「大型圖片」,因此部分 Xcode 功能可能無法運作。姓名:
視您在 Tulsi 中選取轉換的目標而定,Xcode 可能無法正確建立專案來源的索引。這會影響 Xcode 中的程式碼完成和導覽,因為 Xcode 無法查看專案的所有原始碼。
Bazel 不會產生 Xcode 預期這些功能的輸出內容,因此靜態分析、位址消化器和執行緒清理器可能無法正常運作。
如果您使用 Tulsi 產生 Xcode 專案,並在 Xcode 中使用該專案執行測試,Xcode 就會執行測試,而非 Bazel。如要使用 Bazel 執行測試,請手動執行
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:(實驗功能) 整合 CocoaPods 依附元件
如要將 CocoaPods 依附元件整合至 Bazel 工作區,請按照轉換 CocoaPods 依附元件一節的說明,將 CocoaPods 依附元件轉換為 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 建構規則支援在 iOS 和 macOS 上執行程式庫式單元測試,以及在 macOS 上執行應用程式型測試。針對在 iOS 或任一平台上的 UI 測試執行應用程式測試,Bazel 會建構測試輸出內容,但測試必須透過 Tulsi 產生的專案在 Xcode 中執行。新增測試目標,如下所示:
macos_unit_test
:在 macOS 上執行程式庫型和應用程式單元測試。ios_unit_test
可在 iOS 上執行程式庫式單元測試。對於需要 iOS 模擬器的測試,Bazel 會建構測試輸出內容,但不會執行測試。您必須使用 Tulsi 產生 Xcode 專案,然後在 Xcode 內執行測試。ios_ui_test
:建構所需的輸出內容,以便在使用 Xcode 在 iOS 模擬工具中執行使用者介面測試。您必須使用 Tulsi 產生 Xcode 專案,然後在 Xcode 內執行測試。Bazel 無法以原生方式執行 UI 測試。
請至少指定 minimum_os_version
屬性的值。雖然 bundle_identifier
和 infoplists
等其他封裝屬性預設為最常使用的值,但請確保這些預設值與專案相容,並視需要進行調整。如果是需要 iOS 模擬器的測試,請一併將 ios_application
目標名稱指定為 test_host
屬性的值。
步驟 3c:新增程式庫目標
為每個 目標 C 程式庫新增 objc_library
目標,並為應用程式和/或測試依附的每個 Swift 程式庫新增 swift_library
目標。
新增程式庫目標,如下所示:
將應用程式程式庫目標新增為應用程式目標的依附元件。
將測試程式庫目標新增為測試目標的依附元件。
在
srcs
屬性中列出實作來源。在
hdrs
屬性中列出標頭。
如要進一步瞭解建構規則,請參閱 Bazel 的 Apple 規則。
此時,建議您測試版本:
bazel build //:<application_target>
步驟 4:(選用) 劃分建構作業
如果專案較大或隨著規模成長,請考慮將其分割為多個 Bazel 套件。提高精細程度的好處如下:
提高建構成效增幅
增加建構工作的平行處理
提高日後使用者的可維護性
進一步控管目標和套件的原始碼瀏覽權限。這樣可以避免發生問題,例如含有實作詳細資料外洩到公用 API 的程式庫。
更精細的專案規模提示:
將每個程式庫放在專屬的 Bazel 套件中。從需要最少依附元件的項目開始,然後逐步執行依附元件樹狀結構。
當您新增
BUILD
檔案並指定目標時,請將這些新目標新增至依附於目標的deps
屬性。glob()
函式不會跨套件邊界,因此,隨著glob()
比對的檔案數量增加,則會縮減。在
main
目錄中新增BUILD
檔案時,請一併將BUILD
檔案新增至對應的test
目錄。對各個套件強制執行健康瀏覽權限限制。
請在每次對
BUILD
檔案有重大變更後建構專案,並在遇到建構錯誤時修正建構錯誤。
步驟 5:執行版本
執行完整遷移的版本,確認建構作業已完成,且沒有出現錯誤或警告。執行每個應用程式並個別測試目標,可更輕鬆地找出任何發生錯誤的來源。
例如:
bazel build //:my-target
步驟 6:使用 Tulsi 產生 Xcode 專案
使用 Bazel 進行建構時,WORKSPACE
和 BUILD
檔案會成為建構相關可靠資訊的來源。為確保 Xcode 能瞭解這一點,您必須使用 Tulsi 產生與 Bazel 相容的 Xcode 專案。
疑難排解
當 Bazel 版本與所選 Xcode 版本不同步時 (例如套用更新時),就會發生 Bazel 錯誤。如果您在使用 Xcode 時遇到錯誤,請嘗試以下做法,例如「必須指定 Xcode 版本才能使用 Apple CROSSTOOL」。
手動執行 Xcode 並接受任何條款及細則。
使用 Xcode Select 來指出正確的版本、接受授權並清除 Bazel 的狀態。
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license
bazel sync --configure
- 如果問題仍無法解決,您也可以嘗試執行
bazel clean --expunge
。