相约 2023 年 BazelCon 将于 10 月 24 日至 25 日在 Google 慕尼黑举办!了解详情

报告问题 查看源代码

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

宽高比可让您使用额外的信息和操作来扩充 build 依赖项关系图。下面是一些非常有用的典型场景:

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

方面基础知识

BUILD 文件用于说明项目的源代码:哪些源文件是项目的一部分、应基于这些文件构建哪些工件(目标),以及这些文件之间的依赖关系等等。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 文件)的操作,并将信息(例如这些工件的位置和名称)传递给提供程序中这些目标的反向依赖项。

方面与规则类似,因为它们具有用于生成操作并返回提供程序的实现函数。不过,它们的能力来自于为其构建依赖关系图的方式。方面有一个实现,以及它所传播的所有属性的列表。假设某个方面 A 沿着名为“依赖项”的属性传播。此宽高比可应用于目标 X,从而生成宽高比应用节点 A(X)。在应用 A 的过程中,它会以递归方式应用到 A 的“依赖项”属性中引用的所有目标(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 的另一个常见参数是 ['*'],用于将方面传播到规则的所有属性。

宽高比实现

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,可以生成操作,并采用两个参数:

  • target:应用宽高比的目标
  • ctxctx 对象,可用于访问属性以及生成输出和操作。

实现函数可以通过 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 的定义)的字符串属性。不能通过命令行使用具有参数的方面,因为没有参数可以定义语法。

各个方面还可以具有 labellabel_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,那么 A(X) 的 ctx.rule.attr.deps 将为 [A(Y), A(Z)]。在此示例中,ctx.rule.attr.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 以递归方式访问所有目标。

参考文档