本教學課程將介紹使用 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:
- 開啟控制台。
- 依序前往「系統和安全性」>「系統」>「進階系統設定」>「進階」分頁 >「環境變數...」。
- 在「使用者變數」清單 (頂端) 清單下方,按一下「新增...」。
- 在「變數名稱」欄位中輸入
JAVA_HOME
。 - 按一下 [瀏覽目錄...]。
- 前往 JDK 目錄 (例如
C:\Program Files\Java\jdk1.8.0_152
)。 - 在所有對話方塊視窗中按一下 [確定]。
取得範例專案
從 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 必須要有 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
目標會建構兩個來源檔案,並依附另一個目標 (: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 的行動應用程式。
祝您建構愉快!