BazelCon 2024 註冊現已開放！

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

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

簡介

第一次使用 Bazel 嗎？您來對地方了。請按照這個「First Build」教學課程以簡化使用 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 檔案都需要至少一個 rule 做為一組指示，告訴 Bazel 如何建構所需的輸出內容，例如可執行的二進位檔或程式庫。這個模型中每個建構規則的執行個體 BUILD 檔案稱為目標並指向一組特定的來源檔案和dependencies。目標也可以指向其他目標。

請查看 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 階段的依附元件圖：

hello-world 的依附元件圖會顯示單一目標和單一來源檔案。

摘要：階段 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",
    ],
)

Bazel 會先利用這個 BUILD 檔案建構 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-world` 的依附元件圖會顯示修改檔案後的結構變更。

摘要：階段 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 目標取決於 hello-time 目標在 lib 套件中 (因此目標標籤 //lib:hello-time) - Bazel 知道透過 deps 屬性達成這個目的您可以在依附元件圖中看到這項資訊：

`hello-world` 的依附元件圖表會顯示主套件中的目標如何依附 `lib` 套件中的目標。

為了讓建構成功，您需要在 lib/BUILD 中進行 //lib:hello-time 目標使用瀏覽權限屬性在 main/BUILD 中的目標明確顯示。這是因為根據預設，只有同一個帳戶的其他目標才能查看 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 的其他規則，請參閱這份參考指南。

祝您建構愉快！