BazelCon 2024 报名现已开放！

此页面由 Cloud Translation API 翻译。

Bazel 教程：构建 Java 项目

报告问题查看来源每晚 · 7.2。 · 7.1敬上 · 7.0 · 6.5 条 · 6.4。

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

预计所需时长：30 分钟。

学习内容

在本教程中，您将学习如何：

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

准备工作

安装 Bazel

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

安装 JDK

安装 Java JDK（首选版本为 11，但支持版本 8 到 15）。
将 JAVA_HOME 环境变量设置为指向 JDK。
- 在 Linux/macOS 上：
```
export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))"
```
- 在 Windows 上：
  1. 打开“控制面板”。
  2. 转到“系统和安全”>“系统”>“高级系统设置”>“高级”标签页 >“环境变量...”.
  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 文件的位置相对于工作区根目录（在本例中为根本身） ProjectRunner 是 BUILD 文件中的目标名称。（您将详细了解目标标签。）

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

深入阅读

如需了解详情，请参阅以下文档：

rules_jvm_external 用于规则来管理传递 Maven 依赖项。
外部依赖项：详细了解如何使用本地和远程代码库
用于详细了解 Bazel 的其他规则。
C++ 构建教程：开始进行构建使用 Bazel 的 C++ 项目。
Android 应用教程和 iOS 应用教程：使用入门如何使用 Bazel 构建 Android 和 iOS 移动应用

祝您构建顺利！