函数

目录

• 软件包
• package_group
• exports_files
• glob
• 选择
• 子软件包

package

package(default_deprecation, default_testonly, default_visibility, features)

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

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

参数

属性	说明
default_visibility	List of labels; optional 此软件包中规则的默认可见性。 除非在规则的 visibility 属性中另行指定，否则此软件包中的每个规则都具有在此属性中指定的可见性。如需详细了解此属性的语法，请参阅可见性文档。 软件包默认可见性不适用于 exports_files，后者默认为公开状态。
default_deprecation	String; optional 为此软件包中的所有规则设置默认的 deprecation 消息。
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 属性中引用该标签。

软件包组主要用于控制可见性。源代码树中的每个软件包都可以引用公开可见的目标。非公开可见目标只能在其自己的软件包（而非子软件包）中引用。在这两种极端情况下，目标可能允许访问自己的软件包，以及一个或多个软件包组描述的任何软件包。如需详细了解可见性系统，请参阅 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 的成员。 请注意，当与否定软件包规范结合使用时，每个组的软件包集是首先单独计算的，然后将结果联合在一起。也就是说，一个组中否定的规范不会影响另一个组中的规范。

示例

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

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

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

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

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

作为旧版行为，在规则的输入中提及的文件也会以默认可见性导出，直到标记 --incompatible_no_implicit_file_export 被翻转。不过，您不应依赖此行为，也不应主动迁移此行为。

参数

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

示例

以下示例会导出 golden.txt（来自 test_data 软件包的文本文件），以便其他软件包可以在测试的 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 结尾的文件，则 foo/*.txt 会匹配该目录中的每一个文件（除非 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/zzz/a.txt，则 **/bar/**/*.txt 会匹配此软件包的每个子目录中的每个 .txt 文件
• ** 会匹配此软件包的每个子目录中的每个文件
• foo**/a.txt 是无效模式，因为 ** 必须单独作为片段

如果启用了 exclude_directories 参数（设置为 1），结果中将会忽略类型为“目录”的文件（默认值为 1）。

如果 allow_empty 参数设置为 False，且结果为空列表，则 glob 函数将出错。

以下是一些重要的限制和注意事项：

1. 由于 glob() 在 BUILD 文件评估期间运行，因此 glob() 仅匹配源代码树中的文件，而不会匹配生成的文件。如果要构建同时需要源文件和已生成文件的目标，则必须将生成的文件显式列表附加到 glob。请参阅下面的 :mylib 和 :gen_java_srcs 示例。

2. 如果规则与匹配的源文件同名，则规则将覆盖该文件。

   为理解这一点，请记住 glob() 会返回路径列表，因此在其他规则的属性（例如 srcs = glob(["*.cc"])）中使用 glob() 与明确列出匹配的路径的效果相同。例如，如果 glob() 生成 ["Foo.java", "bar/Baz.java"]，但软件包中还有一个名为“Foo.java”的规则（尽管 Bazel 会发出警告），但 glob() 的使用方将使用“Foo.java”规则（其输出），而不是“Foo.java”文件。如需了解详情，请参阅 GitHub 问题 #10395。

3. glob 可能会匹配子目录中的文件。子目录名称可以使用通配符。但是...

4. 标签不能跨越软件包边界，并且 glob 与子软件包中的文件不匹配。

   例如，如果 x/y 作为软件包存在（作为 x/y/BUILD 或软件包路径上的其他位置），则软件包 x 中的 glob 表达式 **/*.cc 不会包含 x/y/z.cc。这意味着 glob 表达式的结果实际上取决于 BUILD 文件的存在，也就是说，如果没有名为 x/y 的软件包，或使用 --deleted_packages 标志将该 glob 表达式标记为已删除，则相同的 glob 表达式将包含 x/y/z.cc。

5. 上述限制适用于所有 glob 表达式，无论它们使用哪些通配符。
6. 文件名以 . 开头的隐藏文件与 ** 和 * 通配符完全匹配。如果要将隐藏文件与复合模式匹配，您的模式必须以 . 开头。例如，* 和 .*.txt 将与 .foo.txt 匹配，但 *.txt 不匹配。 隐藏目录也会以相同的方式进行匹配。隐藏目录可能包含不需要作为输入的文件，并且可能会增加不必要的全局化文件的数量和内存消耗。如需排除隐藏目录，请将其添加到“排除”列表参数中。
7. 通配符“**”有一个极端情况：格式 "**" 与软件包的目录路径不匹配。也就是说，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",
    ],
    ...
)

添加目录 testdata 中除 experimental.txt 以外的所有 txt 文件。 请注意，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"]),
)

创建一个根据此目录及所有子目录（路径包含名为“testing”的目录除外）中的所有 java 文件构建的库。应尽可能避免使用这种模式，因为它会减少构建增量，从而增加构建时间。

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 标志。 例如，您可以使用此方法定义特定于平台的依赖项或根据规则是在“开发者”模式还是“发布”模式下构建来嵌入不同的资源。

基本用途如下：

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”模块，而不是直接调用此函数。