如需穩定版說明文件，請使用「版本化文件」下拉式選單。預設檢視會反映位於 HEAD 的最新版本。

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

Bazel 教學課程：建構 Java 專案

回報問題查看來源

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

預計完成時間：30 分鐘。

課程內容

在本教學課程中，您會瞭解如何：

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

事前準備

安裝 Bazel

如果您尚未安裝 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 需要 greeter 程式庫才能建構 ProjectRunner 二進位檔。

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

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 的程式庫)。

方法是將 visibility 屬性新增至 java-tutorial/BUILD 中的 greeter 目標，如下所示：

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 新增至類別路徑，因此如果這麼做，該指令碼就會在本機執行，但無法獨立於其他機器上執行。幸好，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 的行動應用程式。

祝建設愉快！