本页面介绍如何从 Maven 迁移到 Bazel,包括前提条件和安装步骤。其中介绍了 Maven 与 Bazel 之间的区别,并提供了一个使用 Guava 项目的迁移示例。
从任何构建工具迁移到 Bazel 时,最好同时运行这两个构建工具,直到您完全迁移了开发团队、CI 系统和任何其他相关系统。您可以在同一代码库中运行 Maven 和 Bazel。
准备工作
- 安装 Bazel(如果尚未安装)。
- 如果您刚开始接触 Bazel,请先完成 Bazel 简介:构建 Java 教程,然后再开始迁移。本教程介绍了 Bazel 的概念、结构和标签语法。
Maven 和 Bazel 之间的区别
- Maven 使用顶级
pom.xml
文件。Bazel 支持每个BUILD
文件包含多个构建文件和多个目标,因此可以实现比 Maven 更多增量的构建。 - Maven 负责执行部署过程的步骤。Bazel 不会自动部署。
- 您可以使用 Bazel 来表达语言之间的依赖关系。
- 向项目中添加新部分时,使用 Bazel 时,您可能需要添加新的
BUILD
文件。最佳实践是在每个新的 Java 软件包中添加一个BUILD
文件。
从 Maven 迁移到 Bazel
以下步骤介绍了如何将项目迁移到 Bazel:
以下示例来自将 Guava 项目从 Maven 迁移到 Bazel。使用的 Guava 项目版本为 v31.1
。使用 Guava 的示例不会逐步完成迁移中的每个步骤,但会显示为迁移手动添加或添加的文件和内容。
$ git clone https://github.com/google/guava.git && cd guava
$ git checkout v31.1
1. 创建 WORKSPACE 文件
在项目的根目录下创建一个名为 WORKSPACE
的文件。如果您的项目没有外部依赖项,则工作区文件可以为空。
如果您的项目依赖于不在您项目目录中的文件或软件包,请在工作区文件中指定这些外部依赖项。如需自动列出工作区文件的外部依赖项,请使用 rules_jvm_external
。如需了解如何使用此规则集,请参阅自述文件。
Guava 项目示例:外部依赖项
您可以使用 rules_jvm_external
规则集列出 Guava 项目的外部依赖项。
将以下代码段添加到 WORKSPACE
文件中:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
RULES_JVM_EXTERNAL_TAG = "4.3"
RULES_JVM_EXTERNAL_SHA = "6274687f6fc5783b589f56a2f1ed60de3ce1f99bc4e8f9edef3de43bdf7c6e74"
http_archive(
name = "rules_jvm_external",
sha256 = RULES_JVM_EXTERNAL_SHA,
strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
url = "https://github.com/bazelbuild/rules_jvm_external/archive/%s.zip" % RULES_JVM_EXTERNAL_TAG,
)
load("@rules_jvm_external//:defs.bzl", "maven_install")
maven_install(
artifacts = [
"com.google.code.findbugs:jsr305:3.0.2",
"com.google.errorprone:error_prone_annotations:2.11.0",
"com.google.j2objc:j2objc-annotations:1.3",
"org.codehaus.mojo:animal-sniffer-annotations:1.20",
"org.checkerframework:checker-qual:3.12.0",
],
repositories = [
"https://repo1.maven.org/maven2",
],
)
2. 创建一个 BUILD 文件
现在您已经定义了工作区并列出了外部依赖项(如果适用),接下来需要创建 BUILD
文件以描述应如何构建项目。与具有一个 pom.xml
文件的 Maven 不同,Bazel 可以使用多个 BUILD
文件来构建项目。这些文件指定多个构建目标,支持 Bazel 生成增量构建。
分阶段添加 BUILD
文件。首先在项目的根目录中添加一个 BUILD
文件,然后使用该文件使用 Bazel 进行初始构建。然后,您可以通过添加更多具有更精细目标的 BUILD
文件来优化构建。
在
WORKSPACE
文件所在的目录中,创建一个文本文件并将其命名为BUILD
。在此
BUILD
文件中,使用适当的规则创建一个目标来构建您的项目。请参考以下提示:使用适当的规则:
如需使用单个 Maven 模块构建项目,请使用
java_library
规则,如下所示:java_library( name = "everything", srcs = glob(["src/main/java/**/*.java"]), resources = glob(["src/main/resources/**"]), deps = ["//:all-external-targets"], )
如需构建包含多个 Maven 模块的项目,请使用
java_library
规则,如下所示:java_library( name = "everything", srcs = glob([ "Module1/src/main/java/**/*.java", "Module2/src/main/java/**/*.java", ... ]), resources = glob([ "Module1/src/main/resources/**", "Module2/src/main/resources/**", ... ]), deps = ["//:all-external-targets"], )
如需构建二进制文件,请使用
java_binary
规则:java_binary( name = "everything", srcs = glob(["src/main/java/**/*.java"]), resources = glob(["src/main/resources/**"]), deps = ["//:all-external-targets"], main_class = "com.example.Main" )
指定属性:
name
:为目标指定一个有意义的名称。在上面的示例中,目标称为“everything”。srcs
:使用 globbing 列出项目中的所有 .java 文件。resources
:使用 globbing 列出项目中的所有资源。deps
:您需要确定项目所需的外部依赖项。例如,如果您使用generate_workspace
工具生成了外部依赖项列表,则java_library
的依赖项是generated_java_libraries
宏中列出的库。
我们来看看从 Guava 项目的迁移中此顶级 BUILD 文件的示例。
现在,项目的根目录下已有一个
BUILD
文件,接下来请构建项目以确保其正常运行。在命令行中,从工作区目录中,使用bazel build //:everything
通过 Bazel 构建项目。该项目现在已使用 Bazel 成功构建。您需要添加更多
BUILD
文件才能允许对项目进行增量构建。
Guava 项目示例:首先创建一个 BUILD 文件
将 Guava 项目迁移到 Bazel 时,最初会使用一个 BUILD
文件构建整个项目。以下是工作区目录中此初始 BUILD
文件的内容:
java_library(
name = "everything",
srcs = glob([
"guava/src/**/*.java",
"futures/failureaccess/src/**/*.java",
]),
javacopts = ["-XepDisableAllChecks"],
deps = [
"@maven//:com_google_code_findbugs_jsr305",
"@maven//:com_google_errorprone_error_prone_annotations",
"@maven//:com_google_j2objc_j2objc_annotations",
"@maven//:org_checkerframework_checker_qual",
"@maven//:org_codehaus_mojo_animal_sniffer_annotations",
],
)
3. 创建更多 BUILD 文件(可选)
正如您在完成首个构建后看到的那样,Bazel 只支持一个 BUILD file
。您仍应考虑通过添加更多具有精细目标的 BUILD
文件,将 build 拆分为更小的分块。
包含多个目标的多个 BUILD
文件将使 build 更加精细,从而允许:
- 增加了项目的增量 build,
- 提高了构建的并行执行速度,
- 为未来用户提供更好的 build 可维护性,以及
- 控制软件包之间目标的可见性,从而防止某些问题,例如包含实现细节的库泄露到公共 API。
有关添加更多 BUILD
文件的提示:
- 您可以先在每个 Java 软件包中添加一个
BUILD
文件。从依赖项最少的 Java 软件包开始,直到依赖项最多的软件包。 - 在添加
BUILD
文件并指定目标时,请将这些新目标添加到依赖于它们的目标的deps
部分。请注意,glob()
函数不会跨越软件包边界,因此随着软件包数量的增加,与glob()
匹配的文件会缩小。 - 每次将
BUILD
文件添加到main
目录时,请务必将BUILD
文件添加到相应的test
目录中。 - 注意适当限制软件包之间的可见性。
- 为了简化
BUILD
文件设置过程中的错误问题排查,请确保在添加每个构建文件时,项目能继续使用 Bazel 进行构建。运行bazel build //...
以确保仍会构建所有目标。
4. 使用 Bazel 构建
在添加 BUILD
文件以验证构建设置时,您一直在使用 Bazel 进行构建。
当您拥有所需粒度的 BUILD
文件时,您可以使用 Bazel 生成所有构建。