Bazel 教程:构建 Java 项目

<ph type="x-smartling-placeholder"></ph> 报告问题 查看来源 敬上 每晚 · 7.3。 · 7.2 条 · 7.1。 · 7.0。 · 6.5

本教程涵盖了使用 Bazel。您将设置自己的工作区并构建一个简单的 Java 项目, 说明了关键的 Bazel 概念,例如目标和 BUILD 文件。

预计所需时长:30 分钟。

学习内容

在本教程中,您将学习如何:

  • 构建目标
  • 直观呈现项目的依赖项
  • 将项目拆分为多个目标和软件包
  • 控制软件包中的目标可见性
  • 通过标签引用目标
  • 部署目标

准备工作

安装 Bazel

准备学习本教程之前,请先安装 Bazel 您尚未安装该软件。

安装 JDK

  1. 安装 Java JDK(首选版本为 11,但支持版本 8 到 15)。

  2. 将 JAVA_HOME 环境变量设置为指向 JDK。

    • 在 Linux/macOS 上:

      export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))"
      
    • 在 Windows 上:

      1. 打开“控制面板”。
      2. 转到“系统和安全”&gt;“系统”&gt;“高级系统设置”&gt;“高级”标签页 >“环境变量...”.
      3. 在“用户变量”下列表(位于顶部的列表中),点击“新建...”。
      4. 在“变量名称”中字段中,输入 JAVA_HOME
      5. 点击“浏览目录...”。
      6. 前往 JDK 目录(例如 C:\Program Files\Java\jdk1.8.0_152)。
      7. 点击“确定”。

获取示例项目

从 Bazel 的 GitHub 代码库中检索示例项目:

git clone https://github.com/bazelbuild/examples

本教程的示例项目位于 examples/java-tutorial 目录,其结构如下:

java-tutorial
├── BUILD
├── src
   └── main
       └── java
           └── com
               └── example
                   ├── cmdline
                      ├── BUILD
                      └── Runner.java
                   ├── Greeting.java
                   └── ProjectRunner.java
└── WORKSPACE

使用 Bazel 构建

设置工作区

您需要先设置项目工作区,然后才能构建项目。工作区是 一个目录,用于保存项目的源文件和 Bazel 的构建输出。它 还包含 Bazel 识别为特殊的文件:

  • WORKSPACE 文件,用于将目录及其内容标识为 Bazel 工作区位于项目目录结构的根目录下,

  • 一个或多个 BUILD 文件,告知 Bazel 如何构建 项目。(工作区内包含 BUILD 文件的目录 是一个软件包。在本教程后面部分,您将了解软件包。)

要将某个目录指定为 Bazel 工作区,请创建一个名为 WORKSPACE

当 Bazel 构建项目时,所有输入和依赖项必须位于同一 工作区。位于不同工作区的文件独立于一个工作区 否则就会出现这种错误,这超出了本教程的讨论范围。

了解 BUILD 文件

BUILD 文件包含几种不同类型的 Bazel 说明。 最重要的类型是“构建规则”,它告诉 Bazel 如何构建 所需的输出,例如可执行二进制文件或库。每个实例 称为目标,它指向BUILD 一组特定的源文件和依赖项。目标还可以指向 目标。

查看 java-tutorial/BUILD 文件:

java_binary(
    name = "ProjectRunner",
    srcs = glob(["src/main/java/com/example/*.java"]),
)

在我们的示例中,ProjectRunner 目标会实例化 Bazel 的内置 java_binary 规则。该规则让 Bazel 构建一个 .jar 文件和封装容器 Shell 脚本(两者均以目标命名)。

目标中的属性会明确说明其依赖项和选项。 name 属性是必需属性,但许多属性是可选的。例如,在 ProjectRunner 规则目标,name 为目标的名称,srcs 指定目标 Bazel 用于构建目标的源文件,main_class 指定 包含主方法的类。(您可能已经注意到, 使用 glob 将一组源文件传递给 Bazel 而不必逐一列出。)

构建项目

如需构建示例项目,请前往 java-tutorial 目录 并运行:

bazel build //:ProjectRunner

在目标标签中,// 部分是 BUILD 文件的位置 相对于工作区根目录(在本例中为根本身) ProjectRunnerBUILD 文件中的目标名称。(您将 详细了解目标标签。)

Bazel 会生成类似于以下内容的输出:

   INFO: Found 1 target...
   Target //:ProjectRunner up-to-date:
      bazel-bin/ProjectRunner.jar
      bazel-bin/ProjectRunner
   INFO: Elapsed time: 1.021s, Critical Path: 0.83s

恭喜,您刚刚构建了您的第一个 Bazel 目标!Bazel 地点构建 输出位于工作区根目录下的 bazel-bin 目录中。浏览 以了解 Bazel 的输出结构。

现在,测试新构建的二进制文件:

bazel-bin/ProjectRunner

查看依赖关系图

Bazel 要求在 BUILD 文件中明确声明 build 依赖项。 Bazel 使用这些语句来创建项目的依赖关系图, 支持准确的增量构建。

要直观呈现示例项目的依赖项,您可以生成一段文本 表示依赖关系图的表示,方法是在 工作区根目录:

bazel query  --notool_deps --noimplicit_deps "deps(//:ProjectRunner)" --output graph

以上命令指示 Bazel 查找目标的所有依赖项 //:ProjectRunner(不包括主机和隐式依赖项)并设置 输出为图表。

然后,将文本粘贴到 GraphViz 中。

如您所见,项目只有一个目标,使用 没有其他依赖项:

目标“ProjectRunner”的依赖项图

设置完工作区后,构建项目并检查其 依赖项,就可以增加一些复杂性。

优化 Bazel 构建

虽然单个目标对小型项目来说已经足够,但您可能希望进行拆分 大型项目拆分为多个目标和软件包,以实现快速增量 (即仅重新构建更改的内容),并通过以下方式加快构建速度: 一次性构建项目的多个部分。

指定多个构建目标

您可以将示例项目 build 拆分为两个目标。将 将 java-tutorial/BUILD 文件替换为以下代码:

java_binary(
    name = "ProjectRunner",
    srcs = ["src/main/java/com/example/ProjectRunner.java"],
    main_class = "com.example.ProjectRunner",
    deps = [":greeter"],
)

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
)

使用此配置时,Bazel 首先构建了 greeter 库,然后 ProjectRunner 二进制文件。java_binary 中的 deps 属性告诉 Bazel, 需要使用 greeter 库来构建 ProjectRunner 二进制文件。

如需构建项目的这个新版本,请运行以下命令:

bazel build //:ProjectRunner

Bazel 会生成类似于以下内容的输出:

INFO: Found 1 target...
Target //:ProjectRunner up-to-date:
  bazel-bin/ProjectRunner.jar
  bazel-bin/ProjectRunner
INFO: Elapsed time: 2.454s, Critical Path: 1.58s

现在,测试新构建的二进制文件:

bazel-bin/ProjectRunner

如果您现在修改 ProjectRunner.java 并重新构建项目,则只需使用 Bazel 重新编译该文件。

通过查看依赖关系图,您可以看到 ProjectRunner 依赖于 输入与之前相同,但 build 的结构有所不同:

目标“ProjectRunner”的依赖项图在添加依赖项之后

现在,您已经构建了具有两个目标的项目。ProjectRunner 目标 build 两个源文件,并且依赖于另一个目标 (:greeter), 一个额外的源文件

使用多个软件包

现在,我们将项目拆分成多个软件包。如果您查看 src/main/java/com/example/cmdline 目录中,您会看到,该文件还包含 一个 BUILD 文件,以及一些源文件。因此,对于 Bazel 包含两个软件包://src/main/java/com/example/cmdline//(由于 工作区的根目录下有一个 BUILD 文件)。

查看 src/main/java/com/example/cmdline/BUILD 文件:

java_binary(
    name = "runner",
    srcs = ["Runner.java"],
    main_class = "com.example.cmdline.Runner",
    deps = ["//:greeter"],
)

runner 目标依赖于 // 软件包中的 greeter 目标(因此 目标标签 //:greeter)- Bazel 通过 deps 属性知道这一点。 查看依赖关系图:

目标“runner”的依赖关系图

不过,如需构建成功,您必须明确指定 runner 目标 //src/main/java/com/example/cmdline/BUILD中的目标 //BUILD(使用 visibility 属性)。这是因为 仅对同一 BUILD 文件中的其他目标可见。(Bazel 使用目标 以避免出现问题,例如包含实现详情的库 泄漏到公共 API 中。)

为此,请将 visibility 属性添加到 greeter 目标中, java-tutorial/BUILD,如下所示:

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
    visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
)

现在,您可以在根目录下运行以下命令来构建新软件包 位置:

bazel build //src/main/java/com/example/cmdline:runner

Bazel 会生成类似于以下内容的输出:

INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner.jar
  bazel-bin/src/main/java/com/example/cmdline/runner
  INFO: Elapsed time: 1.576s, Critical Path: 0.81s

现在,测试新构建的二进制文件:

./bazel-bin/src/main/java/com/example/cmdline/runner

现在,您已修改了项目,将其构建为两个软件包,每个软件包分别包含一个 并了解它们之间的依赖关系。

使用标签引用目标

BUILD 文件和命令行中,Bazel 使用目标标签来引用 目标 - 例如 //:ProjectRunner//src/main/java/com/example/cmdline:runner。其语法如下:

//path/to/package:target-name

如果目标是规则目标,则 path/to/package 是指向 目录中包含 BUILD 文件,target-name 是您为其命名的 target 位于 BUILD 文件(name 属性)中。如果目标是文件 目标,则 path/to/package 是软件包根目录的路径; target-name 是目标文件的名称,包括其完整路径。

在代码库根目录中引用目标时,软件包路径为空。 只需使用 //:target-name 即可。引用同一 BUILD 中的目标时 您甚至可以跳过 // 工作区根标识符,直接使用 :target-name

例如,对于 java-tutorial/BUILD 文件中的目标,您无需执行以下操作: 请指定软件包路径,因为工作区根目录本身就是一个软件包 (//); 您的两个目标标签就分别是 //:ProjectRunner//:greeter

不过,对于 //src/main/java/com/example/cmdline/BUILD 文件中的目标, 必须指定 //src/main/java/com/example/cmdline 的完整软件包路径 您的目标标签为“//src/main/java/com/example/cmdline:runner”。

打包 Java 目标以进行部署

现在,我们将使用 运行时依赖项这样,您就可以在外部 开发环境。

如您所知,java_binary 构建规则 生成 .jar 和封装容器 shell 脚本。查看 runner.jar

jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar

内容如下:

META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class

如您所见,runner.jar 包含 Runner.class,但不包含其依赖项。 Greeting.class。Bazel 生成的 runner 脚本会添加 greeter.jar 添加到类路径,因此如果您按这样的方式处理,它会在本地运行, 无法在另一台机器上独立运行幸运的是,java_binary 规则 可让您构建一个可部署的独立二进制文件。如需进行构建,请将 _deploy.jar 附加到目标名称:

bazel build //src/main/java/com/example/cmdline:runner_deploy.jar

Bazel 会生成类似于以下内容的输出:

INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
INFO: Elapsed time: 1.700s, Critical Path: 0.23s

您刚刚构建了 runner_deploy.jar,它可以单独运行, 因为其中包含所需的运行时 依赖项使用 与之前相同的命令:

jar tf bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar

内容包括运行所需的所有类:

META-INF/
META-INF/MANIFEST.MF
build-data.properties
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class
com/example/Greeting.class

深入阅读

如需了解详情,请参阅以下文档:

祝您构建顺利!