本页面介绍了使用方面的基础知识和优势,并提供了简单和高级的示例。
您可以通过添加维度来通过额外的信息和操作增强 build 依赖关系图。可以从以下方面着手的典型场景:
- 集成了 Bazel 的 IDE 可以使用多个方面来收集项目的相关信息。
- 代码生成工具可以利用各方面以与目标无关的方式对输入执行相关操作。例如,
BUILD
文件可以指定 protobuf 库定义的层次结构,而特定于语言的规则可以使用各方面来附加为特定语言生成 protobuf 支持代码的操作。
Aspect 基础知识
BUILD
文件提供项目源代码的说明:项目包含哪些源文件、应根据这些文件构建哪些工件(目标),以及这些文件之间的依赖关系等。Bazel 使用这些信息来执行构建,也就是说,Bazel 会使用这些信息执行构建,也就是说,它会确定生成工件所需的一组操作(例如运行编译器或链接器),并执行这些操作。为此,Bazel 会在目标之间构建一个依赖关系图,然后访问此图来收集这些操作。
我们来考虑以下 BUILD
文件:
java_library(name = 'W', ...)
java_library(name = 'Y', deps = [':W'], ...)
java_library(name = 'Z', deps = [':W'], ...)
java_library(name = 'Q', ...)
java_library(name = 'T', deps = [':Q'], ...)
java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...)
此 BUILD
文件定义了一个依赖关系图,如下图所示:
图 1. BUILD
文件依赖关系图。
Bazel 通过针对上述示例中的每个目标调用相应规则(在本例中为“java_library”)的实现函数来分析此依赖关系图。规则实现函数会生成用于构建工件(例如 .jar
文件)的操作,并将信息(例如这些工件的位置和名称)传递给 provider 中这些目标的反向依赖项。
方面与规则类似,因为它们具有一个实现函数,可生成操作并返回提供程序。不过,它们的强大能力来自为其构建依赖关系图的方式。一个方面有一个实现,以及一个与其传播的所有属性的列表。假设有一个方面 A,它沿名为“deps”的属性进行传播。该宽高比可应用于目标 X,从而产生宽高比应用节点 A(X)。在应用期间,A 将递归地应用到 X 在其“deps”属性(A 的传播列表中的所有属性)中引用的所有目标。
因此,将方面 A 应用到目标 X 的单个操作会生成目标的原始依赖关系图的“影子图”,如下图所示:
图 2. 包含各方面的图表。
唯一被阴影的边是沿传播集中属性的边,因此在此示例中,runtime_deps
边不会被阴影。然后,系统会在影子图中的所有节点上调用方面实现函数,类似于在原始图的节点上调用规则实现的方式。
简单示例
此示例演示了如何以递归方式输出规则及其所有依赖项(具有 deps
属性)的源文件。它显示了切面实现、切面定义,以及如何从 Bazel 命令行调用切面。
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
我们将这个示例分成几部分,然后逐一查看每个部分。
切面定义
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
方面定义与规则定义类似,也是使用 aspect
函数定义的。
就像规则一样,切面也有一个实现函数,在本例中为 _print_aspect_impl
。
attr_aspects
是宽高比传播时遵循的规则属性的列表。在这种情况下,切面将沿其所应用到的规则的 deps
属性传播。
attr_aspects
的另一个常见参数是 ['*']
,该参数会将方面传播到规则的所有属性。
Aspect 实现
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
方面实现函数与规则实现函数类似。它们会返回 providers,可以生成操作并使用两个参数:
实现函数可以通过 ctx.rule.attr
访问目标规则的属性。它可以检查由它应用到的目标所提供的提供程序(通过 target
参数)。
必须提供参数才能返回提供程序列表。在此示例中,方面不提供任何内容,因此它返回一个空列表。
使用命令行调用切面
如需应用某个方面,最简单的方法是使用 --aspects
参数从命令行运行。假设上述方面是在名为 print.bzl
的文件中定义,如下所示:
bazel build //MyExample:example --aspects print.bzl%print_aspect
会将 print_aspect
应用于目标 example
以及可通过 deps
属性递归访问的所有目标规则。
--aspects
标志接受一个参数,该参数是宽高比的规范,格式为 <extension file label>%<aspect top-level name>
。
高级示例
以下示例演示了如何使用目标规则中的一个方面,该方面用于统计目标中的文件,并且可能会按扩展名进行过滤。其中介绍了如何使用提供程序返回值、如何使用参数将参数传递到某个类实现,以及如何从规则调用某个类。
file_count.bzl
文件:
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
BUILD.bazel
文件:
load('//:file_count.bzl', 'file_count_rule')
cc_library(
name = 'lib',
srcs = [
'lib.h',
'lib.cc',
],
)
cc_binary(
name = 'app',
srcs = [
'app.h',
'app.cc',
'main.cc',
],
deps = ['lib'],
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
切面定义
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
以下示例展示了宽高比如何通过 deps
属性传播。
attrs
用于为一个方面定义一组属性。公共宽高比属性用于定义参数,只能是 bool
、int
或 string
类型。对于规则传播的方面,必须为 int
和 string
参数指定 values
。此示例有一个名为 extension
的参数,该参数可以使用“*
”“h
”或“cc
”作为值。
对于规则传播的方面,参数值从请求方面的规则中获取,并使用具有相同名称和类型的规则的特性。(请参阅 file_count_rule
的定义)。
对于命令行,可以使用 --aspects_parameters
标志传递参数值。可以省略 int
和 string
参数的 values
限制。
维度还可以具有 label
或 label_list
类型的私有属性。私有标签属性可用于指定方面生成的操作所需的工具或库的依赖关系。此示例中未定义私有属性,但以下代码段展示了如何将工具传递给某个方面:
...
attrs = {
'_protoc' : attr.label(
default = Label('//tools:protoc'),
executable = True,
cfg = "exec"
)
}
...
Aspect 实现
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
就像规则实现函数一样,方面实现函数会返回可供其依赖项访问的提供程序的结构。
在此示例中,FileCountInfo
被定义为具有一个字段 count
的提供程序。最佳实践是使用 fields
属性明确定义提供程序的字段。
方面应用 A(X) 的提供程序集合,来自于目标 X 的规则的实现和方面 A 的实现。规则实现传播的提供程序在应用各方面之前创建和冻结,无法从某个方面进行修改。如果目标和应用于它的方面各自提供的提供程序类型相同,但 OutputGroupInfo
(合并,只要规则和形式指定不同的输出组)和 InstrumentedFilesInfo
(从方面获取)除外,就会出错。这意味着切面实现可能永远不会返回 DefaultInfo
。
参数和私有属性在 ctx
的属性中传递。此示例引用了 extension
参数并确定要统计的文件。
对于返回提供程序,宽高比传播时(来自 attr_aspects
列表)的属性值会替换为对它们应用切面的结果。例如,如果目标 X 的依赖项中包含 Y 和 Z,则 A(X) 的 ctx.rule.attr.deps
将为 [A(Y), A(Z)]。
在此示例中,ctx.rule.attr.deps
是 Target 对象,它是将切面应用于已应用切面的原始目标的“deps”的结果。
在该示例中,宽高比从目标的依赖项访问 FileCountInfo
提供程序,以累积总传递文件数。
从规则调用切面
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
规则实现演示了如何通过 ctx.attr.deps
访问 FileCountInfo
。
规则定义演示了如何定义参数 (extension
) 并为其指定一个默认值 (*
)。请注意,如果默认值不是“cc
”“h
”或“*
”中的任何值,由于对切面定义中的参数施加的限制,将会导致错误。
通过目标规则调用切面
load('//:file_count.bzl', 'file_count_rule')
cc_binary(
name = 'app',
...
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
这演示了如何通过规则将 extension
参数传入切面。由于在规则实现中 extension
参数具有默认值,因此 extension
将被视为可选参数。
构建 file_count
目标后,系统会对切面本身进行评估,并且可以通过 deps
递归访问所有目标。