从 Maven 迁移到 Bazel

报告问题 查看源代码

本页面介绍如何从 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：

  1. 创建 WORKSPACE 文件
  2. 创建一个 BUILD 文件
  3. 创建更多 BUILD 文件
  4. 使用 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 文件来优化构建。

  1. 在 WORKSPACE 文件所在的目录中，创建一个文本文件并将其命名为 BUILD。

  2. 在此 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 文件的示例。

  3. 现在，项目的根目录下已有一个 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 生成所有构建。