本页面介绍如何从 Maven 迁移到 Bazel,包括前提条件和安装步骤。其中介绍了 Maven 和 Bazel 之间的差异,并提供了一个使用 Guava 项目的迁移示例。
从任何构建工具迁移到 Bazel 时,最好同时并行运行构建工具,直到您完全迁移开发团队、CI 系统和任何其他相关系统。您可以在同一代码库中运行 Maven 和 Bazel。
准备工作
- 安装 Bazel(如果尚未安装)。
- 如果您刚开始接触 Bazel,请完成教程:Bazel:构建 Java,然后再开始迁移。本教程介绍了 Bazel 的概念、结构和标签语法。
Maven 和 Bazel 之间的区别
- Maven 使用顶级
pom.xml
文件。Bazel 支持每个 build 文件和多个BUILD
文件多个目标,这使得这些 build 比 Maven 的增量更大。 - Maven 负责部署过程的步骤。Bazel 不会自动部署。
- 您可以使用 Bazel 来表达语言之间的依赖关系。
- 向项目中添加新版块时,您可能需要使用 Bazel 添加新的
BUILD
文件。最佳做法是向每个新的 Java 软件包添加BUILD
文件。
从 Maven 迁移到 Bazel
以下步骤介绍了如何将项目迁移到 Bazel:
以下示例来自从 Maven 到 Bazel 的 Guava 项目迁移。使用的 Guava 项目为版本 v31.1
。使用 Guava 的示例不会演示迁移过程中的每个步骤,但会显示为迁移手动生成或添加的文件和内容。
$ git clone https://github.com/google/guava.git && cd guava
$ git checkout v31.1
1. 创建 WORKSPACE 文件
在项目的根目录下创建一个名为 WORKSPACE
的文件。如果您的项目没有外部依赖项,则工作区文件可以为空。
如果您的项目依赖的文件不在软件包的任一目录中,请在工作区文件中指定这些外部依赖项。如需自动列出工作区外部依赖项,请使用 rules_jvm_external
。如需了解如何使用此规则集,请参阅 README 文件。
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
文件来描述项目的构建方式。与 Maven 只包含一个 pom.xml
文件不同,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
:为目标指定一个有意义的名称。在上面的示例中,目标称为“所有内容”。srcs
:使用 globbing 列出项目中的所有 .java 文件。resources
:使用全球查询列出项目中的所有资源。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",
]),
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 构建
您一直在使用 Bazel 进行构建,同时添加 BUILD
文件以验证构建的设置。
当您的 BUILD
文件达到所需的粒度时,可以使用 Bazel 生成所有构建。