簡介
第一次使用 Bazel 嗎?瀏覽 Google Ads 後,請按照這個 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 建構輸出內容的目錄。其中包含下列重要檔案:
會將目錄和內容識別為 Bazel 工作區,並位於專案目錄結構的根目錄中。WORKSPACE
file- 一或多個
,用於指示 Bazel 如何建構專案的不同部分。工作區中包含BUILD
filesBUILD
檔案的目錄是套件。(本教學課程稍後會進一步介紹套件)。
在日後的專案中,如要將目錄指定為 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 會先使用 Bazel 的內建 cc_library rule
建構 hello-greet
程式庫,然後再建構 hello-world
二進位檔。hello-world
目標中的 deps
屬性會告知 Bazel 需要 hello-greet
程式庫建構 hello-world
二進位檔。
您必須先變更目錄,並執行下列指令切換至 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 的其他規則,請參閱這份參考指南。
祝你建造愉快!