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

Bazel 教學課程：建構 Java 專案

回報問題查看來源

本教學課程將介紹使用 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
└── 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 中。

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

目標「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 屬性得知這一點。查看依附元件圖表：

目標「執行器」的依附元件圖

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

祝您建構愉快！