相约 2023 年 BazelCon 将于 10 月 24 日至 25 日在 Google 慕尼黑举办！报名现已开放！ 了解详情

此页面由 Cloud Translation API 翻译。

函数

包裹

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

此函数声明适用于软件包中每个后续规则的元数据。它最多只能在一个软件包（BUILD 文件）中使用一次。

package() 函数应该在文件顶部的所有 load() 语句之后、任何规则之前调用。

参数

属性	说明
`default_applicable_licenses`	`default_package_metadata` 的别名。
`default_visibility`	`List of labels; optional` 此软件包中规则的默认可见性。此软件包中的每条规则都具有此属性中指定的可见性，除非该规则的 `visibility` 特性中另行指定。如需详细了解此属性的语法，请参阅可见性文档。软件包默认可见性不适用于 exports_files，后者默认为公开。
`default_deprecation`	`String; optional` 设置此软件包中所有规则的默认 `deprecation` 消息。
`default_package_metadata`	`List of labels; optional` 设置一个默认元数据列表，并将其应用于软件包中的所有其他目标。这些目标通常是与 OSS 软件包和许可声明有关的目标。如需查看示例，请参阅 rules_license。
`default_testonly`	`Boolean; optional; default is False except as noted` 为该软件包中的所有规则设置默认的 `testonly` 属性。在 `javatests` 下的软件包中，默认值为 1。
`features`	`List strings; optional` 设置会影响此 BUILD 文件语义的各种标志。此功能主要供构建构建系统的人标记需要某种特殊处理的软件包。除非是构建系统的成员明确请求，否则请勿使用此参数。

示例

以下声明声明只有软件包组 //foo:target 的成员可以看到此软件包中的规则。针对规则的单个可见性声明（如果存在）会覆盖此规范。

package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

此函数会定义一组软件包，并将标签与该组相关联。可以在 visibility 属性中引用标签。

软件包组主要用于控制可见性。您可以从源代码树中的每个软件包引用公开的目标。不公开可见的目标只能在自己的软件包（而不是子软件包）中引用。在这两种极端情况下，目标可能会允许访问其自己的软件包以及由一个或多个软件包组描述的任何软件包。如需详细了解可见性系统，请参阅可见性属性。

如果某个给定软件包与 packages 属性匹配，或者已包含在 includes 属性中提及的其他软件包组中，则会被视为在该组中。

软件包组在技术上是目标，但不是由规则创建的，本身本身没有任何可见性保护。

参数

属性说明

属性	说明
`name`	`Name; required` 此目标的唯一名称。
`packages`	`List of strings; optional` 零个或多个软件包规范的列表。每个软件包规范字符串都可以采用下列格式之一：软件包的全称，不带代码库，以双斜杠开头。例如，`//foo/bar` 会指定具有该名称且与软件包组位于同一代码库中的软件包。如上所示，但末尾使用了 `/...`。例如，`//foo/...` 会指定 `//foo` 集及其所有子软件包。`//...` 指定当前代码库中的所有软件包。字符串 `public` 或 `private`，它们分别指定每个软件包或未指定软件包。（此表单需要设置 `--incompatible_package_group_has_public_syntax` 标志。）此外，前两种软件包规范也可以使用“`-`”的前缀来表示它们是否定的。软件包组包含至少符合其一个肯定规范且没有排除的规范的任何软件包。例如，值 `[//foo/..., -//foo/tests/...]` 包含 `//foo` 的所有子软件包，这些子软件包也不是 `//foo/tests` 的子软件包。（不包含 `//foo` 本身，而 //foo/tests 本身不包含在内）。除了公开可见性之外，无法直接指定当前代码库之外的软件包。如果缺少此属性，则相当于将其设置为空列表，这同样会设置为仅包含 `private` 的列表。注意：在 Bazel 6.0 之前，规范 `//...` 的旧版行为与 `public` 相同。启用 `--incompatible_fix_package_group_reporoot_syntax`（这是 Bazel 6.0 之后的默认版本）时，此行为将得到修复。注意：在 Bazel 6.0 之前，当此属性作为 `bazel query --output=proto`（或 `--output=xml`）的一部分进行序列化时，系统会省略前导斜杠。例如，`//pkg/foo/...` 将输出为 `\"pkg/foo/...\"`。启用 `--incompatible_package_group_includes_double_slash`（这是 Bazel 6.0 之后的默认版本）时，此行为将会修复。
`includes`	`List of labels; optional` 此软件包中包含的其他软件包组。此属性中的标签必须引用其他软件包组。所引用的软件包组中的软件包被视为此软件包组的一部分。这是传递性 - 如果软件包组 `a` 包含软件包组 `b`，且 `b` 包含软件包组 `c`，那么 `c` 中的每个软件包也都将是 `a` 的成员。当与否定软件包规范结合使用时，请注意，每个组的这组软件包会先独立计算，然后结果结合在一起。这意味着，一个组中的否定规范对另一个组中的规范没有影响。

name

Name; required

此目标的唯一名称。

packages

List of strings; optional

零个或多个软件包规范的列表。

每个软件包规范字符串都可以采用下列格式之一：

软件包的全称，不带代码库，以双斜杠开头。例如，//foo/bar 会指定具有该名称且与软件包组位于同一代码库中的软件包。
如上所示，但末尾使用了 /...。例如，//foo/... 会指定 //foo 集及其所有子软件包。//... 指定当前代码库中的所有软件包。
字符串 public 或 private，它们分别指定每个软件包或未指定软件包。（此表单需要设置 --incompatible_package_group_has_public_syntax 标志。）

此外，前两种软件包规范也可以使用“-”的前缀来表示它们是否定的。

软件包组包含至少符合其一个肯定规范且没有排除的规范的任何软件包。例如，值 [//foo/..., -//foo/tests/...] 包含 //foo 的所有子软件包，这些子软件包也不是 //foo/tests 的子软件包。（不包含 //foo 本身，而 //foo/tests 本身不包含在内）。

除了公开可见性之外，无法直接指定当前代码库之外的软件包。

如果缺少此属性，则相当于将其设置为空列表，这同样会设置为仅包含 private 的列表。

注意：在 Bazel 6.0 之前，规范 //... 的旧版行为与 public 相同。启用 --incompatible_fix_package_group_reporoot_syntax（这是 Bazel 6.0 之后的默认版本）时，此行为将得到修复。

注意：在 Bazel 6.0 之前，当此属性作为 bazel query --output=proto（或 --output=xml）的一部分进行序列化时，系统会省略前导斜杠。例如，//pkg/foo/... 将输出为 \"pkg/foo/...\"。启用 --incompatible_package_group_includes_double_slash（这是 Bazel 6.0 之后的默认版本）时，此行为将会修复。

includes

List of labels; optional

此软件包中包含的其他软件包组。

此属性中的标签必须引用其他软件包组。所引用的软件包组中的软件包被视为此软件包组的一部分。这是传递性 - 如果软件包组 a 包含软件包组 b，且 b 包含软件包组 c，那么 c 中的每个软件包也都将是 a 的成员。

当与否定软件包规范结合使用时，请注意，每个组的这组软件包会先独立计算，然后结果结合在一起。这意味着，一个组中的否定规范对另一个组中的规范没有影响。

示例

以下 package_group 声明指定了一个名为“热带”的软件包组，其中包含热带水果。

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

以下声明指定了虚构应用的软件包组：

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

导出文件

exports_files([label, ...], visibility, licenses)

exports_files() 指定属于此软件包的文件列表，这些文件会导出到其他软件包。

软件包的 BUILD 文件只能直接引用属于其他软件包的源文件，前提是这些文件是使用 exports_files() 语句明确导出的。详细了解文件的公开范围。

作为一项旧版行为，对于以规则输入形式提及的文件，系统也会导出这些内容的默认可见性，直到 --incompatible_no_implicit_file_export 标志被翻转为止。但是，这种行为不应依赖于并主动从这些进程中迁出。

参数

该参数是当前软件包中文件名的列表。还可以指定可见性声明；在这种情况下，这些文件将对指定的目标可见。如果未指定可见性，则每个软件包都会看到文件，即使 package 函数中指定了软件包默认可见性也是如此。您还可以指定许可。

示例

以下示例会导出 test_data 软件包中的文本文件 golden.txt，以便其他软件包可以使用它，例如在测试的 data 属性中。

# from //test_data/BUILD

exports_files(["golden.txt"])

glob

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

Glob 是一个辅助函数，用于查找符合特定路径模式的所有文件，并返回其路径上新的可变排序列表。Glob 只搜索其自己的软件包中的文件，并且只查找源文件（而不是生成的文件或其他目标）。

如果文件的软件包相对路径与任何 include 格式匹配，并且与 exclude 格式都不匹配，则结果中将包含源文件的标签。

include 和 exclude 列表包含相对于当前软件包的路径模式。每种模式都可能包含一个或多个路径段。与往常一样，对于 Unix 路径，这些细分由 / 分隔。段可能包含 * 通配符：此路径与路径段中的任何子字符串（甚至空的子字符串除外）匹配，但不包括目录分隔符 /。此通配符可在一个路径段中多次使用。此外，** 通配符可以与零个或更多个完整路径段匹配，但必须将其声明为独立的路径段。

示例：

foo/bar.txt 与此软件包中的 foo/bar.txt 文件完全匹配
如果 foo/*.txt 以 .txt 结尾，则匹配 foo/ 目录中的每个文件（除非 foo/ 是子软件包）。
foo/a*.htm* 匹配 foo/ 目录中的每个以 a 开头的文件，然后具有任意字符串（可以为空），其后跟 .htm，以另一个任意字符串结尾；例如 foo/axx.htm 和 foo/a.html 或 foo/axxx.html
**/a.txt 与此软件包的每个子目录中的每个 a.txt 文件匹配
如果生成的路径中至少有一个目录的名称为 bar（例如 xxx/bar/yyy/zzz/a.txt 或 bar/a.txt），请注意 **/bar/**/*.txt 与此软件包的每个子目录中的每个 .txt 文件匹配（请注意，** 也匹配零段）或 bar/zzz/a.txt。
** 与此软件包的每个子目录中的每个文件匹配
foo**/a.txt 是一种无效模式，因为 ** 必须独立地成为一个段

如果启用 exclude_directories 参数（设为 1），搜索结果中将省略类型目录的文件（默认为 1）。

如果 allow_empty 参数设置为 False，则 glob 函数将在结果为空列表时发生错误。

有一些重要的限制和注意事项：

由于 glob() 在 BUILD 文件评估期间运行，因此 glob() 只会匹配源代码树中的文件，而不会匹配生成的文件。如果您构建的目标需要来源和生成的文件，您必须将生成的文件的明确列表附加到 glob。请参阅下面的示例，了解 :mylib 和 :gen_java_srcs。
如果规则与匹配的源文件具有相同的名称，则该规则将“覆盖”该文件。

为了理解这一点，请记住 glob() 会返回路径列表，因此在其他规则的属性（例如 srcs = glob(["*.cc"])）中使用 glob() 与明确列出匹配路径的效果相同。例如，如果 glob() 会生成 ["Foo.java", "bar/Baz.java"]，但软件包中还有一个名为“Foo.java”（在它允许 Bazel 发出警告时允许）的规则，则 glob() 的使用方将使用“Foo.java”规则（其输出）而非“Foo.java”文件。如需了解详情，请参阅 GitHub 问题 10395。
Glob 可能会匹配子目录中的文件。子目录名称可以采用通配符。不过...
不允许标签跨越软件包边界，并且 glob 与子软件包中的文件不匹配。

例如，如果 x/y 以软件包的形式存在（既在 x/y/BUILD 中，又在软件包路径上的其他位置），则 x 软件包中的 glob 表达式不包含 x/y/z.cc。这意味着 glob 表达式的结果实际上依赖于 BUILD 文件是否存在；也就是说，如果没有名为 x/y 的软件包或者使用 --deleted_packages 标记将其标记为已删除，同一个 glob 表达式将包含 x/y/z.cc。
上述限制适用于所有 glob 表达式，无论它们使用的通配符是什么。
文件名以 . 开头的隐藏文件将由 ** 和 * 通配符完全匹配。如果要将隐藏文件与复合模式匹配，则需要以 . 开头。例如，* 和 .*.txt 将匹配 .foo.txt，但 *.txt 不会匹配。隐藏目录的匹配方式也相同。隐藏的目录可能包含不需要作为输入的文件，这可能会增加不必要的不必要的文件和内存消耗。如需排除隐藏的目录，请将相应目录添加到“排除”列表参数中。
“**”通配符具有一种极端情况：模式 "**" 与软件包的目录路径不匹配。也就是说，glob(["**"], exclude_directories = 0) 会准确匹配当前软件包目录下的所有文件和目录（但肯定不会进入子软件包的目录，请参阅前文中关于这一点的备注）。

一般而言，您应该尝试提供适当的扩展（例如 *.html），而不是对 glob 模式使用裸“*”。更明确的名称是自行记录，可确保您不会意外匹配备份文件或 emacs/vi/... 自动保存文件。

编写构建规则时，您可以枚举 glob 的元素。举例来说，这样便可为每个输入生成单独的规则。请参阅下面的展开的 glob 示例部分。

Glob 示例

创建一个从此目录中的所有 Java 文件以及 :gen_java_srcs 规则生成的所有文件构建的 Java 库。

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

将除 testal.txt 以外的所有 txt 文件包含在目录 testdata 中。请注意，testdata 的子目录中不会包含文件。如果要包含这些文件，请使用递归 glob (**)。

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

递归 Glob 示例

让测试依赖于 testdata 目录及其所有子目录（及其子目录等）中的所有 txt 文件。包含 BUILD 文件的子目录会被忽略。（请参阅上述限制和注意事项。）

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

创建一个目录，从此目录（及其路径中包含的所有 Java 文件）及其所有目录创建。如果可能，应避免使用此模式，因为它可以降低 build 增量，进而增加构建时间。

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

展开的 Glob 示例

在当前目录中为 *_test.cc 创建单个 genrule，以统计文件中的行数。

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

如果上述 BUILD 文件在软件包 //foo 中，并且软件包包含三个匹配的文件（a_test.cc、b_test.cc 和 c_test.cc），则运行 bazel query '//foo:all' 将列出生成的所有规则：

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

select

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() 是使规则属性可配置的辅助函数。它可以替换几乎所有属性分配的右侧，因此其值取决于命令行 Bazel 标志。例如，您可以使用此 SDK 定义平台专用依赖项，或根据规则是在“开发者”模式下还是“发布”模式下构建来嵌入不同的资源。

基本用法如下：

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

这会使 sh_binary 的 srcs 属性可配置，方法是将其常规标签列表分配替换为 select 调用，该调用会将配置条件映射到匹配值。每个条件都是对 config_setting 或 constraint_value 的标签引用，如果目标的配置与一组预期值匹配，则“匹配”。然后，mytarget#srcs 的值将成为与当前调用匹配的标签列表。

备注：

每次调用时，只能选择一个条件。
如果有多个条件匹配，并且其中一个条件是其他条件的专业化，则以该专业化优先。如果条件 B 具有与 A 相同的所有标志和限制值，再加上一些额外的标志或约束条件值，则条件 B 会被视为条件 A 的专用项。这也意味着专项解决方案不能按照下面示例 2 中所示的方式创建排序。
如果有多个条件匹配，并且其中一个条件不是所有其他项的专用项，则 Bazel 会失败并返回错误，除非所有条件都能解析为相同的值。
如果没有其他条件匹配，则特殊伪标签 //conditions:default 会被视为匹配。如果省略此条件，必须匹配其他一些规则以避免错误。
select 可以嵌入到更大的特性分配中。因此，srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) 和 srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) 是有效的表达式。
select 适用于大多数（但并非全部）属性。不兼容的属性会在其文档中标记为 nonconfigurable。
子软件包
```
subpackages(include, exclude=[], allow_empty=True)
```
subpackages() 是一个辅助函数，类似于 glob()，其中会列出子软件包，而不是文件和目录。它使用与 glob() 相同的路径模式，并且可以匹配属于当前加载的 BUILD 文件的直接后代的任何子软件包。如需详细了解包含模式和排除模式，请参阅 glob。

返回的子软件包列表按排序顺序排列，其中包含相对于当前加载软件包的路径，该路径与 include 中的指定格式（而不是 exclude 中的格式）匹配。
示例

以下示例列出了软件包 foo/BUILD 的所有直接子软件包
```
# The following BUILD files exist:
# foo/BUILD
# foo/bar/baz/BUILD
# foo/sub/BUILD
# foo/sub/deeper/BUILD
#
# In foo/BUILD a call to
subs = subpackages(include = ["**"])

# results in subs == ["sub", "bar/baz"]
#
# 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
# 'foo'
```
一般来说，最好是让用户不要直接调用此函数，而是使用 skylib 的“subpackages”模块。