Bazel通用定义

通用定义(common-definitions)

本节定义了以下许多功能或构建规则所共有的术语和概念。

内容(contents)

• Bourne Shell标记化
• 标签扩展(Label Expansion)
• 所有构建规则共有的属性(Attributes common to all build rules)
• 所有测试规则共有的属性（* _test）
• 所有二进制规则（* _binary）共有的属性
• 可配置属性(Configurable attributes)
• 隐式输出目标(implicit output targets)

Bourne Shell标记化

根据Bourne shell的标记化规则，某些规则的某些字符串属性会分成多个词：未用引号引起来的空格分隔单独的词，并且使用单引号和双引号字符以及反斜杠来防止标记化。

在本文档的定义中明确指出了受此标记化影响的那些属性。

受“ Make”变量扩展和Bourne shell标记化影响的属性通常用于将任意选项传递给编译器和其他工具。此类属性的示例为 cc_library.copts和java_library.javacopts。这些替换一起允许单个字符串变量扩展为特定于配置的选项字列表。

标签扩展

极少数规则的某些字符串属性会进行标签扩展：如果这些字符串包含有效的标签作为子字符串，例如//mypkg:target，并且该标签是当前规则的已声明先决条件，则会将其扩展为表示的文件的路径名按目标//mypkg:target。

示例属性包括genrule.cmd和 cc_binary.linkopts。在每种情况下，细节可能会因以下问题而有很大不同：如何处理扩展到多个文件的标签，等等。有关详细信息，请参阅规则属性文档。

所有构建规则共有的属性

本节描述所有构建规则共有的属性。
请注意，在标签列表属性中两次列出同一标签是错误的。

data

List of labels; optional此规则在运行时所需的文件列表。
data属性中 命名的目标*.runfiles（如果有的话）将出现在此规则的区域中。这可能包括二进制文件或库所需的数据文件，或它所需的其他程序。有关如何依赖和使用数据文件的更多信息，请参见 数据依赖项部分。几乎所有规则都允许一个data属性，但是在不允许该属性的情况下，此事实将在特定规则下记录。

visibility

List of labels; optional; default default_visibility from package if specified, or //visibility:private otherwise.``visibility`规则上 的属性控制该规则是否可以被其他包使用。规则对于同一包中声明的其他规则始终可见。可见性标签可以采用五种形式（和一种临时形式）：

• ["//visibility:public"]：任何人都可以使用此规则。
• ["//visibility:private"]：仅此软件包中的规则可以使用此规则。中的规则javatests/foo/bar 可以始终使用中的规则java/foo/bar。
• ["//some/package:__pkg__", "//other/package:__pkg__"]：只有规则some/package和other/package （定义some/package/BUILD和 other/package/BUILD）可以访问此规则。请注意，子包无权访问该规则。例如， //some/package/foo:bar否则 //other/package/testing:bla将无法访问。 __pkg__是一个特殊的目标，必须逐字使用。它代表包中的所有规则。
• ["//project:__subpackages__", "//other:__subpackages__"]：只有软件包project或其other子软件包之一中的规则可以访问此规则。例如 //project:rule，//project/library:lib或者 //other/testing/internal:munge被允许依赖此规则（但不是//independent:evil）
• ["//some/package:my_package_group"]：软件包组是一组命名的软件包名称。程序包组还可以授予对整个子树的访问权限，例如//myproj/...。

的可见性规范 //visibility:public，并//visibility:private 不能与其他任何知名度规范相结合。可见性规范可能包含包装标签（即//foo:__pkg__）和package_group的组合。

如果规则确实指定了可见性属性，则该规范将覆盖 包含该规则的BUILD文件中的语句的任何 [default_visibility](https://docs.bazel.build/versions/master/be/functions.html#package.default_visibility) 属性[package](https://docs.bazel.build/versions/master/be/functions.html#package)。

否则，如果规则未指定可见性属性，则使用程序包的default_visibility（exports_files除外 ）。

否则，如果未指定包的default_visibility， //visibility:private则使用。

范例：

文件 //frobber/bin/BUILD：

# This rule is visible to everyone
cc_binary(
    name = "executable",
    visibility = ["//visibility:public"],
    deps = [":library"],
)

# This rule is visible only to rules declared in the same package
cc_library(
    name = "library",
    visibility = ["//visibility:private"],
)

# This rule is visible to rules in package //object and //noun
cc_library(
    name = "subject",
    visibility = [
        "//noun:__pkg__",
        "//object:__pkg__",
    ],
)

# See package group "//frobber:friends" (below) for who can
# access this rule.
cc_library(
    name = "thingy",
    visibility = ["//frobber:friends"],
)

文件 //frobber/BUILD：

# This is the package group declaration to which rule
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
    name = "friends",
    packages = [
        "//fribber/...",
        "//frobber",
    ],
)

toolchains

List of [labels](https://docs.bazel.build/versions/master/build-ref.html#labels); optional

允许访问其规则 的Make变量的目标集。这些规则既可以是提供TemplateVariableInfo程序的规则，也可以是Bazel中内置的工具链类型的特殊目标。这些包括：

• @bazel_tools//tools/cpp:current_cc_toolchain
• @bazel_tools//tools/cpp:current_java_runtime

请注意，这与 规则实现用于平台相关配置的工具链解析概念不同 。您不能使用此属性来确定目标将使用哪个特定的cc_toolchain或java_toolchain。

deps

List of labels; optional

此规则的依赖项列表。

该规则依赖于另一个使用的含义的确切语义deps特定于此规则的种类，下面的特定于规则的文档将更详细地介绍。但是，至少有一个名为via的目标deps会出现在*.runfiles此规则的区域中（如果有的话）。

大多数情况下，deps依赖项用于允许一个模块使用以相同编程语言编写并单独编译的另一模块中定义的符号。在许多情况下，还允许跨语言依赖性：例如，一条java_library规则可以cc_library通过在deps属性中声明后者来依赖规则中的C ++代码。有关更多信息，请参见依赖性的定义。

几乎所有规则都允许一个deps属性，但是在不允许该属性的情况下，此事实将在特定规则下记录。

deprecation

String; optional

与该规则关联的说明性警告消息。通常，它用于通知用户某条规则已过时或已被另一条规则所取代，对某个包是私有的或出于某种原因可能被视为有害。最好包含一些参考信息（例如网页，错误号或示例迁移CL），以便人们可以轻松地找到需要哪些更改以避免出现此消息。如果有一个新目标可以用作替换目标，则最好迁移旧目标的所有用户。

该属性对构建事物的方式没有影响，但是可能会影响构建工具的诊断输出。当具有deprecation属性的规则被另一个规则所依赖时，构建工具会发出警告。

包内依赖项不受此警告的影响，因此，例如，构建不赞成使用的规则的测试不会遇到警告。

如果不推荐使用的规则依赖于另一个不推荐使用的规则，则不会发出警告消息。

一旦人们停止使用它，就可以将其取出。

tags

List of arbitrary text tags. Tags may be any valid string; default is the empty list.

标签可以在任何规则上使用。测试和 规则上的标签test_suite对于将测试分类非常有用。 非测试规则上的标记用于控制genrules和 Starlark 操作的沙盒执行 ，并用于人工和/或外部工具的解析。

如果Bazel在tags任何测试规则或的属性中或 任何Starlark操作genrule的键中找到以下关键字，则Bazel会修改其沙盒代码的行为execution_requirements。

• no-sandbox关键字导致动作或测试永远不会被 沙盒化 ; 它仍然可以缓存或远程运行-使用no-cache或no-remote 防止两者之一或全部。
• no-cache 关键字导致操作或测试永远不会被缓存（远程或本地）
• no-remote-cache关键字导致操作或测试永远不会被远程缓存（但可以在本地缓存；也可以远程执行）。注意：就此标记而言，磁盘缓存被视为本地缓存，而http和gRPC缓存被视为远程缓存。如果指定了组合缓存（即具有本地和远程组件的缓存），则将其视为远程缓存并完全禁用。
• no-remote-exec 关键字会导致操作或测试永远不会远程执行（但可能会远程缓存）。
• no-remote关键字可防止操作或测试被远程执行或远程缓存。这等效于同时使用no-remote-cache和no-remote-exec。
• local关键字可阻止操作或测试在沙盒中进行远程缓存，远程执行或运行 。对于类型和测试，使用local = True 属性标记规则具有相同的效果。
• requires-network关键字允许从沙箱内部访问外部网络。只有启用了沙箱功能，此标记才有效。
• block-network关键字会阻止从沙箱内部访问外部网络。在这种情况下，仅允许与本地主机通信。只有启用了沙箱功能，此标记才有效。
• requires-fakeroot以uid和gid 0（即root用户）运行测试或操作。仅在Linux上支持。此标记优先于 --sandbox_fake_username命令行选项。

测试上的标签通常用于注释测试在调试和发布过程中的角色。通常，标签对于缺少任何运行时注释功能的C ++和Python测试最有用。标签和大小元素的使用为基于代码库签入策略的测试套件组合提供了灵活性。

如果Bazel tags在测试规则的属性中找到以下关键字，则它会修改测试运行行为 ：

• exclusive关键字将强制测试以“独占”模式运行，确保没有其他测试同时运行。在完成所有构建活动和非排他性测试之后，将以串行方式执行此类测试。它们还将始终在本地运行，因此无需沙箱。
• manual关键字将迫使测试目标不被包括在目标图案通配符（...，:*，:all等）; 测试目标既不会构建也不会运行。test_suite没有明确提及该测试的规则也将忽略它。建立或运行这种测试的唯一方法是通过命令行上的显式目标模式进行指定。Bazel查询不接受该manual标记。
• external关键字将强制无条件执行测试（无论--cache_test_results 值如何）。

有关附加到测试规则的标签的更多约定，请参见“测试百科全书”中的“标记约定”。

testonly

Boolean; optional; default False except as noted

如果为True，则仅testonly目标（例如测试）可以依赖于此目标。

等效地，testonly不允许的规则不允许依赖于的任何规则testonly。

默认情况下， 测试（*_test规则）和测试套件（test_suite规则）testonly。

此属性旨在表示目标不应包含在发布到生产中的二进制文件中。

由于testonly是在构建时而非运行时强制执行的，并且会通过依赖关系树进行病毒传播，因此应明智地应用它。例如，对于单元测试有用的存根和伪造品也可能对涉及将要发布到生产中的相同二进制文件的集成测试有用，因此可能不应标记为仅测试。相反，即使因为危险而无条件地覆盖正常行为的规则，也可能会被链接为危险。

features

List of *features*. Default is the empty list.

功能上的规则修改功能上当前启用的包级通过功能属性。
例如，如果在软件包级别启用了功能['a'，'b']，并且规则功能属性包含['-a'，'c']，则为该规则启用的功能将为“ b”和“ c”。

licenses

List of strings; optional

用于此特定构建规则的许可证类型字符串的列表。这是Bazel不再使用的已弃用的许可API的一部分。不要使用这个。

compatible_with

List of [labels](https://docs.bazel.build/versions/master/build-ref.html#labels); optional

除了默认支持的环境之外，可以为该规则构建环境的列表。

这是Bazel的软启动约束系统的一部分，该系统使用户可以声明哪些规则可以相互依赖，也可以不相互依赖。例如，可外部部署的二进制文件不应依赖于带有公司机密代码的库。有关详细信息，请参见 ConstraintSemantics。

exec_properties

Dictionary of strings. Default is an empty dictionary.

字符串字典，将添加到exec_properties为此目标选择的平台的。见exec_properties的的平台规则。

如果平台和目标级别属性中都存在键，则将从目标中获取值。

distribs

List of strings; optional

用于此特定构建规则的分发方法字符串的列表。这是Bazel不再使用的已弃用的许可API的一部分。不要使用这个。

exec_compatible_with

List of [labels](https://docs.bazel.build/versions/master/build-ref.html#labels); optional

该列表 [constraint_values](https://docs.bazel.build/versions/master/be/platform.html#constraint_value) 必须存在于该目标的执行平台中。这是规则类型已经设置的任何约束的补充。约束用于限制可用执行平台的列表，有关详细信息，请参见 工具链解析的描述。

此属性仅在[genrule](https://docs.bazel.build/versions/master/be/general.html#genrule)， shell规则和所有测试规则（* _test）上可用。

|
| restricted_to |

List of [labels](https://docs.bazel.build/versions/master/build-ref.html#labels); optional

可以构建此规则的环境列表，而不是默认支持的环境。

这是Bazel的软启动约束系统的一部分。有关[compatible_with](https://docs.bazel.build/versions/master/be/common-definitions.html#common.compatible_with) 详细信息，请参见 。

|

所有测试规则共有的属性（* _test）

本节介绍所有测试规则共有的属性。

args

List of strings; optional; subject to [$(location)](https://docs.bazel.build/versions/master/be/make-variables.html#location) and ["Make variable"](https://docs.bazel.build/versions/master/be/make-variables.html) substitution, and [Bourne shell tokenization](https://docs.bazel.build/versions/master/be/common-definitions.html#sh-tokenization)

将这些参数添加到由--test_arg 执行时bazel test。

这些参数--test_arg在bazel test命令行上指定的值之前传递。

size

String "enormous", "large" "medium" or "small", default is "medium"; optional

测试多么“繁重”。

测试“繁重”的分类：需要运行多少时间/资源。

单元测试被认为是“小型”，集成测试被认为是“中”，端到端测试被认为是“大”或“巨大”。Bazel使用该大小来确定默认超时（可以使用timeout属性覆盖 ），以及运行测试必须获取的资源量。测试大小对应于以下资源和默认超时：

尺寸	内存（MB）	CPU（在CPU内核中）	默认超时
小	20	1个	短（1分钟）
介质	100	1个	中度（5分钟）
大	300	1个	长（15分钟）
巨大	800	1个	永恒（60分钟）

timeout

String "short", "moderate", "long", "eternal" (with the default derived from the test's size attribute)

返回之前，测试应运行多长时间。

虽然测试的大小属性控制资源估计，但是可以独立设置测试的超时。如果未明确指定，则超时基于测试的size。可以用该--test_timeout标志来覆盖测试超时，例如，用于在已知较慢的某些条件下运行。测试超时值对应于以下时间段：

超时值	时间段
短	1分钟
中等	5分钟
长	15分钟
永恒	60分钟

对于上述时间以外的其他时间，测试超时可以用--test_timeoutbazel标志覆盖 ，例如，在已知缓慢的条件下手动运行。该--test_timeout值以秒。例如，--test_timeout=120将测试超时设置为两分钟。

flaky

Boolean; optional

标记测试为片状。

如果设置，则在声明为失败之前最多执行3次测试。默认情况下，此属性设置为0，并且测试被认为是稳定的。请注意，通常不鼓励使用此属性-我们确实希望所有测试都稳定。

local

Boolean; optional

强制测试在本地运行，而无需沙箱测试。

默认情况下，此属性设置为0，并使用默认测试策略。这等效于提供“本地”作为标签（tags=["local"]）。

shard_count

小于或等于50的非负整数；可选的

指定用于运行测试的并行分片的数量。

该值将覆盖用于确定运行测试的并行分片数量的所有试探法。请注意，对于某些测试规则，可能首先需要此参数才能启用分片。另请参阅--test_sharding_strategy。

分片要求测试运行器支持测试分片协议。如果不是，那么它很可能会在每个分片中运行每个测试，这不是您想要的。

所有二进制规则（* _binary）共有的属性

本节介绍所有二进制规则共有的属性。

| args |

List of strings; optional; subject to [$(location)](https://docs.bazel.build/versions/master/be/make-variables.html#location) and ["Make variable"](https://docs.bazel.build/versions/master/be/make-variables.html) substitution, and [Bourne shell tokenization](https://docs.bazel.build/versions/master/be/common-definitions.html#sh-tokenization)

由run命令执行或作为测试执行时，bazel将传递给目标的命令行参数。这些参数在bazel run或 bazel test命令行上指定的参数之前传递。

注意：在bazel之外运行目标时（例如，通过在中手动执行二进制文件bazel-bin/），不会传递参数 。

大多数二进制规则都允许使用args属性，但是在不允许使用此属性的情况下，此事实记录在特定规则下。

|
| output_licenses |

List of strings; optional

该二进制文件生成的输出文件的许可证。这是Bazel不再使用的已弃用的许可API的一部分。不要使用这个。

|

可配置的属性

大多数属性都是“可配置的”，这意味着当以不同方式构建目标时，它们的值可能会更改。具体来说，可配置属性可能会根据传递给Bazel命令行的标志或请求目标的下游依赖关系而有所不同。例如，这可以用于为多个平台或编译模式自定义目标。

以下示例为不同的目标体系结构声明了不同的源。运行bazel build :multiplatform_lib --cpu x86 将使用构建目标x86_impl.cc，而替代 --cpu arm将导致使用目标arm_impl.cc。

cc_library（ name =“ multiplatform_lib”， srcs = select（{ “：x86_mode”：[“ x86_impl.cc”]， “：arm_mode”：[“ arm_impl.cc”] }） ） config_setting（ 名称=“ x86_mode”， 值= {“ cpu”：“ x86”} ） config_setting（ 名称=“ arm_mode”， 值= {“” cpu“：”手臂“} ）
 

该select()函数根据当前配置中满足的条件为可配置属性选择不同的替代值。 config_setting

在处理宏之后和处理规则之前（在技术上，在 加载和分析阶段之间）将评估可配置属性 。Bazel在select()评估之前进行的任何处理都不会知道将选择哪个分支。特别是，宏不能根据所选分支更改其行为，并且bazel query只能对目标的可配置依赖项做出保守的猜测；相反，在编写新类型的规则时，您无需担心可配置属性的歧义，因为所有 select()表达式都已经已由其解析值替换。有关与规则和宏结合 使用的更多信息，请参 见此常见问题解答select()。

nonconfigurable在其文档中 标记的属性不能使用此功能。通常，属性是不可配置的，因为Bazel内部需要知道其值才能确定如何选择 select()分支。

有关更多信息，请参见可 配置的构建属性。

隐式输出目标

在BUILD文件中定义构建规则时，将在包中显式声明一个新的命名规则目标。许多构建规则功能还隐式包含一个或多个输出文件目标，其内容和含义是特定于规则的。例如，当您明确声明一条 java_binary(name='foo', ...)规则时，您还将 隐式声明一个输出文件目标foo_deploy.jar为同一包的成员。（此特定目标是适合部署的自包含Java归档。）

隐式输出目标是全局目标图的一等成员。就像其他目标一样，它们是按需构建的，既可以在顶级构建命令中指定，也可以在其他构建目标的必要前提下使用。可以将它们称为BUILD文件中的依赖项，并且可以在分析工具（如）的输出中观察到bazel query。

对于每种构建规则，该规则的文档都包含一个特殊的部分，详细说明了由该类型的声明引起的任何隐式输出的名称和内容。

构建系统使用的两个名称空间之间的一个重要但有点微妙的区别： 标签标识目标（可以是规则或文件），目标文件可以分为源（或输入）文件目标和派生（或输出）文件目标。这些都是您可以在BUILD文件中提及的，从命令行构建或使用进行检查的内容bazel query；这是目标名称空间。每个文件目标对应一个磁盘上的实际文件（“文件系统名称空间”）；每个规则目标可能对应于磁盘上的零个，一个或多个实际文件。磁盘上可能有没有对应目标的文件；例如，.o在C ++编译过程中生成的目标文件不能从BUILD文件内部或命令行中引用。以这种方式，构建工具可以隐藏其工作方式的某些实现细节。这在《BUILD概念参考》中有更全面的说明。