BUILD
文件格式设置遵循与 Go 相同的方法,使用标准化工具处理大多数格式设置问题。Buildifier 是一种以标准样式解析和发出源代码的工具。因此,每个 BUILD
文件都会以相同的自动化方式设置格式,这样在代码审核期间就不会出现格式设置问题。这也让工具可以更轻松地理解、修改和生成 BUILD
文件。
BUILD
文件格式必须与 buildifier
的输出一致。
格式设置示例
# Test code implementing the Foo controller.
package(default_testonly = True)
py_test(
name = "foo_test",
srcs = glob(["*.py"]),
data = [
"//data/production/foo:startfoo",
"//foo",
"//third_party/java/jdk:jdk-k8",
],
flaky = True,
deps = [
":check_bar_lib",
":foo_data_check",
":pick_foo_port",
"//pyglib",
"//testing/pybase",
],
)
文件结构
建议:请使用以下顺序(每个元素都是可选的):
文件包说明(注释)
所有
load()
对账单package()
函数。对规则和宏的调用
构建器可以区分独立注释和附加到元素的注释。如果注释未附加到特定元素,请在注释后面添加一个空行。在执行自动更改时(例如,在删除规则时保留或移除注释),这种区别非常重要。
# Standalone comment (such as to make a section in a file)
# Comment for the cc_library below
cc_library(name = "cc")
对当前软件包中的目标的引用
应通过相对于软件包目录的路径引用文件(无需使用向上引用,例如 ..
)。生成的文件应带有“:
”前缀,以表明它们不是源文件。源文件不应带有 :
前缀。规则应带有 :
前缀。例如,假设 x.cc
是一个源文件:
cc_library(
name = "lib",
srcs = ["x.cc"],
hdrs = [":gen_header"],
)
genrule(
name = "gen_header",
srcs = [],
outs = ["x.h"],
cmd = "echo 'int x();' > $@",
)
目标命名
目标名称应具有描述性。如果目标包含一个源文件,则目标通常应具有派生自该来源的名称(例如,chat.cc
的 cc_library
可以命名为 chat
,DirectMessage.java
的 java_library
可以命名为 direct_message
)。
软件包的同名目标(与所在目录同名的目标)应提供目录名称所描述的功能。如果没有此类目标,请勿创建同名目标。
在引用同名目标时,更喜欢使用简称(//x
而不是 //x:x
)。如果您在同一个软件包中,请首选本地引用(:x
而不是 //x
)。
避免使用具有特殊含义的“预留”目标名称。其中包括 all
、__pkg__
和 __subpackages__
,这些名称具有特殊语义,使用这些名称可能会导致混淆和意外行为。
在没有主要的团队惯例的情况下,下面是 Google 广泛采用的一些非约束性建议:
- 一般情况下,请使用 "snake_case"
- 对于包含一个
src
的java_library
,这意味着使用的名称与不带扩展名的文件名不同 - 对于 Java
*_binary
和*_test
规则,请使用“大写驼峰命名法”。这样,目标名称就可以与其中一个src
匹配。对于java_test
,这可以根据目标的名称推断出test_class
属性。
- 对于包含一个
- 如果某个目标有多个变体,请添加后缀以消除歧义(例如
:foo_dev
、:foo_prod
或:bar_x86
、:bar_x64
) - 为
_test
目标添加_test
、_unittest
、Test
或Tests
后缀 - 避免使用
_lib
或_library
等无意义的后缀(除非有必要以避免_library
目标与其对应的_binary
之间发生冲突) - 对于 proto 相关目标:
proto_library
个目标的名称应以_proto
结尾- 特定于语言的
*_proto_library
规则应与底层 proto 匹配,但需将_proto
替换为特定于语言的后缀,例如:cc_proto_library
:_cc_proto
java_proto_library
:_java_proto
java_lite_proto_library
:_java_proto_lite
可见性
您应尽可能缩小可见性范围,同时仍允许测试和反向依赖项访问。请根据需要使用 __pkg__
和 __subpackages__
。
避免将软件包 default_visibility
设置为 //visibility:public
。只能为项目的公共 API 中的目标单独设置 //visibility:public
。这些库可以是设计为供外部项目依赖的库,也可以是可供外部项目的构建流程使用的二进制文件。
依赖项
依赖项应仅限于直接依赖项(规则中列出的来源所需的依赖项)。请勿列出传递依赖项。
应首先列出软件包本地依赖项,并以与上面对当前软件包中的目标的引用部分兼容的方式引用它们(而不是通过其绝对软件包名称)。
最好以单个列表的形式直接列出依赖项。将多个目标的“通用”依赖项放在一个变量中会降低可维护性,使工具无法更改目标的依赖项,并且可能导致未使用的依赖项。
Glob
使用 []
表示“无定位”。请勿使用与任何内容都不匹配的 glob:与空列表相比,它更容易出错,也不太明显。
递归
请勿使用递归 glob 来匹配源文件(例如 glob(["**/*.java"])
)。
递归 glob 使 BUILD
文件难以推断,因为它们会跳过包含 BUILD
文件的子目录。
与为每个目录创建 BUILD
文件并在它们之间定义依赖关系图相比,递归 glob 的效率较低,因为这样可以提供更好的远程缓存和并行性。
最好在每个目录中创建一个 BUILD
文件,并定义它们之间的依赖关系图。
非递归
非递归 glob 通常可以接受。
其他惯例
使用大写和下划线可声明常量(如
GLOBAL_CONSTANT
),使用小写和下划线可声明变量(如my_variable
)。不得拆分标签,即使标签长度超过 79 个字符也是如此。标签应尽可能采用字符串字面量。说明:它使查找和替换变得简单。还可以提高可读性。
名称属性的值应为字面量常量字符串(宏除外)。说明:外部工具使用名称属性来引用规则。他们需要在无需解读代码的情况下查找规则。
设置布尔值类型的属性时,请使用布尔值,而不是整数值。由于旧版原因,规则仍会根据需要将整数转换为布尔值,但不建议这样做。原因:
flaky = 1
可能会被误读为“通过重新运行一次来降低此目标的稳定性”。flaky = True
明确地说“此测试不稳定”。
与 Python 样式指南的差异
虽然目标是实现与 Python 样式指南的兼容性,但也存在一些差异:
没有严格的行长度限制。长注释和长字符串通常会拆分为 79 列,但这并不是必需的。而不应在代码审核或提交前脚本中强制执行。说明:标签可能很长,可能超过此限制。
BUILD
文件由工具生成或修改,这种情况很常见,不符合行长度限制。不支持隐式字符串串联。使用
+
运算符。 说明:BUILD
文件包含许多字符串列表。我们很容易忘记一个逗号,而这会得到完全不同的结果。过去这导致了很多错误。另请参阅此讨论。对于规则中的关键字参数,在
=
符号前后加空格。说明:命名参数比 Python 中更为频繁,并且始终位于单独的一行。聊天室可提高可读性。这种惯例已经实施了很长时间,不值得修改所有现有的BUILD
文件。默认情况下,为字符串使用双引号。说明:Python 样式指南中未指定此设置,但建议一致性。因此,我们决定仅使用英文双引号字符串。许多语言在字符串字面量中使用英文双引号。
在两个顶级定义之间添加一个空白行。说明:
BUILD
文件的结构与典型的 Python 文件不同。它只有顶级语句。使用单个空白行可缩短BUILD
文件。