切面

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

本页介绍了使用方面 (aspect) 的基础知识和优势，并提供了简单示例和高级示例。

方面允许使用其他信息和操作来扩充 build 依赖关系图。以下是一些方面可能很有用的典型场景：

集成 Bazel 的 IDE 可以使用方面来收集有关项目的信息。
代码生成工具可以利用方面以与 目标无关的方式对其输入执行操作。例如，BUILD 文件可以指定 protobuf 库定义的层次结构，而特定于语言的规则可以使用方面来附加为特定语言生成 protobuf 支持代码的操作。

方面基础知识

BUILD 文件提供了项目源代码的说明：哪些源文件是项目的一部分，应从这些文件构建哪些工件（目标），这些文件之间的依赖关系是什么等。Bazel 使用此信息执行 build，也就是说，它会找出生成工件所需的一组操作（例如运行编译器或链接器），并执行这些操作。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 文件）的操作，并将这些工件的位置和名称等信息传递给这些目标的反向依赖项（在提供程序中）。

方面与规则类似，因为它们都有一个实现函数，该函数会生成操作并返回提供程序。不过，它们的强大之处在于为其构建依赖关系图的方式。方面具有实现和它沿途传播的所有属性的列表。假设方面 A 沿名为“deps”的属性传播。此方面可以应用于目标 X，从而生成方面应用节点 A(X)。在应用期间，方面 A 会以递归方式应用于 X 在其“deps” 属性（A 的传播列表中的所有属性）中引用的所有目标。

因此，将方面 A 应用于目标 X 的单个操作会生成下图所示的目标的原始依赖关系图的“影子图”：

使用切面构建图表

图 2.包含方面的 build 图。

唯一被遮盖的边是沿传播集中的属性的边，因此在此示例中，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 的另一个常见实参是 ['*']，它会将方面传播到规则的所有属性。

方面实现

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 []

方面实现函数与规则实现函数类似。它们会返回提供程序，可以生成操作，并接受两个实参：

target：方面所应用的目标。
ctx：ctx 对象，可用于访问属性以及生成输出和操作。

实现函数可以通过 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 定义了方面的一组属性。公共方面属性的类型为 string，称为参数。参数必须指定values 属性。此示例有一个名为 extension 的参数，该参数的值可以是“*”“h”或“cc”。

方面的参数值取自与请求该方面的规则同名的字符串属性（请参阅 file_count_rule 的定义）。带有参数的方面无法通过命令行使用，因为没有用于定义参数的语法。

方面还允许具有类型为 label 或 label_list 的私有属性。私有标签属性可用于指定对方面生成的操作所需的工具或库的依赖项。在此示例中未定义私有属性，但以下代码段演示了如何将工具传递给方面：

...
    attrs = {
        '_protoc' : attr.label(
            default = Label('//tools:protoc'),
            executable = True,
            cfg = "exec"
        )
    }
...

方面实现

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，则 ctx.rule.attr.deps A(X) 的依赖项将为 [A(Y), A(Z)]。在此示例中，ctx.rule.attr.deps 是目标对象，这些对象是将方面应用于方面所应用到的原始目标的“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 = '*'),
    },
)

规则实现演示了如何访问 FileCountInfo 通过 ctx.attr.deps。

规则定义演示了如何定义参数 (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 以递归方式访问的所有目标进行评估。

切面 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

方面基础知识

简单示例

方面定义

方面实现

使用命令行调用方面

高级示例

方面定义

方面实现

从规则调用方面

通过目标规则调用方面

切面