BazelCon 2024 註冊現已開放！

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

Bazel 教學課程：建構 Java 專案

回報問題查看原始碼 Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

預估完成時間：30 分鐘。

課程內容

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

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

事前準備

安裝 Bazel

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

安裝 JDK

安裝 Java JDK (建議版本為 11，但支援 8 到 15 之間的版本)。
將 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
└── MODULE.bazel

使用 Bazel 建構

設定工作區

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

MODULE.bazel 檔案：可將目錄及其內容識別為 Bazel 工作區，並位於專案目錄結構的根目錄中。
一或多個 BUILD 檔案，可告訴 Bazel 如何建構專案的不同部分。(工作區中包含 BUILD 檔案的目錄是套件。您將在本教學課程稍後的部分瞭解套件。)

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

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 中。

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

目標「ProjectRunner」的依附元件圖

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

精進 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」的依附元件圖

您現在已建構含有兩個目標的專案。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 屬性瞭解這項資訊。請查看依附元件圖表：

目標「runner」的依附元件圖

不過，如果要成功進行建構作業，您必須使用 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 行動應用程式。

祝您建構愉快！