本頁面含有可協助您搭配 Java 專案使用 Bazel 的資源。本頁面提供教學課程、建構規則,以及使用 Bazel 建構 Java 專案的其他資訊。
使用 Bazel
下列資源可協助您在 Java 專案中使用 Bazel:
遷移至 Bazel
如果您目前使用 Maven 建構 Java 專案,請按照遷移指南中的步驟開始使用 Bazel 建構 Maven 專案:
Java 版本
有兩個相關的 Java 版本都使用設定標記:
- 存放區中來源檔案的版本
- 用於執行程式碼及測試的 Java 執行階段版本
設定存放區中的原始碼版本
如未另外設定,Bazel 會假設存放區中的所有 Java 來源檔案都是以單一 Java 版本寫入。如要指定存放區中的來源版本,請將 build --java_language_version={ver}
新增至 .bazelrc
檔案,其中 {ver}
為 11
。Bazel 存放區擁有者應設定這個標記,讓 Bazel 及其使用者能夠參照原始碼的 Java 版本號碼。詳情請參閱 Java 語言版本標記。
設定用於執行及測試程式碼的 JVM
Bazel 會使用一個 JDK 進行編譯,並使用另一個 JVM 執行及測試程式碼。
根據預設,Bazel 會使用所下載的 JDK 編譯程式碼,然後使用本機電腦上安裝的 JVM 執行及測試程式碼。Bazel 會使用 JAVA_HOME
或路徑搜尋 JVM。
產生的二進位檔會與系統程式庫中本機安裝的 JVM 相容,也就是說,產生的二進位檔取決於機器安裝的項目。
如要設定用於執行和測試的 JVM,請使用 --java_runtime_version
標記。預設值為 local_jdk
。
密封測試與編譯
如要建立隱密編譯,您可以使用指令列標記 --java_runtime_version=remotejdk_11
。程式碼會編譯、執行,並透過遠端存放區下載的 JVM 進行測試。詳情請參閱 Java 執行階段版本標記。
在 Java 中設定建構工具的編譯和執行作業
第二對 JDK 和 JVM 是用來建構和執行工具,這些工具會在建構程序中使用,但不會出現在建構結果中。該 JDK 和 JVM 是使用 --tool_java_language_version
和 --tool_java_runtime_version
控制。預設值為 11
和 remotejdk_11
。
使用本機安裝的 JDK 編譯
根據預設,Bazel 會使用遠端 JDK 進行編譯,因為這會覆寫 JDK 的內部。已設定使用本機安裝 JDK 的編譯工具鍊,但一律不使用。
如要使用本機安裝的 JDK 進行編譯,而該作業會使用本機 JDK 的編譯工具鍊,請使用額外的標記 --extra_toolchains=@local_jdk//:all
。不過請注意,這可能不適用於任意供應商的 JDK。
詳情請參閱設定 Java 工具鍊。
最佳做法
除了一般 Bazel 最佳做法以外,下方則是 Java 專案專用的最佳做法。
目錄結構
偏好 Maven 的標準目錄版面配置 (src/main/java
下的來源,src/test/java
下的測試)。
BUILD 檔案
建立 BUILD
檔案時,請遵守下列規範:
針對每個包含 Java 來源的目錄,使用一個
BUILD
檔案,因為這樣可提高建構效能。每個
BUILD
檔案都應包含一個java_library
規則,如下所示:java_library( name = "directory-name", srcs = glob(["*.java"]), deps = [...], )
程式庫的名稱應為包含
BUILD
檔案的目錄名稱。這樣會縮短程式庫的標籤,使用"//package"
,而不是"//package:package"
。來源應為目錄中所有 Java 檔案的非遞迴
glob
。測試應位於
src/test
下的相符目錄,且依附於這個程式庫。
為進階 Java 版本建立新規則
注意:建立新規則適用於進階建構和測試情境。您在開始使用 Bazel 時並不需要。
下列模組、設定片段和提供者可協助您在建構 Java 專案時擴充 Bazel 的功能:
- 主要 Java 供應商:
java_common
- 主要 Java 模組:
JavaInfo
- 設定片段:
java
其他模組:
設定 Java 工具鍊
Bazel 使用兩種 Java 工具鍊:
- 用於執行及測試 Java 二進位檔 (由 --java_runtime_version
標記控制)
- 編譯,用於編譯 Java 來源,使用 --java_language_version
標記控制。
設定其他執行工具鍊
執行工具鍊是本機或存放區的 JVM,包含有關其版本、作業系統和 CPU 架構的其他資訊。
Java 執行工具鍊可以使用 WORKSPACE
檔案中的 local_java_repository
或 remote_java_repository
規則新增。新增規則後,就能使用標記提供 JVM。如果提供同一作業系統和 CPU 架構的多項定義,系統會使用第一個定義。
本機 JVM 的設定範例:
load("@bazel_tools//tools/jdk:local_java_repository.bzl", "local_java_repository")
local_java_repository(
name = "additionaljdk", # Can be used with --java_runtime_version=additionaljdk, --java_runtime_version=11 or --java_runtime_version=additionaljdk_11
version = 11, # Optional, if not set it is autodetected
java_home = "/usr/lib/jdk-15/", # Path to directory containing bin/java
)
遠端 JVM 的設定範例:
load("@bazel_tools//tools/jdk:remote_java_repository.bzl", "remote_java_repository")
remote_java_repository(
name = "openjdk_canary_linux_arm",
prefix = "openjdk_canary", # Can be used with --java_runtime_version=openjdk_canary_11
version = "11", # or --java_runtime_version=11
target_compatible_with = [ # Specifies constraints this JVM is compatible with "@platforms//cpu:arm",
"@platforms//os:linux",
],
urls = ..., # Other parameters are from http_repository rule.
sha256 = ...,
strip_prefix = ...
)
設定其他編譯工具鍊
編譯工具鍊包含 JDK 和多項 Bazel 在編譯期間使用的工具,且該工具可提供其他功能,例如:Error Prone、嚴格的 Java 依附元件、標頭編譯、Android 脫糖、涵蓋率檢測,以及 IDE 的生成式類別處理。
JavaBuilder 是 Bazel 封裝工具,可執行編譯作業並提供上述功能。實際編譯作業是使用 JDK 的內部編譯器執行。用於編譯的 JDK 是由工具鍊的 java_runtime
屬性指定。
Bazel 會覆寫部分 JDK 內部。如果 JDK 版本超過 9,系統會使用 JDK 的標記 --patch_module
修補 java.compiler
和 jdk.compiler
模組。如果是 JDK 8 版,系統會使用 -Xbootclasspath
標記修補 Java 編譯器。
VanillaJavaBuilder 是 JavaBuilder 的第二個實作項目,這個實作不會修改 JDK 的內部編譯器,也不具備任何其他功能。所有內建工具鍊都不使用 VanillaJavaBuilder。
除了 JavaBuilder 之外,Bazel 會在編譯時使用幾項其他工具。
ijar
工具會處理 jar
檔案,移除呼叫簽章以外的所有項目。產生的 jar 則稱為標頭 jar。這種程式庫只會在函式主體變更時重新編譯下游相依項目,藉此改善編譯增量性。
singlejar
工具會將多個 jar
檔案封裝成單一檔案。
genclass
工具會對 Java 編譯的輸出內容進行後續處理,並產生 jar
,其中僅包含由註解處理工具產生的來源類別檔案。
JacocoRunner
工具會針對檢測檔案執行 Jacoco,並輸出 LCOV 格式。
TestRunner
工具會在受控管的環境中執行 JUnit 4 測試。
如要重新設定編譯作業,請將 default_java_toolchain
巨集新增至 BUILD
檔案,然後透過將 register_toolchains
規則新增至 WORKSPACE
檔案,或使用 --extra_toolchains
標記進行註冊。
只有在 source_version
屬性與 --java_language_version
標記指定的值相符時,才能使用工具鍊。
工具鍊設定範例:
load(
"@bazel_tools//tools/jdk:default_java_toolchain.bzl",
"default_java_toolchain", "DEFAULT_TOOLCHAIN_CONFIGURATION", "BASE_JDK9_JVM_OPTS", "DEFAULT_JAVACOPTS"
)
default_java_toolchain(
name = "repository_default_toolchain",
configuration = DEFAULT_TOOLCHAIN_CONFIGURATION, # One of predefined configurations
# Other parameters are from java_toolchain rule:
java_runtime = "@bazel_tools//tools/jdk:remote_jdk11", # JDK to use for compilation and toolchain's tools execution
jvm_opts = BASE_JDK9_JVM_OPTS + ["--enable_preview"], # Additional JDK options
javacopts = DEFAULT_JAVACOPTS + ["--enable_preview"], # Additional javac options
source_version = "9",
)
可使用 --extra_toolchains=//:repository_default_toolchain_definition
,或在工作器中新增 register_toolchains("//:repository_default_toolchain_definition")
。
預先定義的設定:
DEFAULT_TOOLCHAIN_CONFIGURATION
:所有功能,支援 JDK 第 9 版以上的版本VANILLA_TOOLCHAIN_CONFIGURATION
:無其他功能,支援任意供應商的 JDK。PREBUILT_TOOLCHAIN_CONFIGURATION
:與預設值相同,但只會使用預先建構的工具 (ijar
、singlejar
)NONPREBUILT_TOOLCHAIN_CONFIGURATION
:與預設值相同,但所有工具都是從來源建構 (在採用不同 libc 的作業系統上可能非常實用)
設定 JVM 和 Java 編譯器標記
您可以使用旗標或 default_java_toolchain
屬性設定 JVM 和 javac 標記。
相關旗標為 --jvmopt
、--host_jvmopt
、--javacopt
和 --host_javacopt
。
相關的 default_java_toolchain
屬性為 javacopts
、jvm_opts
、javabuilder_jvm_opts
和 turbine_jvm_opts
。
套件專用的 Java 編譯器旗標設定
您可以使用 default_java_toolchain
的 package_configuration
屬性,為特定來源檔案設定不同的 Java 編譯器標記。請參考以下範例。
load("@bazel_tools//tools/jdk:default_java_toolchain.bzl", "default_java_toolchain")
# This is a convenience macro that inherits values from Bazel's default java_toolchain
default_java_toolchain(
name = "toolchain",
package_configuration = [
":error_prone",
],
visibility = ["//visibility:public"],
)
# This associates a set of javac flags with a set of packages
java_package_configuration(
name = "error_prone",
javacopts = [
"-Xep:MissingOverride:ERROR",
],
packages = ["error_prone_packages"],
)
# This is a regular package_group, which is used to specify a set of packages to apply flags to
package_group(
name = "error_prone_packages",
packages = [
"//foo/...",
"-//foo/bar/...", # this is an exclusion
],
)
單一存放區中有多種版本的 Java 原始碼
Bazel 僅支援在建構作業中編譯單一版本的 Java 來源。這表示在建構 Java 測試或應用程式時,所有依附元件都是以相同的 Java 版本建構而成。
不過,您可以使用不同的標記執行不同的建構。
為簡化使用不同標記的工作,可將特定版本的標記組合以 .bazelrc
設定分組:
build:java8 --java_language_version=8
build:java8 --java_runtime_version=localjdk_8
build:java11 --java_language_version=11
build:java11 --java_runtime_version=remotejdk_11
這些設定可與 --config
旗標搭配使用,例如 bazel test --config=java11 //:java11_test
。