依赖项

报告问题 查看源代码 每夜 build · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

如果目标 A 在构建或执行时需要目标 B,则 A 依赖于 Bdepends upon 关系会在目标上诱导出有向无环图 (DAG),称为依赖关系图

目标的直接依赖项是指依赖项图中长度为 1 的路径可到达的其他目标。目标的传递依赖项是指通过图表中任意长度的路径依赖于该目标的目标。

事实上,在 build 上下文中,有两个依赖项图,一个是实际依赖项图,另一个是声明的依赖项图。大多数情况下,这两个图表非常相似,因此无需进行这种区分,但对于下面的讨论,这种区分很有用。

实际依赖项和声明的依赖项

如果必须存在、构建并保持最新的 Y,才能正确构建 X,则目标 X 实际上依赖于目标 Y已构建可以是指生成、处理、编译、关联、归档、压缩、执行或构建期间常规发生的任何其他类型的任务。

如果 X 的软件包中存在从 XY 的依赖项边,则目标 X 对目标 Y 具有声明的依赖项

为了构建正确的 build,实际依赖项 A 的图必须是声明的依赖项 D 的子图。也就是说,A 中的每对直接连接的节点 x --> y 也必须在 D 中直接连接。可以说,D 是对 A过度近似

BUILD 文件写入器必须向构建系统明确声明每个规则的所有实际直接依赖项,且不得超出此范围。

违反此原则会导致未定义的行为:构建可能会失败,但更糟糕的是,构建可能会依赖于某些先前的操作,或者依赖于目标偶然具有的传递声明的依赖项。Bazel 会检查是否缺少依赖项并报告错误,但在所有情况下都无法完成此检查。

您无需(也不应)尝试列出所有间接导入的内容,即使 A 在执行时需要这些内容也是如此。

在构建目标 X 期间,构建工具会检查 X 依赖项的整个传递闭包,以确保这些目标中的任何更改都会反映在最终结果中,并根据需要重新构建中间文件。

依赖项的传递性质会导致一个常见错误。有时,一个文件中的代码可能会使用间接依赖项提供的代码,即声明的依赖关系图中传递但非直接的边。间接依赖项不会显示在 BUILD 文件中。由于规则不直接依赖于提供程序,因此无法跟踪更改,如以下示例时间轴所示:

1. 声明的依赖项与实际依赖项相符

起初,一切都很顺利。a 软件包中的代码使用 b 软件包中的代码。b 软件包中的代码使用 c 软件包中的代码,因此 ac 具有传递依赖项。

a/BUILD b/BUILD
rule(
    name = "a",
    srcs = "a.in",
    deps = "//b:b",
)
      
rule(
    name = "b",
    srcs = "b.in",
    deps = "//c:c",
)
      
a / a.in b / b.in
import b;
b.foo();
    
import c;
function foo() {
  c.bar();
}
      
声明的依赖关系图,其中箭头连接了 a、b 和 c
声明的依赖关系图
与声明的依赖关系图匹配的实际依赖关系图,其中箭头连接了 a、b 和 c
实际依赖关系图

声明的依赖项过于近似于实际依赖项。一切顺利。

2. 添加未声明的依赖项

如果有人向 a 添加了会对 c 创建直接实际依赖项的代码,但忘记在 build 文件 a/BUILD 中声明该依赖项,就会引入潜在的隐患。

a / a.in  
        import b;
        import c;
        b.foo();
        c.garply();
      
 
声明的依赖关系图,其中箭头连接了 a、b 和 c
声明的依赖关系图
实际依赖图,其中箭头连接了 a、b 和 c。现在,箭头还将 A 连接到 C。这与声明的依赖项图不符
实际依赖关系图

声明的依赖项不再过于近似于实际依赖项。这可能可以正常构建,因为这两个图的传递闭包是等同的,但掩盖了一个问题:ac 有实际但未声明的依赖项。

3. 声明的依赖项图与实际依赖项图之间存在差异

当有人重构 b 使其不再依赖 c 时,就会发现此隐患,而他们并无过错,只是无意中破坏了 a

  b/BUILD
 
rule(
    name = "b",
    srcs = "b.in",
    deps = "//d:d",
)
      
  b / b.in
 
      import d;
      function foo() {
        d.baz();
      }
      
声明的依赖项图,其中箭头连接了 a 和 b。
                  b 不再连接到 c,这会断开 a 与 c 的连接
声明的依赖关系图
实际依赖项图,显示 a 连接到 b 和 c,但 b 不再连接到 c
实际依赖关系图

现在,声明的依赖项图表是对实际依赖项的近似估计,即使在传递关闭的情况下也是如此;构建可能会失败。

若要避免此问题,可以确保在 BUILD 文件中正确声明第 2 步中引入的 ac 的实际依赖项。

依赖项类型

大多数 build 规则都有三个属性,用于指定不同类型的通用依赖项:srcsdepsdata。具体说明如下。如需了解详情,请参阅所有规则共有的属性

许多规则还具有针对规则专用类型的依赖项(例如 compilerresources)的其他属性。如需了解详情,请参阅构建百科全书

srcs 依赖项

输出源文件的规则直接使用的文件。

deps 依赖项

指向提供头文件、符号、库、数据等的单独编译模块的规则

data 依赖项

构建目标可能需要一些数据文件才能正常运行。这些数据文件不是源代码:它们不会影响目标的构建方式。例如,单元测试可以将函数的输出与文件的内容进行比较。构建单元测试时,您无需该文件,但在运行测试时需要该文件。这同样适用于在执行期间启动的工具。

构建系统会在隔离的目录中运行测试,其中仅包含列为 data 的文件。因此,如果二进制文件/库/测试需要一些文件才能运行,请在 data 中指定这些文件(或包含这些文件的 build 规则)。例如:

# I need a config file from a directory named env:
java_binary
(
    name
= "setenv",
   
...
    data
= [":env/default_env.txt"],
)

# I need test data from another directory
sh_test
(
    name
= "regtest",
    srcs
= ["regtest.sh"],
    data
= [
       
"//data:file1.txt",
       
"//data:file2.txt",
       
...
   
],
)

您可以使用相对路径 path/to/data/file 访问这些文件。在测试中,您可以通过连接测试的源目录路径和相对于工作区的路径(例如 ${TEST_SRCDIR}/workspace/path/to/data/file)来引用这些文件。

使用标签引用目录

查看 BUILD 文件时,您可能会注意到某些 data 标签会引用目录。这些标签以 /./ 结尾,如以下示例所示,您不应使用这些标签:

不推荐 - data = ["//data/regression:unittest/."]

不推荐 - data = ["testdata/."]

不推荐 - data = ["testdata/"]

这似乎很方便,尤其是对于测试,因为它允许测试使用目录中的所有数据文件。

但请尽量不要这样做。为了确保在发生更改后正确进行增量重新构建(以及重新执行测试),构建系统必须知道构建(或测试)的输入文件的完整集。当您指定目录时,构建系统仅在目录本身发生更改(由于添加或删除文件)时才会执行重新构建,但无法检测对各个文件的修改,因为这些更改不会影响封闭目录。您应枚举目录中包含的一组文件,而不是将目录指定为构建系统的输入,可以明确枚举,也可以使用 glob() 函数枚举。(使用 ** 强制 glob() 进行递归。)

推荐 - data = glob(["testdata/**"])

遗憾的是,在某些情况下,必须使用目录标签。例如,如果 testdata 目录包含名称不符合标签语法的文件,则对文件进行显式枚举或使用 glob() 函数会导致标签无效错误。在这种情况下,您必须使用目录标签,但要注意上述重建不正确的相关风险。

如果您必须使用目录标签,请注意,您不能使用相对 ../ 路径引用父级软件包;而应使用绝对路径(例如 //data/regression:unittest/.)。

任何需要使用多个文件的外部规则(例如测试)都必须明确声明其对所有这些文件的依赖项。您可以使用 filegroup()BUILD 文件中将文件分组:

filegroup(
        name
= 'my_data',
        srcs
= glob(['my_unittest_data/*'])
)

然后,您可以在测试中将标签 my_data 引用为数据依赖项。