Depset 是一种专门的数据结构，用于高效 收集目标传递依赖项中的数据。它们是规则处理的重要 元素。
Depset 的定义特征是其时间和空间高效的并集运算。 Depset 构造函数接受元素列表（“直接”）和其他 depset 列表（“传递”），并返回一个 depset，该 depset 表示一个包含所有 直接元素和所有传递集的并集的集合。从概念上讲， 构造函数会创建一个新图节点，该节点以直接节点和传递节点 作为其后继节点。Depset 具有明确定义的排序语义，基于 此图的遍历。
Depset 的使用示例包括：
存储程序库的所有对象文件的路径，然后可以 通过提供程序将这些路径传递给链接器操作。
对于解释型语言，存储包含在可执行文件的运行文件中的传递源文件。
说明和操作
从概念上讲，depset 是一个有向无环图 (DAG)，通常看起来 与目标图类似。它是从叶子到根构建的。 依赖项链中的每个目标都可以在 前一个目标的基础上添加自己的内容，而无需读取或复制这些内容。
DAG 中的每个节点都包含直接元素列表和子节点列表。 Depset 的内容是传递元素，例如所有节点的直接元素 。可以使用 depset构造函数创建新的 depset：它接受直接 元素列表和另一个子节点列表。
s = depset(["a", "b", "c"])
t = depset(["d", "e"], transitive = [s])
print(s) # depset(["a", "b", "c"])
print(t) # depset(["d", "e", "a", "b", "c"])
如需检索 depset 的内容，请使用 to_list() 方法。它会返回所有传递 元素的列表，不包括重复项。无法直接检查 DAG 的确切结构，不过此结构确实会影响返回元素的顺序 。
s = depset(["a", "b", "c"])
print("c" in s.to_list()) # True
print(s.to_list() == ["a", "b", "c"]) # True
Depset 中允许的项受到限制，就像字典中允许的键受到 限制一样。特别是，depset 内容可能不可变。
Depset 使用引用相等：depset 等于自身，但不等于任何其他 depset，即使它们具有相同的内容和相同的内部结构也是如此。
s = depset(["a", "b", "c"])
t = s
print(s == t) # True
t = depset(["a", "b", "c"])
print(s == t) # False
d = {}
d[s] = None
d[t] = None
print(len(d)) # 2
如需按内容比较 depset，请将它们转换为排序列表。
s = depset(["a", "b", "c"])
t = depset(["c", "b", "a"])
print(sorted(s.to_list()) == sorted(t.to_list())) # True
无法从 depset 中移除元素。如果需要这样做，您 必须读出 depset 的全部内容，过滤掉要 移除的元素，然后重新构建新的 depset。这种方法效率不高。
s = depset(["a", "b", "c"])
t = depset(["b", "c"])
# Compute set difference s - t. Precompute t.to_list() so it's not done
# in a loop, and convert it to a dictionary for fast membership tests.
t_items = {e: None for e in t.to_list()}
diff_items = [x for x in s.to_list() if x not in t_items]
# Convert back to depset if it's still going to be used for union operations.
s = depset(diff_items)
print(s) # depset(["a"])
顺序
to_list 操作会对 DAG 执行遍历。遍历的类型
取决于构建 depset 时指定的 顺序。Bazel 支持多种顺序非常有用，因为有时
工具会关心其输入的顺序。例如，链接器操作可能需要确保，如果 B 依赖于 A，则 A.o 在链接器的命令行中位于 B.o 之前。其他工具可能具有相反的要求。
支持三种遍历顺序：postorder、preorder 和
topological。前两种的工作方式与树
遍历
完全相同，只不过它们在 DAG 上运行并跳过已访问的节点。第三种顺序
的工作方式是从根到叶的拓扑排序，与
前序遍历基本相同，只不过共享子项仅在所有父项之后列出。
前序遍历和后序遍历作为从左到右的遍历运行，但请注意，在每个节点中
，直接元素相对于子项没有顺序。对于拓扑
顺序，没有从左到右的保证，即使是
“先列出所有父项，再列出子项”的保证也不适用于 DAG 的不同节点中存在
重复元素的情况。
# This demonstrates different traversal orders.
def create(order):
cd = depset(["c", "d"], order = order)
gh = depset(["g", "h"], order = order)
return depset(["a", "b", "e", "f"], transitive = [cd, gh], order = order)
print(create("postorder").to_list()) # ["c", "d", "g", "h", "a", "b", "e", "f"]
print(create("preorder").to_list()) # ["a", "b", "e", "f", "c", "d", "g", "h"]
# This demonstrates different orders on a diamond graph.
def create(order):
a = depset(["a"], order=order)
b = depset(["b"], transitive = [a], order = order)
c = depset(["c"], transitive = [a], order = order)
d = depset(["d"], transitive = [b, c], order = order)
return d
print(create("postorder").to_list()) # ["a", "b", "c", "d"]
print(create("preorder").to_list()) # ["d", "b", "a", "c"]
print(create("topological").to_list()) # ["d", "b", "c", "a"]
由于遍历的实现方式，必须在
使用构造函数的 order 关键字实参创建 depset 时指定顺序。如果省略此
实参，则 depset 具有特殊的 default 顺序，在这种情况下
无法保证其任何元素的顺序（但它是确定性的）。
完整示例
此示例位于 https://github.com/bazelbuild/examples/tree/main/rules/depsets。
假设有一种假设的解释型语言 Foo。如需构建
每个 foo_binary，您需要知道它直接或
间接依赖的所有 *.foo 文件。
# //depsets:BUILD
load(":foo.bzl", "foo_library", "foo_binary")
# Our hypothetical Foo compiler.
py_binary(
name = "foocc",
srcs = ["foocc.py"],
)
foo_library(
name = "a",
srcs = ["a.foo", "a_impl.foo"],
)
foo_library(
name = "b",
srcs = ["b.foo", "b_impl.foo"],
deps = [":a"],
)
foo_library(
name = "c",
srcs = ["c.foo", "c_impl.foo"],
deps = [":a"],
)
foo_binary(
name = "d",
srcs = ["d.foo"],
deps = [":b", ":c"],
)
# //depsets:foocc.py
# "Foo compiler" that just concatenates its inputs to form its output.
import sys
if __name__ == "__main__":
assert len(sys.argv) >= 1
output = open(sys.argv[1], "wt")
for path in sys.argv[2:]:
input = open(path, "rt")
output.write(input.read())
在这里，二进制文件 d 的传递源是 *.foo 的 srcs 字段中的所有 *.foo 文件，这些字段位于 a、b、c 和 d 中。为了让 foo_binary
目标了解 d.foo 之外的任何文件，foo_library 目标需要在
提供程序中传递这些文件。每个库都会从自己的
依赖项接收提供程序，添加自己的直接源，并传递包含
扩充内容的新提供程序。foo_binary 规则也会执行相同的操作，只不过它不是返回提供程序，而是使用完整的源列表为操作构建命令行。
以下是 foo_library 和 foo_binary 规则的完整实现。
# //depsets/foo.bzl
# A provider with one field, transitive_sources.
foo_files = provider(fields = ["transitive_sources"])
def get_transitive_srcs(srcs, deps):
"""Obtain the source files for a target and its transitive dependencies.
Args:
srcs: a list of source files
deps: a list of targets that are direct dependencies
Returns:
a collection of the transitive sources
"""
return depset(
srcs,
transitive = [dep[foo_files].transitive_sources for dep in deps])
def _foo_library_impl(ctx):
trans_srcs = get_transitive_srcs(ctx.files.srcs, ctx.attr.deps)
return [foo_files(transitive_sources=trans_srcs)]
foo_library = rule(
implementation = _foo_library_impl,
attrs = {
"srcs": attr.label_list(allow_files=True),
"deps": attr.label_list(),
},
)
def _foo_binary_impl(ctx):
foocc = ctx.executable._foocc
out = ctx.outputs.out
trans_srcs = get_transitive_srcs(ctx.files.srcs, ctx.attr.deps)
srcs_list = trans_srcs.to_list()
ctx.actions.run(executable = foocc,
arguments = [out.path] + [src.path for src in srcs_list],
inputs = srcs_list + [foocc],
outputs = [out])
foo_binary = rule(
implementation = _foo_binary_impl,
attrs = {
"srcs": attr.label_list(allow_files=True),
"deps": attr.label_list(),
"_foocc": attr.label(default=Label("//depsets:foocc"),
allow_files=True, executable=True, cfg="host")
},
outputs = {"out": "%{name}.out"},
)
您可以通过将这些文件复制到新软件包中、适当地重命名
标签、使用虚拟内容创建源 *.foo 文件以及
构建 d 目标来测试此项。
性能
如需了解使用 depset 的动机，请考虑如果
get_transitive_srcs() 在列表中收集其源会发生什么情况。
def get_transitive_srcs(srcs, deps):
trans_srcs = []
for dep in deps:
trans_srcs += dep[foo_files].transitive_sources
trans_srcs += srcs
return trans_srcs
这不会考虑重复项，因此 a
的源文件将在命令行中出现两次，在输出
文件的内容中出现两次。
另一种方法是使用通用集，该通用集可以通过
字典进行模拟，其中键是元素，所有键都映射到True。
def get_transitive_srcs(srcs, deps):
trans_srcs = {}
for dep in deps:
for file in dep[foo_files].transitive_sources:
trans_srcs[file] = True
for file in srcs:
trans_srcs[file] = True
return trans_srcs
这样可以消除重复项，但会使命令行 实参的顺序（以及文件的内容）不确定，不过仍然是确定性的。
此外，这两种方法在渐近意义上都比基于 depset 的方法差 。假设有一条很长的 Foo 库依赖项链。处理每个规则都需要将之前的所有传递 源复制到新的数据结构中。这意味着，分析单个库或二进制目标的时间和空间成本与其在链中的高度成正比。对于长度为 n 的链 foolib_1 ← foolib_2 ← … ← foolib_n，总成本实际上为 O(n^2)。
一般来说，当您通过传递依赖项累积 信息时，应使用 depset。这有助于确保 您的构建随着目标图的深度增加而良好扩缩。
最后，请务必不要在规则实现中不必要地检索 depset
的内容。在二进制规则的末尾调用一次 to_list()
即可，因为总成本仅为 O(n)。当许多非终端目标尝试调用 to_list() 时，才会出现二次行为。
如需详细了解如何高效使用 depset，请参阅性能页面。
API 参考
如需了解详情，请点击此处。