Bazel 教學課程：建構 Java 專案

本教學課程將介紹使用 Bazel 建構 Java 應用程式的基本概念。您將設定工作區，並建構簡單的 Java 專案，說明主要的 Bazel 概念，例如目標和 BUILD 檔案。

預估完成時間：30 分鐘。

課程內容

在本教學課程中，您將學習如何：

• 建構目標
• 以視覺化方式呈現專案的依附元件
• 將專案分割為多個目標和套件
• 控管各套件中的目標瀏覽權限
• 透過標籤參照目標
• 部署目標

事前準備

安裝 Bazel

如要準備教學課程，請先安裝 Bazel (如果尚未安裝)。

安裝 JDK

1. 安裝 Java JDK (建議版本為 11，但支援 8 到 15 之間的版本)。

2. 將 JAVA_HOME 環境變數設為指向 JDK。

   • 在 Linux/macOS 上：

     export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))"
     

   • Windows：

     1. 開啟控制台。
     2. 依序前往「系統和安全性」>「系統」>「進階系統設定」>「進階」分頁標籤 >「環境變數...」。
     3. 在「使用者變數」清單 (頂端) 下方，按一下「新增...」。
     4. 在「變數名稱」欄位中輸入 JAVA_HOME。
     5. 按一下「瀏覽目錄...」。
     6. 前往 JDK 目錄 (例如 C:\Program Files\Java\jdk1.8.0_152)。
     7. 在所有對話方塊中按一下「確定」。

取得範例專案

從 Bazel 的 GitHub 存放區擷取範例專案：

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

本教學課程的範例專案位於 examples/java-tutorial 目錄中，結構如下：

java-tutorial
├── BUILD
├── src
│   └── main
│       └── java
│           └── com
│               └── example
│                   ├── cmdline
│                   │   ├── BUILD
│                   │   └── Runner.java
│                   ├── Greeting.java
│                   └── ProjectRunner.java
└── WORKSPACE

使用 Bazel 建構

設定工作區

您必須先設定工作區，才能建構專案。工作區是一個目錄，用於儲存專案的來源檔案和 Bazel 的建構輸出內容。也包含 Bazel 視為特殊檔案的檔案：

• WORKSPACE 檔案：可將目錄及其內容識別為 Bazel 工作區，並位於專案目錄結構的根目錄中。

• 一或多個 BUILD 檔案，可告訴 Bazel 如何建構專案的不同部分。(工作區中包含 BUILD 檔案的目錄是套件。您將在本教學課程稍後的部分瞭解套件。)

如要將目錄指定為 Bazel 工作區，請在該目錄中建立名為 WORKSPACE 的空白檔案。

Bazel 建構專案時，所有輸入內容和依附元件都必須位於同一個工作區。位於不同工作區的檔案彼此獨立，除非連結檔案，否則不在本教學課程的討論範圍內。

瞭解 BUILD 檔案

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

請查看 java-tutorial/BUILD 檔案：

java_binary(
    name = "ProjectRunner",
    srcs = glob(["src/main/java/com/example/*.java"]),
)

在本範例中，ProjectRunner 目標會例項化 Bazel 內建的 java_binary 規則。這個規則會指示 Bazel 建構 .jar 檔案和包裝函式指令碼 (兩者都以目標命名)。

目標中的屬性會明確指出其依附元件和選項。name 屬性為必填，但許多屬性為選填。舉例來說，在 ProjectRunner 規則目標中，name 是目標的名稱，srcs 會指定 Bazel 用來建構目標的來源檔案，而 main_class 會指定包含主方法的類別。(您可能已經注意到，我們的範例使用 glob 將一組來源檔案傳遞至 Bazel，而非逐一列出這些檔案)。

建構專案

如要建構範例專案，請前往 java-tutorial 目錄並執行以下指令：

bazel build //:ProjectRunner

在目標標籤中，// 部分是 BUILD 檔案相對於工作區根目錄的位置 (在本例中為根目錄本身)，ProjectRunner 則是 BUILD 檔案中的目標名稱。(您將在本教學課程結尾處進一步瞭解目標標籤)。

Bazel 會產生類似以下的輸出內容：

   INFO: Found 1 target...
   Target //:ProjectRunner up-to-date:
      bazel-bin/ProjectRunner.jar
      bazel-bin/ProjectRunner
   INFO: Elapsed time: 1.021s, Critical Path: 0.83s

恭喜！您剛剛建構了第一個 Bazel 目標！Bazel 會將建構輸出內容放在工作區根目錄的 bazel-bin 目錄中。瀏覽內容，瞭解 Bazel 的輸出結構。

接著測試新建的二進位檔：

bazel-bin/ProjectRunner

查看依附元件圖

Bazel 要求建構依附元件必須在 BUILD 檔案中明確宣告。Bazel 會使用這些陳述式建立專案的相依關係圖，以便進行準確的增量建構作業。

如要將範例專案的依附元件視覺化，您可以在工作區根目錄中執行以下指令，產生依附元件圖表的文字表示法：

bazel query  --notool_deps --noimplicit_deps "deps(//:ProjectRunner)" --output graph

上述指令會指示 Bazel 尋找目標 //:ProjectRunner 的所有依附元件 (不含主機和隱含依附元件)，並將輸出內容格式化為圖表。

然後將文字貼到 GraphViz 中。

如您所見，專案只有一個目標，可建構兩個來源檔案，且沒有其他依附元件：

設定工作區、建構專案並檢查依附元件後，您就可以增加一些複雜性。

精進 Bazel 建構作業

雖然單一目標可滿足小型專案的需求，但您可能會想要將大型專案分割成多個目標和套件，以便快速進行增量建構作業 (也就是只重新建構變更的項目)，並一次建構專案的多個部分，加快建構作業。

指定多個建構目標

您可以將範例專案的建構作業分割為兩個目標。將 java-tutorial/BUILD 檔案的內容替換成以下內容：

java_binary(
    name = "ProjectRunner",
    srcs = ["src/main/java/com/example/ProjectRunner.java"],
    main_class = "com.example.ProjectRunner",
    deps = [":greeter"],
)

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
)

在這個設定中，Bazel 會先建構 greeter 程式庫，然後再建構 ProjectRunner 二進位檔。java_binary 中的 deps 屬性會告訴 Bazel，建構 ProjectRunner 二進位檔時需要 greeter 程式庫。

如要建構這個新版本的專案，請執行下列指令：

bazel build //:ProjectRunner

Bazel 會產生類似以下的輸出內容：

INFO: Found 1 target...
Target //:ProjectRunner up-to-date:
  bazel-bin/ProjectRunner.jar
  bazel-bin/ProjectRunner
INFO: Elapsed time: 2.454s, Critical Path: 1.58s

接著測試新建的二進位檔：

bazel-bin/ProjectRunner

如果現在修改 ProjectRunner.java 並重新建構專案，Bazel 只會重新編譯該檔案。

查看依附元件圖表，您會發現 ProjectRunner 依附的輸入內容與先前相同，但建構的結構不同：

您現在已建構含有兩個目標的專案。ProjectRunner 目標會建構兩個來源檔案，並依附另一個目標 (:greeter)，後者會建構另一個來源檔案。

使用多個套件

接下來，我們將專案分割成多個套件。查看 src/main/java/com/example/cmdline 目錄，您會發現它也包含 BUILD 檔案和一些來源檔案。因此，在 Bazel 中，工作區現在包含兩個套件：//src/main/java/com/example/cmdline 和 // (因為工作區的根目錄中有 BUILD 檔案)。

請查看 src/main/java/com/example/cmdline/BUILD 檔案：

java_binary(
    name = "runner",
    srcs = ["Runner.java"],
    main_class = "com.example.cmdline.Runner",
    deps = ["//:greeter"],
)

runner 目標依附於 // 套件中的 greeter 目標 (因此是目標標籤 //:greeter) - Bazel 會透過 deps 屬性瞭解這項資訊。請查看依附元件圖表：

不過，如果要成功進行建構作業，您必須使用 visibility 屬性，明確將 //src/main/java/com/example/cmdline/BUILD 中的 runner 目標顯示給 //BUILD 中的目標。這是因為根據預設，只有同一個 BUILD 檔案中的其他目標才能看到目標。(Bazel 會使用目標可見度，避免發生包含實作細節的程式庫外洩至公用 API 的問題)。

如要執行此操作，請在 java-tutorial/BUILD 中的 greeter 目標中新增 visibility 屬性，如下所示：

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
    visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
)

您現在可以在工作區根目錄中執行下列指令，建構新的套件：

bazel build //src/main/java/com/example/cmdline:runner

Bazel 會產生類似以下的輸出內容：

INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner.jar
  bazel-bin/src/main/java/com/example/cmdline/runner
  INFO: Elapsed time: 1.576s, Critical Path: 0.81s

接著測試新建的二進位檔：

./bazel-bin/src/main/java/com/example/cmdline/runner

您現在已修改專案，以便以兩個套件的形式進行建構，每個套件各包含一個目標，並瞭解兩者之間的依附元件。

使用標籤參照目標

在 BUILD 檔案和指令列中，Bazel 會使用目標標籤參照目標，例如 //:ProjectRunner 或 //src/main/java/com/example/cmdline:runner。語法如下：

//path/to/package:target-name

如果目標是規則目標，path/to/package 就是包含 BUILD 檔案的目錄路徑，而 target-name 則是您在 BUILD 檔案中指定的目標名稱 (name 屬性)。如果目標是檔案目標，path/to/package 就是套件根目錄的路徑，而 target-name 則是目標檔案的名稱，包括完整路徑。

當您參照存放區根層級的目標時，套件路徑會是空白，只要使用 //:target-name 即可。在同一個 BUILD 檔案中參照目標時，您甚至可以略過 // 工作區根 ID，只使用 :target-name。

舉例來說，如果是 java-tutorial/BUILD 檔案中的目標，您不必指定套件路徑，因為工作區根目錄本身就是套件 (//)，而兩個目標標籤只是 //:ProjectRunner 和 //:greeter。

不過，如果是 //src/main/java/com/example/cmdline/BUILD 檔案中的目標，您必須指定 //src/main/java/com/example/cmdline 的完整套件路徑，且目標標籤為 //src/main/java/com/example/cmdline:runner。

為部署作業套用 Java 目標

接下來，我們將使用所有執行階段依附元件建構二進位檔，以便封裝要部署的 Java 目標。這可讓您在開發環境之外執行二進位檔。

如您所知，java_binary 建構規則會產生 .jar 和包裝函式指令碼。使用下列指令查看 runner.jar 的內容：

jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar

內容如下：

META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class

如您所見，runner.jar 包含 Runner.class，但不包含其依附元件 Greeting.class。Bazel 產生的 runner 指令碼會將 greeter.jar 新增至 classpath，因此如果您保留這個狀態，指令碼會在本機執行，但不會在其他電腦上獨立執行。幸好，java_binary 規則可讓您建構可部署的獨立二進位檔。如要建構，請在目標名稱後方加上 _deploy.jar：

bazel build //src/main/java/com/example/cmdline:runner_deploy.jar

Bazel 會產生類似以下的輸出內容：

INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
INFO: Elapsed time: 1.700s, Critical Path: 0.23s

您剛建構 runner_deploy.jar，由於該應用程式包含所需的執行階段依附元件，因此您可以離開開發環境單獨執行該應用程式。請使用與先前相同的指令查看這個獨立 JAR 的內容：

jar tf bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar

內容包含執行所需的所有類別：

META-INF/
META-INF/MANIFEST.MF
build-data.properties
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class
com/example/Greeting.class

延伸閱讀

相關詳情請參閱：

• rules_jvm_external：用於管理傳遞 Maven 依附元件的規則。

• 外部依附元件，進一步瞭解如何使用本機和遠端存放區。

• 其他規則，進一步瞭解 Bazel。

• C++ 建構教學課程：開始使用 Bazel 建構 C++ 專案。

• Android 應用程式教學課程和 iOS 應用程式教學課程，以便開始使用 Bazel 建構 Android 和 iOS 行動應用程式。

祝您建構愉快！