概览
本页包含 Fuchsia 特有的样式以及编写规则、宏和函数的最佳实践。这些始终在 .bzl 文件中定义,并且这些文件的指南也适用于此处。此外,与 BUILD.bazel 文件中的目标相关的指南也适用于由规则和宏定义的目标。
本页面是 Bazel 样式指南和最佳实践的一部分。
考虑新宏和函数是否合适
与 Bazel 样式指南一样,Fuchsia 更倾向于使用 DAMP(描述性和有意义的短语)BUILD 文件,而不是 DRY(不要重复)。
具体而言,与在 GN 中使用此类模板相比,Fuchsia build 在 Bazel 中使用特定于区域的宏和函数的频率要低得多。
使用共享的静态列表,其中内容必须保持同步(例如常见依赖项),而不是编写特定于区域的宏。
虽然特定于区域的模板可以减少在初始创建目标时输入的内容,但它们会成为维护和迁移问题,尤其是对于自动化工具,因为各个目标会被特定于区域的宏隐藏。如果您认为使用特定于区域的宏和函数会带来很大好处,请咨询构建团队(根据以往的经验,标准很高)。
尽可能优先使用现有宏和规则
随着此类宏或规则的潜在使用范围扩大,这一点的重要性也随之增加。
特别是,如果您的需求仅限于以下方面,请考虑是否可以使用现有宏和/或规则来实现:
正在生成元数据
强制执行属性值
例如,尽量减少调用方必须指定的属性数量
尤其是在前两种情况下,请考虑 Bazel 查询、SHAC 规则、测试或其他机制是否可以满足您的需求。Bazel 查询可以在依赖项树或目录树中定义的所有目标上运行。你能编写一个测试来运行查询并检查结果吗?如果您的用例需要额外属性,请考虑使用标记。
使用现有规则和宏的原因包括:
更易于理解,开发者的磨合期更短
熟悉 Bazel 的开发者可以快速上手并理解目标。
团队中某个部分的开发者可以了解代码库其他部分中的目标。
AI 更有可能理解和生成使用常见规则和宏的 Bazel 文件
需要更少的
load()语句内置标识符不需要任何 load 语句。
其他目标可能已加载到文件中的其他目标。
减少出现 bug 的机会
- 例如,只有当切面遍历所有相关目标时,它们才能正常工作。自定义宏或规则可能会引入不会被遵循的路径。请参阅使用标准属性名称。
首选符号宏,而非旧版宏
建议编写符号宏(使用 macro() 定义),而不是旧版宏(使用 def 定义的类似 Python 的函数,用于创建目标)。符号宏可提供更清晰的属性及其类型文档,对属性执行类型检查,并确保在调用网站上评估标签。它们还支持属性继承(通过 inherit_attrs)。如需了解更多背景信息,请参阅为什么不应使用旧版宏。
切勿在符号宏的实现函数中为实参指定默认值,因为默认值由 attrs 条目定义,并且系统会为每个属性提供一个值。
在某些情况下,有必要在符号宏周围使用旧版宏封装容器,但对于大多数开发者来说,这种情况应该非常罕见。
对宏中定义的目标进行可见性和访问权限检查
概览
为了便于理解可见性,您可以将旧版宏视为在实例化时内嵌展开。在 BUILD.bazel 文件中使用时,由旧版宏定义的目标实际上是在该文件中定义的。因此:
所定义目标的默认
visibility与实例化软件包相同,包括软件包default_visibility(如果已指定)。宏可以使用(例如,添加到
deps)对实例化软件包可见的任何目标。- 定义旧版宏的
.bzl文件的位置无关紧要。
- 定义旧版宏的
不过,出于可见性考虑,请将符号宏定义的目标视为在与定义宏的 .bzl 文件位于同一软件包(目录)中的 BUILD.bazel 文件中定义。因此:
所定义目标的默认
visibility是包含.bzl文件的软件包(目录)。宏可以使用(例如,添加到
deps)对包含.bzl文件的软件包(目录)可见的任何目标。例如,这对于
fidl_library()添加的 FIDL 绑定支持库非常有用。但对于 HLCPP 支持库许可清单等内容,这会带来问题。
如需了解详情,请参阅问题 446911800。
为宏中定义的目标指定公开范围
公开目标
将传递给宏的 visibility 属性转发给宏定义的主要目标(即 name 传递到的目标)。visibility 属性也可能会根据需要转发到宏的 doc 字符串中提及的其他已定义公共目标。
私有目标
在符号宏中,定义的所有其他目标的公开范围默认为 ["//visibility:private"]。不过,对于旧版宏,您必须为旧版宏定义的所有目标指定可见性。
为旧版宏定义的所有目标指定公开范围
为不使用传递给宏的 visibility 属性的所有目标指定 visibility = ["//visibility:private"]。这是为了防止它们默认使用软件包的 default_visibility(如果已指定)。
使用标准属性名称
在宏和规则中使用标准属性名称。例如,使用 "deps"、"data" 甚至 "tools",而不是 "images" 或 "scripts"。请参阅一些通常适用的属性。
原因包括:
为了提高可读性,以及出于与尽可能优先使用现有宏和规则中类似的其他原因。
切面只有在遍历所有相关目标时才能正常运行,并且宏通常会配置为应用于
"deps"和其他常见属性(视情况而定)。不过,他们不太可能知道"rust_deps"等属性,如果未能应用于该属性,可能会排除与该方面相关的目标。
需要具名实参
公共函数和旧版宏(一种特殊类型的函数)通常应声明仅限关键字的实参(所有实参都在 *, 之后声明)。如果函数最多只有几个实参,且实参可以从符号名称中清楚地看出,并且实参不会在错误的位置被误用(包括由于重构/重新排序),则可以例外。布尔值参数和具有默认值的参数应始终出现在 * 之后。
虽然这对于要由代码库的其他部分使用的符号最为重要,但也适用于所有 .bzl 文件中的公共符号。
这有助于强制执行 Bazel .bzl 样式指南的指导,即“调用宏时,仅使用关键字实参。这与规则一致,并大大提高了可读性。”
声明宏使用的所有实参
如果宏(可选)使用实参,请在宏实现的形参列表中明确声明该实参,而不是从 kwargs 中提取。例如,请避免以下情况:
# Do NOT do this:
testonly = kwargs.get("testonly", False),
声明实参可以更清楚地表明哪些实参与宏实现相关(例如,与它调用的宏相比),并提供一个查看默认值的位置。对于旧版宏,它还可确保记录实参。(这主要与 Fuchsia Bazel SDK 相关。)
与任何其他参数一样,但尤其是所有 build 规则通用的属性和所有测试规则通用的属性 (_test),您必须确保将该参数传递给支持它的所有宏和规则,因为这些宏和规则不会在 **kwargs 中。
符号宏中的可配置属性
在符号宏中,属性默认可配置,这意味着调用方可以传递 select() 表达式。对于可选属性,省略或 None 实参会解析为属性的默认值(将 None 传递给 mandatory = True 属性会被视为省略并失败)。对于可配置属性,Bazel 会自动将每个非 None 解析值(包括非 None 默认值,例如 False、"" 或 [])封装到 select() (SelectorList) 中,然后再将其传递给宏的 implementation 函数(而不可配置属性(例如 configurable = False、attr.output() 和 attr.output_list())会接收具体值)。只有默认值为 None 的可配置属性 - attr.label()(没有默认值或 default = None)和通过 inherit_attrs 继承的非强制性属性(其默认值被替换为 None,除非在 attrs 中被替换为非 None 默认值)- 在省略或传递 None 时会作为 None 到达(而传递 select({"//conditions:default": None}) 会传递 SelectorList)。
由于 select() 值在 Starlark 中始终为真,与具体值不相等(例如,attr == [] 始终为 False),并且无法迭代、编入索引、设置格式或放置在列表或字典字面量中,因此请勿对可配置属性或 select() 值执行需要具体值的操作 [SHAC 错误]:
布尔值求值:请勿使用
if attr:、not attr、attr or default或bool(attr)。使用attr == None或attr != None检查是否省略了默认值为None的可配置属性(没有非None默认值或非强制继承属性的attr.label())或传递了None。对于具有非None默认值的可配置属性(例如attr.bool()、attr.string()或attr.string_list()),Bazel 会将默认值封装在select()中,因此attr == None始终为False。容器字面量和迭代:请勿将可配置属性放在列表、元组或字典字面量(例如
[attr]或{"key": attr})中,也不要对其进行迭代 (for x in attr) 或将其传递给序列函数(len(attr)、list(attr))。使用+串联列表,使用|合并字典。值比较、字符串格式设置和方法调用:请勿将可配置属性与非
None值 (attr == "foo") 进行比较、设置其格式("%s" % attr或"{}".format(attr))、对其调用方法,或将其传递给不可配置属性(例如name、tags、testonly或visibility)。
如果宏实现必须检查、设置格式、迭代或分支属性值,或将其传递给不可配置的属性,请在 attrs 中使用 configurable = False 声明该属性。
评论
为所有公共函数(不以下划线开头的函数)提供函数级注释。
为所有规则和宏提供
doc字符串。为所有规则和宏属性提供
doc字符串。- 对于私有属性(以下划线开头的属性),如果其含义从
default值中显而易见,则可以省略doc字符串。
- 对于私有属性(以下划线开头的属性),如果其含义从
文档字符串
在 Fuchsia 平台中,
doc字符串应在源文件中读取,而不是在某些生成的文档中读取。因此,请优先考虑针对该情况进行优化,而不是考虑某些生成的文档可能是什么样子。长
doc字符串:在合理的情况下,最好将顶级单句说明完全写在与
doc=相同的行中。Bazel 中没有严格的行长度限制。
如果需要多行,请使用三引号编写多行字符串。
避免附加常规字符串。
多行
doc字符串在与
doc实参 (doc = """Begin the comment...) 相同的行上开始多行字符串。后续行从
doc中的d下方开始,类似于 Python 注释从第一个"下方开始下一行。这可以优化一致性和可读性,同时接受它不适合生成文本的事实。
多行字符串应以三引号 (
""") 结尾,且三引号应单独成行并与doc对齐。
规则和宏实现函数名称
为 rule() 和 macro() 实例的 implementation 函数命名时,请使用前导下划线,后跟规则或函数的名称,并以 _impl 结尾。
在宏中引用目标名称时使用变量
如果宏定义了一个目标,然后在另一个目标中依赖该目标,请使用前一个目标的名称定义一个变量,并将其用于其 name 属性和后一个目标的 deps 中。
这可以明确地关联两个目标,尤其是在基于其他目标名称存在多个级别的目标名称的复杂情况下,并且更易于突出显示和搜索。
请勿对内部未使用的目标使用变量,除非这样做可以提高可读性,例如在同一位置定义所有目标名称时。
封装内置和常用规则、宏和函数
在编写宏以替换 Fuchsia 平台代码库中的常见 Bazel 规则、宏或函数时,请在封装的名称前加上 fx_。例如,应使用 fx_cc_library(),而不是 cc_library()。
“Common”包括 Bazel 中内置的符号(包括 native.*)以及常见代码库(例如 rules_cc)中的符号。对于其他冲突(例如与 package 无关的 fx_package()),也请使用此前缀。请勿使用 fuchsia_ 前缀,因为 fuchsia_... 文件和符号位于 Fuchsia Bazel SDK 中。
添加新的 C/C++ 或 Rust 封装容器宏或规则时,请参阅 //build/bazel/rules/cc/README.md 或 //build/bazel/rules/rust/README.md,了解有关更新 bazel_fuchsia_wrappers SHAC 检查和相关文档的说明。
避免配置转换
Fuchsia 平台目标应该已经以正确的配置进行构建。如果您认为自己需要过渡,那么您很可能不需要。请与 Build 团队联系;只有 Build 团队可以添加转换或新平台。
将工具作为可执行标签属性传递
运行工具的规则应将其作为 attr.label(executable = True, cfg = "exec") 并使用 ctx.executable 读取。
反模式
正在通过
PATH查找工具。Infra 沙盒不会设置它,Bazel 无法跟踪它不知道的工具。而是将该工具作为可执行标签属性传递。将嵌入标签的 JSON 或字典 blob 传递到规则或宏中。Bazel 只能看到标签类型属性中的标签,因此不会构建或跟踪这些依赖项。请改用标签属性和提供程序。
通过
bazel-bin符号链接查找 build 输出。它指向一个配置,而转换可以将您想要的输出放入不同的bazel-out目录中。通过提供程序传递输出或明确报告其路径。依赖于上游规则集的实现细节,例如
rules_cc使用的_solib_目录前缀。当规则集更新时,它们会发生变化,恕不另行通知。
避免缓存或远程处理大型工件
请参阅避免缓存大型工件。