目录
package
package(default_deprecation, default_testonly, default_visibility, features)
此函数声明适用于软件包中每条后续规则的元数据。它在软件包(BUILD 文件)中最多使用一次。
应在文件顶部所有的 load() 语句之后、任何规则之前调用 package() 函数。
参数
属性 | 说明 |
---|---|
default_visibility |
此软件包中规则的默认可见性。 除非在规则的 |
default_deprecation |
为此软件包中的所有规则设置默认的
|
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
函数中指定了软件包默认可见性,这些文件对每个软件包也可见。您还可以指定许可。
示例
以下示例会导出 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
函数将出错。
以下是一些重要的限制和注意事项:
-
由于
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 表达式标记为已删除,则相同的 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 中除 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”模块,而不是直接调用此函数。