目录
package
package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)
此函数用于声明适用于软件包中每条规则的元数据。它在软件包(BUILD 文件)中最多只能使用一次。
对于声明将应用于整个代码库中每条规则的元数据的副本,请使用代码库根目录下的 REPO.bazel
文件中的 repo()
函数。repo()
函数采用的参数与 package()
完全相同。
应在文件顶部的所有 load() 语句之后、任何规则之前调用 package() 函数。
参数
属性 | 说明 |
---|---|
default_applicable_licenses |
|
default_visibility |
标签列表;默认值为 此软件包中规则的默认可见性。 除非在规则的 |
default_deprecation |
字符串;默认值为 为此软件包中的所有规则设置默认
|
default_package_metadata |
标签列表;默认值为 设置适用于软件包中所有其他目标的元数据目标的默认列表。这些通常是与 OSS 软件包和许可声明相关的目标。有关示例,请参阅 rules_license。 |
default_testonly |
布尔值;除非另有说明,否则默认值为 为此软件包中的所有规则设置默认
在 |
features |
列表字符串;默认值为 设置影响此 BUILD 文件语义的各种标记。 此功能主要供构建系统开发者用来标记需要某种特殊处理的软件包。除非构建系统工作者明确请求,否则请勿使用此属性。 |
示例
以下声明声明,此软件包中的规则仅对软件包组//foo:target
的成员可见。规则的个别可见性声明(如果存在)会替换此规范。
package(default_visibility = ["//foo:target"])
package_group
package_group(name, packages, includes)
此函数定义了一组软件包,并将一个标签与这组软件包相关联。可以在 visibility
属性中引用该标签。
软件包组主要用于控制可见性。可以从源代码树中的每个软件包引用公开可见的目标。私密可见目标只能在自己的软件包(而不是子软件包)内引用。在这两种极端之间,目标可能会允许访问自己的软件包以及一个或多个软件包组所描述的任何软件包。如需详细了解可见性系统,请参阅 visibility 属性。
如果给定软件包与 packages
属性匹配,或已包含在 includes
属性中提及的其他软件包组,则被视为包含在组内。
软件包组在技术上是目标,但不是由规则创建的,本身没有任何可见性保护。
参数
属性 | 说明 |
---|---|
name |
名称(必需) 此目标的唯一名称。 |
packages |
字符串列表;默认值为 零个或多个软件包规范的列表。 每个软件包规范字符串可以采用以下格式之一:
此外,前两种软件包规范还可以带有 软件包组包含与其至少一个正向规范匹配而未符合其任何负面规范的任何软件包。例如,值 除了公开可见之外,无法直接指定当前代码库之外的软件包。 如果缺少此属性,则等同于将其设置为空列表,也与将其设为仅包含 注意:在 Bazel 6.0 之前的版本中,规范 注意:在 Bazel 6.0 之前的版本中,当此属性序列化为 |
includes |
标签列表;默认值为 此软件包中包含的其他软件包组。 此属性中的标签必须引用其他软件包组。
所引用软件包组中的软件包会被视为此软件包组的一部分。这是传递的 - 如果软件包组 请注意,当与否定软件包规范结合使用时,系统会先独立计算每组的软件包集,然后再将结果联合在一起。也就是说,一个组中排除的规范对另一组中的规范没有影响。 |
示例
以下 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
函数中指定了软件包默认可见性也是如此。您还可以指定许可。
示例
以下示例会导出 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/
是子软件包)- 如果
foo/
目录中以.txt
结尾的文件,则foo/*.txt
会匹配该文件(除非foo/
是子软件包) foo/a*.htm*
会匹配foo/
目录中以a
开头,然后具有任意字符串(可以为空)、.htm
并以另一个任意字符串结尾(除非foo/
是子软件包)的每个文件;例如foo/axx.htm
和foo/a.html
或foo/axxx.html
foo/*
会匹配foo/
目录中的每个文件(除非foo/
是子软件包);即使exclude_directories
设置为 0,它也不会匹配foo
目录本身foo/**
会匹配软件包的第一级子目录foo/
下每个非子软件包子目录中的每个文件;如果exclude_directories
设置为 0,则foo
目录本身也会匹配该模式;在这种情况下,**
被视为匹配零路径段**/a.txt
会匹配此软件包的目录以及非子软件包子目录中的a.txt
文件。- 如果生成的路径上至少有一个目录名为
bar
,例如xxx/bar/yyy/zzz/a.txt
或bar/a.txt
(请注意,**
也与零个段匹配)或bar/zzz/a.txt
,则**/bar/**/*.txt
会匹配此软件包的每个非子软件包子目录中的每个.txt
文件。 **
会匹配此软件包的每个非子软件包子目录中的每个文件foo**/a.txt
是无效格式,因为**
必须作为一个细分独立存在foo/
是无效模式,因为在/
之后定义的第二个段是空字符串
如果 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 表达式**/*.cc
不会包含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", ], ... )
在目录 testdata 中添加除了 experiment.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/bar/but/bad/BUILD # foo/sub/BUILD # foo/sub/deeper/BUILD # # In foo/BUILD a call to subs1 = subpackages(include = ["**"]) # results in subs1 == ["sub", "bar/baz", "bar/but/bad"] # # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of # 'foo' subs2 = subpackages(include = ["bar/*"]) # results in subs2 = ["bar/baz"] # # Since 'bar' is not a subpackage itself, this looks for any subpackages under # all first level subdirectories of 'bar'. subs3 = subpackages(include = ["bar/**"]) # results in subs3 = ["bar/baz", "bar/but/bad"] # # Since bar is not a subpackage itself, this looks for any subpackages which are # (1) under all subdirectories of 'bar' which can be at any level, (2) not a # subpackage of another subpackages. subs4 = subpackages(include = ["sub"]) subs5 = subpackages(include = ["sub/*"]) subs6 = subpackages(include = ["sub/**"]) # results in subs4 and subs6 being ["sub"] # results in subs5 = []. # # In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a # subpackage of 'foo'). # In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since # 'foo/sub' is already a subpackage itself, the subdirectories will not be # traversed anymore. # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it # is returned. But the subdirectories of 'foo/sub' will not be traversed # anymore.
一般而言,用户最好使用 skylib 的“子软件包”模块,而不是直接调用此函数。