Bazel 專案版面配置和機構

Bazel 專案

Bazel 專案是一組來源和建構檔案，用於說明：

• 如何建構構件 (例如二進位檔或資料檔案) 及其依附元件。
• 如何執行特定指令，也就是指令碼或可執行檔。
• 如何測試上述建構構件。

Bazel 專案會透過「頂層目錄」具體化，其內容遵循「特定版面配置」和「慣例」。

Bazel 工作區

Bazel 工作區是目錄樹，內含頂層 WORKSPACE.bazel¹ 檔案。這會定義來源集合和相關建構檔案的根目錄。Bazel 專案可以使用多個工作區：

• 專案的根目錄稱為「根工作區」，因此必須包含 WORKSPACE.bazel 檔案。

• 專案也可以參照其他工作區，稱為外部 存放區，對應至第三方專案依附元件。

舉例來說，在：

/home/user/project/
    WORKSPACE.bazel
    src/
        BUILD.bazel
        extra/
            extra.cc
        lib/
            BUILD.bazel
            foo.cc
            foo.h
        main.cc

目錄 /home/user/project 是根 Bazel 工作區，其中包含所有檔案。

WORKSPACE.bazel 檔案可以空白，但也可以包含參照其他工作區的指令，詳情請見下文。

Bazel 套件

在工作區中，含有 BUILD.bazel² 檔案的目錄會定義套件，也就是 Bazel 知道的一組來源檔案和項目周圍的界線。

舉例來說，這個檔案版面配置：

/home/user/project/
  WORKSPACE.bazel
  BUILD.bazel
  main.cc

定義根工作區，位於 /home/user/project，其中包含單一頂層套件，內含 BUILD.bazel 和 main.cc 檔案。

BUILD.bazel 檔案也可以包含指令，定義具名項目，例如目標、設定條件等，這些項目在技術上也屬於套件。

單一工作區中可以有多個套件，且每個檔案只能屬於一個套件。舉例來說，如果檔案結構如下：

/home/user/project/
  WORKSPACE.bazel
  BUILD.bazel
  main.cc
  lib/
    BUILD.bazel
    foo.cc

根工作區包含兩個不同的套件：

• 頂層套件，其中仍包含 BUILD.bazel 和 main.cc 檔案 (相對於根工作區目錄)。

• 第二個套件，內含 lib/BUILD.bazel 和 lib/foo.cc 檔案。

請注意，/home/user/project/lib/foo.cc 的檔案只屬於第二個套件，不屬於第一個套件。這是因為套件 邊界 絕不會 重疊。

BUILD.bazel對BUILD

Bazel 源自 Google 的 Blaze，後者只能在 Linux 上運作，且檔案系統會區分大小寫。Blaze 只會使用 BUILD 檔案名稱儲存建構指令。

不過，Bazel 也需要在 Windows 上執行，而 Windows 具有不區分大小寫的檔案系統。許多 Google 或非 Google 專案已使用名為「build」的目錄，這會與這類系統上名為「BUILD」的檔案發生衝突。

為解決這個問題，Bazel 會使用 BUILD.bazel 和 WORKSPACE.bazel 做為預設檔案名稱，同時仍支援 BUILD 和 WORKSPACE 做為備援。

工作區指令

根 WORKSPACE.bazel 可以是空白，也可以包含參照其他 Bazel 工作區的指令，這些工作區稱為外部存放區。這些指令一律會為存放區命名。例如：

local_repository(
  name = "my_ssl",
  path = "/home/user/src/openssl-bazel",
)

將名稱 my_ssl 與建構電腦上 /home/user/src/openssl-bazel 的工作區建立關聯。這個目錄也必須包含 WORKSPACE.bazel (或 WORKSPACE) 檔案。

存放區只是具有名稱的外部 Bazel 工作區。這個名稱是專案的本機名稱，稍後可用於參照外部工作區中的項目 (請參閱下文)。

Bazel 也支援其他指令，可從網路下載存放區，甚至以程式輔助方式產生內容。

Bazel 標籤

如要瞭解 Bazel 標籤，請參閱這個頁面。

Bazel 擴充功能 (.bzl) 檔案

如要瞭解 Bazel 擴充功能檔案，請參閱這個頁面。