Bazel 教學課程：建構 C++ 專案

回報問題 查看來源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

簡介

第一次使用 Bazel 嗎？你來對地方了！請參閱這篇「第一個建構作業」教學課程，簡要瞭解如何使用 Bazel。本教學課程會定義 Bazel 環境中使用的重要術語，並逐步說明 Bazel 工作流程的基本概念。您將從所需工具開始，建構及執行三個難度漸增的專案，並瞭解專案難度提高的原因和方式。

Bazel 是支援多語言建構作業的建構系統，本教學課程以 C++ 專案為例，提供適用於大多數語言的一般指南和流程。

預計完成時間：30 分鐘。

必要條件

首先，請安裝 Bazel (如果尚未安裝)。本教學課程使用 Git 進行原始碼控管，因此建議您安裝 Git，以獲得最佳效果。

接下來，請在所選的指令列工具中執行下列指令，從 Bazel 的 GitHub 存放區擷取範例專案：

git clone https://github.com/bazelbuild/examples

本教學課程的範例專案位於 examples/cpp-tutorial 目錄中。

結構如下：

examples
└── cpp-tutorial
    ├──stage1
    │  ├── main
    │  │   ├── BUILD
    │  │   └── hello-world.cc
    │  └── WORKSPACE
    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE
    └──stage3
       ├── main
       │   ├── BUILD
       │   ├── hello-world.cc
       │   ├── hello-greet.cc
       │   └── hello-greet.h
       ├── lib
       │   ├── BUILD
       │   ├── hello-time.cc
       │   └── hello-time.h
       └── WORKSPACE

共有三組檔案，每組代表本教學課程中的一個階段。在第一階段，您將建構位於單一套件中的單一目標。在第二階段，您將從單一套件建構二進位檔和程式庫。在第三個也是最後一個階段，您將建立包含多個套件的專案，並以多個目標建構專案。

摘要：簡介

安裝 Bazel (和 Git) 並複製本教學課程的存放區後，您就已為使用 Bazel 進行首次建構奠定基礎。請繼續閱讀下一節，瞭解一些術語並設定工作區。

開始使用

設定工作區

您必須先設定專案的工作區，才能建構專案。工作區是保存專案來源檔案和 Bazel 建構輸出內容的目錄。此外，這個目錄也包含下列重要檔案：

• WORKSPACE file ，可將目錄及其內容識別為 Bazel 工作區，並位於專案目錄結構的根目錄。
• 一或多個 BUILD files ，用於告知 Bazel 如何建構專案的不同部分。工作區中含有 BUILD 檔案的目錄就是「套件」。(本教學課程稍後會詳細說明套件)。

在日後的專案中，如要將目錄指定為 Bazel 工作區，請在該目錄中建立名為 WORKSPACE 的空白檔案。為達到本教學課程的目的，每個階段都已提供 WORKSPACE 檔案。

注意：Bazel 建構專案時，所有輸入內容都必須位於同一個工作區。除非連結，否則不同工作區中的檔案彼此獨立。如要進一步瞭解工作區規則，請參閱這份指南。

瞭解 BUILD 檔案

BUILD 檔案包含多種 Bazel 指令。每個 BUILD 檔案都至少需要一組規則做為指令，告訴 Bazel 如何建構所需的輸出內容，例如可執行的二進位檔或程式庫。BUILD 檔案中的每個建構規則例項都稱為「目標」，並指向一組特定的來源檔案和「依附元件」。目標也可以指向其他目標。

請看看 cpp-tutorial/stage1/main 目錄中的 BUILD 檔案：

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)

在本例中，hello-world 目標會例項化 Bazel 的內建 cc_binary rule。這項規則會告知 Bazel 從 hello-world.cc 來源檔案建構獨立的可執行二進位檔，且不含任何依附元件。

摘要：開始使用

您現在已熟悉一些重要術語，以及這些術語在這個專案和一般 Bazel 中的意義。在下一節中，您將建構及測試專案的第 1 階段。

第 1 階段：單一目標、單一套件

現在可以開始建構專案的第一部分。如需視覺參考資料，專案第 1 階段部分的結構如下：

examples
└── cpp-tutorial
    └──stage1
       ├── main
       │   ├── BUILD
       │   └── hello-world.cc
       └── WORKSPACE

執行下列指令，移至 cpp-tutorial/stage1 目錄：

cd cpp-tutorial/stage1

接著執行：

bazel build //main:hello-world

在目標標籤中，//main: 部分是 BUILD 檔案相對於工作區根目錄的位置，而 hello-world 是 BUILD 檔案中的目標名稱。

Bazel 會產生類似下列內容的項目：

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.267s, Critical Path: 0.25s

您剛剛建構了第一個 Bazel 目標。Bazel 會將建構輸出內容放在工作區根目錄的 bazel-bin 目錄中。

現在測試剛建構的二進位檔，也就是：

bazel-bin/main/hello-world

這樣就會列印出「Hello world」訊息。

以下是第 1 階段的依附元件圖表：

摘要：第 1 階段

您已完成第一個建構作業，現在對建構作業的結構有基本概念。在下一個階段，您將新增另一個目標，增加複雜度。

第 2 階段：多個建構目標

小型專案只要一個目標就夠了，但您可能想將大型專案拆分成多個目標和套件。這樣就能快速進行漸進式建構 (也就是 Bazel 只會重建變更的內容)，並同時建構專案的多個部分，加快建構速度。本教學課程的這一階段會新增目標，下一階段則會新增套件。

這是您在第 2 階段使用的目錄：

    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE

請參閱下方 cpp-tutorial/stage2/main 目錄中的 BUILD 檔案：

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
    ],
)

有了這個 BUILD 檔案，Bazel 會先建構 hello-greet 程式庫 (使用 Bazel 的內建 cc_library rule)，然後建構 hello-world 二進位檔。hello-world 目標中的 deps 屬性會告知 Bazel，建構 hello-world 二進位檔時需要 hello-greet 程式庫。

如要建構這個新版專案，請先變更目錄，切換至 cpp-tutorial/stage2 目錄並執行下列指令：

cd ../stage2

現在，您可以使用下列常見指令建構新的二進位檔：

bazel build //main:hello-world

Bazel 會再次產生類似下列內容的項目：

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.399s, Critical Path: 0.30s

現在可以測試剛建構的二進位檔，該檔案會傳回另一個「Hello world」：

bazel-bin/main/hello-world

如果您現在修改 hello-greet.cc 並重建專案，Bazel 只會重新編譯該檔案。

查看依附元件圖表，您會發現 hello-world 依附於名為 hello-greet 的額外輸入內容：

摘要：第 2 階段

您現在已建構專案，並包含兩個目標。hello-world 目標會建構一個來源檔案，並依附於另一個目標 (//main:hello-greet)，該目標會建構兩個額外的來源檔案。在下一節中，我們將進一步新增另一個套件。

第 3 階段：多個套件

下一個階段會增加複雜度，並使用多個套件建構專案。請參閱下方的 cpp-tutorial/stage3 目錄結構和內容：

└──stage3
   ├── main
   │   ├── BUILD
   │   ├── hello-world.cc
   │   ├── hello-greet.cc
   │   └── hello-greet.h
   ├── lib
   │   ├── BUILD
   │   ├── hello-time.cc
   │   └── hello-time.h
   └── WORKSPACE

您可以看到現在有兩個子目錄，且每個子目錄都包含 BUILD 檔案。因此，對 Bazel 而言，工作區現在包含兩個套件：lib 和 main。

查看 lib/BUILD 檔案：

cc_library(
    name = "hello-time",
    srcs = ["hello-time.cc"],
    hdrs = ["hello-time.h"],
    visibility = ["//main:__pkg__"],
)

在 main/BUILD 檔案中：

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
        "//lib:hello-time",
    ],
)

主要套件中的 hello-world 目標依附於 lib 套件中的 hello-time 目標 (因此目標標籤為 //lib:hello-time) - Bazel 會透過 deps 屬性瞭解這點。您可以在依附元件圖表中看到這點：

如要成功建構，請使用可見度屬性，讓 main/BUILD 中的目標明確看到 lib/BUILD 中的 //lib:hello-time 目標。這是因為根據預設，只有相同 BUILD 檔案中的其他目標才能看到目標。Bazel 會使用目標可見度來避免問題，例如含有實作詳細資料的程式庫洩漏到公開 API 中。

現在建構這個專案的最終版本。執行下列指令，切換至 cpp-tutorial/stage3 目錄：

cd  ../stage3

再次執行下列指令：

bazel build //main:hello-world

Bazel 會產生類似下列內容的項目：

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 0.167s, Critical Path: 0.00s

現在測試本教學課程的最後一個二進位檔，確認是否出現最終的 Hello world 訊息：

bazel-bin/main/hello-world

摘要：第 3 階段

您現在已將專案建構為兩個套件，其中包含三個目標，並瞭解這些目標之間的依附元件，因此可以繼續使用 Bazel 建構未來的專案。下一節將說明如何繼續 Bazel 學習之旅。

後續步驟

您已完成第一個 Bazel 基本建構作業，但這只是開始。以下提供更多資源，協助您繼續學習 Bazel：

• 如要繼續瞭解 C++，請參閱常見的 C++ 建構用途。
• 如要開始使用 Bazel 建構其他應用程式，請參閱 Java、Android 應用程式或 iOS 應用程式的教學課程。
• 如要進一步瞭解如何處理本機和遠端存放區，請參閱「外部依附元件」一文。
• 如要進一步瞭解 Bazel 的其他規則，請參閱這份參考指南。

祝您建構愉快！