Trang này chứa các tài nguyên giúp bạn sử dụng Bazel với các dự án Java. Trang này liên kết đến một hướng dẫn, các quy tắc xây dựng và thông tin khác dành riêng cho việc xây dựng các dự án Java bằng Bazel.
Làm việc với Bazel
Các tài nguyên sau đây sẽ giúp bạn làm việc với Bazel trên các dự án Java:
Di chuyển sang Bazel
Nếu bạn hiện đang tạo các dự án Java bằng Maven, hãy làm theo các bước trong hướng dẫn di chuyển để bắt đầu tạo các dự án Maven bằng Bazel:
Các phiên bản Java
Có 2 phiên bản Java liên quan được thiết lập bằng cờ cấu hình:
- phiên bản của các tệp nguồn trong kho lưu trữ
- phiên bản của thời gian chạy Java được dùng để thực thi mã và kiểm thử mã
Định cấu hình phiên bản mã nguồn trong kho lưu trữ
Nếu không có cấu hình bổ sung, Bazel giả định rằng tất cả các tệp nguồn Java trong kho lưu trữ đều được viết bằng một phiên bản Java duy nhất. Để chỉ định phiên bản của các nguồn trong kho lưu trữ, hãy thêm build --java_language_version={ver}
vào tệp .bazelrc
, trong đó {ver}
là 11
chẳng hạn. Chủ sở hữu kho lưu trữ Bazel nên đặt cờ này để Bazel và người dùng có thể tham chiếu số phiên bản Java của mã nguồn. Để biết thêm thông tin chi tiết, hãy xem Cờ phiên bản ngôn ngữ Java.
Định cấu hình JVM dùng để thực thi và kiểm thử mã
Bazel sử dụng một JDK để biên dịch và một JVM khác để thực thi và kiểm thử mã.
Theo mặc định, Bazel sẽ biên dịch mã bằng JDK mà nó tải xuống, đồng thời thực thi và kiểm thử mã bằng JVM được cài đặt trên máy cục bộ. Bazel tìm kiếm JVM bằng cách sử dụng JAVA_HOME
hoặc đường dẫn.
Các tệp nhị phân kết quả tương thích với JVM được cài đặt cục bộ trong các thư viện hệ thống, nghĩa là các tệp nhị phân kết quả phụ thuộc vào những gì được cài đặt trên máy.
Để định cấu hình JVM dùng cho quá trình thực thi và kiểm thử, hãy sử dụng cờ --java_runtime_version
. Giá trị mặc định là local_jdk
.
Thử nghiệm và biên dịch khép kín
Để tạo một bản biên dịch khép kín, bạn có thể sử dụng cờ dòng lệnh --java_runtime_version=remotejdk_11
. Mã này được biên dịch, thực thi và kiểm thử trên JVM được tải xuống từ một kho lưu trữ từ xa. Để biết thêm thông tin chi tiết, hãy xem Cờ phiên bản thời gian chạy Java.
Định cấu hình quá trình biên dịch và thực thi các công cụ xây dựng bằng Java
Có một cặp JDK và JVM thứ hai được dùng để tạo và thực thi các công cụ. Các công cụ này được dùng trong quy trình tạo nhưng không có trong kết quả tạo. JDK và JVM đó được kiểm soát bằng --tool_java_language_version
và --tool_java_runtime_version
. Giá trị mặc định lần lượt là 11
và remotejdk_11
.
Biên dịch bằng JDK được cài đặt cục bộ
Theo mặc định, Bazel sẽ biên dịch bằng JDK từ xa vì nó đang ghi đè các thành phần bên trong của JDK. Các chuỗi công cụ biên dịch sử dụng JDK được cài đặt cục bộ sẽ được định cấu hình, nhưng không được dùng.
Để biên dịch bằng JDK được cài đặt cục bộ, tức là sử dụng chuỗi công cụ biên dịch cho JDK cục bộ, hãy sử dụng cờ bổ sung --extra_toolchains=@local_jdk//:all
, tuy nhiên, hãy lưu ý rằng cờ này có thể không hoạt động trên JDK của các nhà cung cấp tuỳ ý.
Để biết thêm thông tin chi tiết, hãy xem phần định cấu hình bộ công cụ Java.
Các phương pháp hay nhất
Ngoài các phương pháp hay nhất chung của Bazel, dưới đây là các phương pháp hay nhất dành riêng cho dự án Java.
Cấu trúc thư mục
Ưu tiên bố cục thư mục tiêu chuẩn của Maven (các nguồn trong src/main/java
, các kiểm thử trong src/test/java
).
Tệp BUILD
Hãy tuân thủ các nguyên tắc sau khi tạo tệp BUILD
:
Sử dụng một tệp
BUILD
cho mỗi thư mục chứa các nguồn Java, vì điều này giúp cải thiện hiệu suất bản dựng.Mỗi tệp
BUILD
phải chứa một quy tắcjava_library
có dạng như sau:java_library( name = "directory-name", srcs = glob(["*.java"]), deps = [...], )
Tên của thư viện phải là tên của thư mục chứa tệp
BUILD
. Điều này giúp nhãn của thư viện ngắn hơn, tức là sử dụng"//package"
thay vì"//package:package"
.Các nguồn phải là
glob
không đệ quy của tất cả các tệp Java trong thư mục.Các kiểm thử phải nằm trong một thư mục khớp trong
src/test
và phụ thuộc vào thư viện này.
Tạo quy tắc mới cho các bản dựng Java nâng cao
Lưu ý: Việc tạo quy tắc mới dành cho các tình huống kiểm thử và tạo nâng cao. Bạn không cần đến nó khi bắt đầu sử dụng Bazel.
Các mô-đun, đoạn cấu hình và trình cung cấp sau đây sẽ giúp bạn mở rộng các chức năng của Bazel khi xây dựng các dự án Java:
- Mô-đun Java chính:
java_common
- Nhà cung cấp Java chính:
JavaInfo
- Mảnh cấu hình:
java
Các mô-đun khác:
Định cấu hình chuỗi công cụ Java
Bazel sử dụng 2 loại chuỗi công cụ Java: – thực thi, dùng để thực thi và kiểm thử các tệp nhị phân Java, được kiểm soát bằng cờ --java_runtime_version
– biên dịch, dùng để biên dịch các nguồn Java, được kiểm soát bằng cờ --java_language_version
Định cấu hình các chuỗi công cụ thực thi bổ sung
Chuỗi công cụ thực thi là JVM, có thể là cục bộ hoặc từ một kho lưu trữ, cùng với một số thông tin bổ sung về phiên bản, hệ điều hành và cấu trúc CPU.
Bạn có thể thêm chuỗi công cụ thực thi Java bằng cách sử dụng các quy tắc local_java_repository
hoặc remote_java_repository
trong một tiện ích mô-đun. Việc thêm quy tắc này sẽ giúp JVM có sẵn bằng cách sử dụng một cờ. Khi bạn đưa ra nhiều định nghĩa cho cùng một hệ điều hành và cấu trúc CPU, định nghĩa đầu tiên sẽ được sử dụng.
Ví dụ về cấu hình JVM cục bộ:
load("@rules_java//toolchains: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
)
Ví dụ về cấu hình JVM từ xa:
load("@rules_java//toolchains: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 = ...
)
Định cấu hình các chuỗi công cụ biên dịch bổ sung
Chuỗi công cụ biên dịch bao gồm JDK và nhiều công cụ mà Bazel sử dụng trong quá trình biên dịch và cung cấp các tính năng bổ sung, chẳng hạn như: Error Prone, các phần phụ thuộc Java nghiêm ngặt, biên dịch tiêu đề, đơn giản hoá Android, đo lường mức độ phù hợp và xử lý genclass cho các IDE.
JavaBuilder là một công cụ đi kèm Bazel, thực hiện quá trình biên dịch và cung cấp các tính năng nêu trên. Quá trình biên dịch thực tế được thực thi bằng trình biên dịch nội bộ của JDK. JDK dùng để biên dịch được chỉ định bằng thuộc tính java_runtime
của chuỗi công cụ.
Bazel ghi đè một số thành phần nội bộ của JDK. Trong trường hợp phiên bản JDK > 9, các mô-đun java.compiler
và jdk.compiler
được vá bằng cờ --patch_module
của JDK. Trong trường hợp JDK phiên bản 8, trình biên dịch Java sẽ được vá bằng cờ -Xbootclasspath
.
VanillaJavaBuilder là một cách triển khai thứ hai của JavaBuilder, không sửa đổi trình biên dịch nội bộ của JDK và không có bất kỳ tính năng bổ sung nào. VanillaJavaBuilder không được bất kỳ chuỗi công cụ tích hợp nào sử dụng.
Ngoài JavaBuilder, Bazel còn sử dụng một số công cụ khác trong quá trình biên dịch.
Công cụ ijar
xử lý các tệp jar
để xoá mọi thứ, ngoại trừ chữ ký lệnh gọi. Các tệp jar thu được được gọi là tệp jar tiêu đề. Chúng được dùng để cải thiện mức tăng của quá trình biên dịch bằng cách chỉ biên dịch lại các thành phần phụ thuộc ở hạ nguồn khi nội dung của một hàm thay đổi.
Công cụ singlejar
sẽ đóng gói nhiều tệp jar
thành một tệp duy nhất.
Công cụ genclass
xử lý đầu ra của quá trình biên dịch Java và tạo ra một jar
chỉ chứa các tệp lớp cho những nguồn do trình xử lý chú thích tạo.
Công cụ JacocoRunner
chạy Jacoco trên các tệp được đo lường và xuất kết quả ở định dạng LCOV.
Công cụ TestRunner
thực thi các kiểm thử JUnit 4 trong một môi trường có kiểm soát.
Bạn có thể định cấu hình lại quá trình biên dịch bằng cách thêm macro default_java_toolchain
vào tệp BUILD
và đăng ký macro đó bằng cách thêm quy tắc register_toolchains
vào tệp MODULE.bazel
hoặc bằng cách sử dụng cờ --extra_toolchains
.
Chuỗi công cụ chỉ được dùng khi thuộc tính source_version
khớp với giá trị do cờ --java_language_version
chỉ định.
Ví dụ về cấu hình chuỗi công cụ:
load(
"@rules_java//toolchains: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 = "@rules_java//toolchains: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",
)
có thể được dùng bằng cách sử dụng --extra_toolchains=//:repository_default_toolchain_definition
hoặc bằng cách thêm register_toolchains("//:repository_default_toolchain_definition")
vào không gian làm việc.
Cấu hình được xác định trước:
DEFAULT_TOOLCHAIN_CONFIGURATION
: tất cả tính năng, hỗ trợ các phiên bản JDK >= 9VANILLA_TOOLCHAIN_CONFIGURATION
: không có tính năng bổ sung, hỗ trợ JDK của các nhà cung cấp tuỳ ý.PREBUILT_TOOLCHAIN_CONFIGURATION
: giống như mặc định, nhưng chỉ sử dụng các công cụ được tạo sẵn (ijar
,singlejar
)NONPREBUILT_TOOLCHAIN_CONFIGURATION
: giống như mặc định, nhưng tất cả các công cụ đều được tạo từ các nguồn (điều này có thể hữu ích trên hệ điều hành có libc khác)
Định cấu hình cờ trình biên dịch JVM và Java
Bạn có thể định cấu hình các cờ JVM và javac bằng cờ hoặc bằng các thuộc tính default_java_toolchain
.
Các cờ liên quan là --jvmopt
, --host_jvmopt
, --javacopt
và --host_javacopt
.
Các thuộc tính default_java_toolchain
có liên quan là javacopts
, jvm_opts
, javabuilder_jvm_opts
và turbine_jvm_opts
.
Cấu hình cờ trình biên dịch Java dành riêng cho gói
Bạn có thể định cấu hình các cờ trình biên dịch Java khác nhau cho các tệp nguồn cụ thể bằng cách sử dụng thuộc tính package_configuration
của default_java_toolchain
.
Vui lòng tham khảo ví dụ bên dưới.
load("@rules_java//toolchains: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
],
)
Nhiều phiên bản mã nguồn Java trong một kho lưu trữ
Bazel chỉ hỗ trợ việc biên dịch một phiên bản duy nhất của các nguồn Java trong một bản dựng. Điều này có nghĩa là khi tạo một bài kiểm thử hoặc ứng dụng Java, tất cả các phần phụ thuộc đều được tạo dựa trên cùng một phiên bản Java.
Tuy nhiên, các bản dựng riêng biệt có thể được thực thi bằng các cờ khác nhau.
Để giúp bạn dễ dàng sử dụng các cờ khác nhau, các nhóm cờ cho một phiên bản cụ thể có thể được nhóm với các cấu hình .bazelrc
":
build:java8 --java_language_version=8
build:java8 --java_runtime_version=local_jdk_8
build:java11 --java_language_version=11
build:java11 --java_runtime_version=remotejdk_11
Bạn có thể dùng các cấu hình này với cờ --config
, ví dụ: bazel test --config=java11 //:java11_test
.