构建样式指南

<ph type="x-smartling-placeholder"></ph> 报告问题 查看来源 敬上 每晚 · 7.3。 · 7.2 条 · 7.1 · 7.0 · 6.5

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，也可以命名为 java_library。 DirectMessage.java 可命名为 direct_message）。

软件包的同名目标（与 目录）所提供的功能， 目录名称。如果没有此类目标，请勿创建同名 目标。

提及同名目标时，更喜欢使用简称 (//x) 而不是 //x:x）。如果您在同一个软件包中，首选使用本地 引用（:x 而不是 //x）。

避免使用“预留”具有特殊含义的目标名称。这包括 all、__pkg__ 和 __subpackages__，这些名称具有特殊 并且可能会导致在使用时造成混淆和意外行为。

如果缺乏主要的团队惯例，则这些条款对团队没有约束力。 Google 广泛采纳的建议：

  • 一般情况下，请使用 &quot;snake_case&quot; <ph type="x-smartling-placeholder">
      </ph>
    • 对于包含一个 src 的 java_library，这意味着使用的名称 与不带扩展名的文件名相同
    • 对于 Java *_binary 和 *_test 规则，请使用 “Upper CamelCase”。 这样，目标名称就可以与其中一个 src 匹配。对于 java_test，这样就可以将 test_class 属性设为 。
  • 如果特定目标有多个变体，则向 消除歧义（例如:foo_dev、:foo_prod 或 :bar_x86、:bar_x64）
  • 为 _test 目标添加 _test、_unittest、Test 或 Tests 后缀
  • 避免使用 _lib 或 _library 等无意义的后缀（除非有必要 避免 _library 目标与其对应的 _binary 之间发生冲突）
  • 对于 proto 相关目标： <ph type="x-smartling-placeholder">
      </ph>
    • proto_library 个目标的名称应以 _proto 结尾
    • 特定于语言的 *_proto_library 规则应与底层规则 proto，但要将 _proto 替换为特定于语言的后缀，例如： <ph type="x-smartling-placeholder">
        </ph>
      • cc_proto_library：_cc_proto
      • java_proto_library：_java_proto
      • java_lite_proto_library：_java_proto_lite

公开范围

公开范围应尽可能缩小范围，同时仍允许访问 由测试和反向依赖项构成。将 __pkg__ 和 __subpackages__ 用作 适当的选择。

避免将软件包 default_visibility 设置为 //visibility:public。 //visibility:public只能为 项目的公共 API。这些库可能是专为依赖于 或二进制文件（可由外部项目的 构建流程

依赖项

依赖项应仅限于直接依赖项（依赖项 （规则中列出的来源所需）。请勿列出传递依赖项。

应首先列出软件包本地依赖项，并以某种方式引用它们 兼容 对当前软件包中的目标的引用 部分（而不是其绝对软件包名称）。

最好以单个列表的形式直接列出依赖项。将“常见” 将多个目标的依赖关系变为一个变量会降低可维护性， 工具不可能改变目标的依赖关系，这可能导致 未使用的依赖项

Glob

指明“无定位”尽在 []。不要使用没有任何匹配的 glob：它 比空列表更易出错，也不太明显。

递归

请勿使用递归 glob 来匹配源文件（例如， glob(["**/*.java"])）。

递归 glob 使 BUILD 文件难以推断，因为它们会跳过 包含 BUILD 文件的子目录。

递归 glob 的效率通常不如每个 glob 的 BUILD 文件 并在其之间定义了依赖关系图， 远程缓存和并行性

最好在每个目录中创建一个 BUILD 文件，并定义一个 它们之间的依赖关系图。

非递归

非递归 glob 通常可以接受。

其他惯例

  • 使用大写和下划线可声明常量（例如 GLOBAL_CONSTANT）， 使用小写字母和下划线来声明变量（例如 my_variable）。

  • 不得拆分标签，即使标签长度超过 79 个字符也是如此。 标签应尽可能采用字符串字面量。理由：它使 轻松查找和替换。还可以提高可读性。

  • 名称属性的值应为字面量常量字符串（除 宏）。说明：外部工具使用名称属性来引用 规则。他们需要在无需解读代码的情况下查找规则。

  • 设置布尔值类型的属性时，请使用布尔值，而不是整数值。 由于旧版原因，规则仍会根据需要将整数转换为布尔值， 但我们不建议这样做原因：flaky = 1 可能会被误读为 "通过重新运行一次来改善此目标的稳定性"。flaky = True含糊不清地说 “这个测试不太稳定”

与 Python 样式指南的差异

虽然 Python 样式指南 是目标，但两者之间有几点区别：

  • 没有严格的行长度限制。长注释和长字符串通常会被拆分 至 79 列，但这并不是必需的。不应在代码中强制执行 审核或提交前脚本。说明：标签可能很长，超过此限制 上限。通常由工具生成或修改 BUILD 文件， 就不太符合行长限制

  • 不支持隐式字符串串联。使用 + 运算符。 说明：BUILD 文件包含许多字符串列表。我们很容易忘记 这会生成完全不同的结果。这导致了很多错误 是过去的日期。另请参阅此讨论。

  • 对于规则中的关键字参数，在 = 符号前后加空格。依据： 命名参数比 Python 中的使用频率要高得多，并且始终位于 换行。聊天室可提高可读性。该大会由 很长时间，因此不值得修改现有的所有 BUILD 文件。

  • 默认情况下，为字符串使用双引号。说明：这并非 Python 样式指南中指定的名称，但建议保持一致。我们 决定仅使用双引号字符串。许多语言都使用英文双引号 。

  • 在两个顶级定义之间添加一个空白行。依据： BUILD 文件的结构与典型的 Python 文件不同。它只有 顶级语句。使用单个空白行可缩短 BUILD 文件。