规则
- cc_binary
- cc_import
- cc_library
- cc_proto_library
- fdo_prefetch_hints
- fdo_profile
- propeller_optimize
- cc_test
- cc_toolchain
- cc_toolchain_suite
cc_binary
cc_binary(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, copts, defines, deprecation, distribs, env, exec_compatible_with, exec_properties, features, includes, licenses, linkopts, linkshared, linkstatic, local_defines, malloc, nocopts, output_licenses, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file)
隐式输出目标
name.stripped
(仅在明确请求时构建):二进制文件的剥离版本。对二进制文件运行strip -g
以移除调试符号。可以在命令行中使用--stripopt=-foo
提供其他剥离选项。只有在明确请求时才会构建此输出。name.dwp
(仅在明确请求时构建):如果启用了 Fission:一个适合调试远程部署的二进制文件的调试信息包文件。否则:空文件。
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
deps
|
这些可以是 |
srcs
|
系统将编译所有
所有 如果规则的名称位于
允许的
...以及生成这些文件的任何规则。 按照 gcc 惯例,不同的扩展名表示不同的编程语言。 |
additional_linker_inputs
|
例如,可在此处提供已编译的 Windows .res 文件,以将其嵌入二进制目标中。 |
copts
|
在编译二进制目标之前,此属性中的每个字符串都会按给定顺序添加到
如果软件包声明功能
|
defines
|
-D ,并添加到此目标以及依赖于它的每条规则的编译命令行中。请务必小心,因为这可能会造成深远的影响。如有疑问,请改为将定义值添加到 local_defines 。
|
includes
|
可使用“生成变量”替换值。
每个字符串都会以 必须将头文件添加到 src 或 hdrs,否则当编译被沙盒化(默认设置)时,这些头文件将不适用于相关规则。 |
linkopts
|
LINKOPTS 。
此列表中不以 |
linkshared
|
linkshared=True 。默认情况下,此选项处于关闭状态。
此标志的存在意味着通过
如果您同时指定 |
linkstatic
|
cc_binary 和 cc_test :在静态模式下链接二进制文件。对于 cc_library.linkstatic :请参阅下文。
默认情况下,系统会针对
启用后,如果这是一个二进制文件或测试,此选项会指示构建工具尽可能关联 链接可执行文件的方法实际上有三种:
在
如果为 |
local_defines
|
-D 并添加到此目标的编译命令行中,但不会添加到其依赖性。
|
malloc
|
默认情况下,C++ 二进制文件链接到 |
nocopts
|
COPTS (包括规则的 copts 属性中明确指定的值)都将从 COPTS 中移除。此属性应很少需要用到,
|
stamp
|
带时间戳的二进制文件不会重新构建,除非其依赖项发生更改。 |
win_def_file
|
仅当 Windows 是目标平台时,才应使用此属性。 它可用于在关联共享库期间 导出符号。 |
cc_import
cc_import(name, data, hdrs, alwayslink, compatible_with, deprecation, distribs, features, interface_library, licenses, restricted_to, shared_library, static_library, system_provided, tags, target_compatible_with, testonly, visibility)
cc_import
规则允许用户导入预编译的 C/C++ 库。
以下是典型用例:
1. 关联静态库
cc_import( name = "mylib", hdrs = ["mylib.h"], static_library = "libmylib.a", # If alwayslink is turned on, # libmylib.a will be forcely linked into any binary that depends on it. # alwayslink = 1, )2. 关联共享库 (Unix)
cc_import( name = "mylib", hdrs = ["mylib.h"], shared_library = "libmylib.so", )3. 将共享库与接口库 (Windows) 关联
cc_import( name = "mylib", hdrs = ["mylib.h"], # mylib.lib is a import library for mylib.dll which will be passed to linker interface_library = "mylib.lib", # mylib.dll will be available for runtime shared_library = "mylib.dll", )4. 将共享库与
system_provided=True
关联 (Windows)
cc_import( name = "mylib", hdrs = ["mylib.h"], # mylib.lib is an import library for mylib.dll which will be passed to linker interface_library = "mylib.lib", # mylib.dll is provided by system environment, for example it can be found in PATH. # This indicates that Bazel is not responsible for making mylib.dll available. system_provided = 1, )5. 链接到静态或共享库
在 Unix 上:
cc_import( name = "mylib", hdrs = ["mylib.h"], static_library = "libmylib.a", shared_library = "libmylib.so", ) # first will link to libmylib.a cc_binary( name = "first", srcs = ["first.cc"], deps = [":mylib"], linkstatic = 1, # default value ) # second will link to libmylib.so cc_binary( name = "second", srcs = ["second.cc"], deps = [":mylib"], linkstatic = 0, )在 Windows 上:
cc_import( name = "mylib", hdrs = ["mylib.h"], static_library = "libmylib.lib", # A normal static library interface_library = "mylib.lib", # An import library for mylib.dll shared_library = "mylib.dll", ) # first will link to libmylib.lib cc_binary( name = "first", srcs = ["first.cc"], deps = [":mylib"], linkstatic = 1, # default value ) # second will link to mylib.dll through mylib.lib cc_binary( name = "second", srcs = ["second.cc"], deps = [":mylib"], linkstatic = 0, )
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
hdrs
|
|
alwayslink
|
由于已知问题,如果始终链接在 Windows 上对 VS 2017 不起作用,请将 VS 2017 升级到最新版本。 |
interface_library
|
允许的文件类型: |
shared_library
|
允许的文件类型: |
static_library
|
允许的文件类型: |
system_provided
|
interface_library 且 shared_library 应为空。
|
cc_library
cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, compatible_with, copts, defines, deprecation, distribs, exec_compatible_with, exec_properties, features, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, nocopts, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file)
标头包含项检查
build 中使用的所有头文件必须在 cc_*
规则的 hdrs
或 srcs
中声明。这是强制执行的。
对于 cc_library
规则,hdrs
中的头文件构成库的公共接口,可以直接从库本身的 hdrs
和 srcs
内的文件,以及从库其 deps
中列出库的 cc_*
规则的 hdrs
和 srcs
内的文件中添加。srcs
中的头文件只能直接从库本身的 hdrs
和 srcs
内的文件中添加。在决定是否将标头放入 hdrs
或 srcs
时,您应询问您是否希望此库的使用方能够直接添加该标头。这与编程语言中 public
和 private
可见性的决定大致相同。
cc_binary
和 cc_test
规则没有导出的接口,因此它们也没有 hdrs
属性。属于二进制文件或测试的所有头文件都应在 srcs
中列出。
为了说明这些规则,请查看以下示例。
cc_binary( name = "foo", srcs = [ "foo.cc", "foo.h", ], deps = [":bar"], ) cc_library( name = "bar", srcs = [ "bar.cc", "bar-impl.h", ], hdrs = ["bar.h"], deps = [":baz"], ) cc_library( name = "baz", srcs = [ "baz.cc", "baz-impl.h", ], hdrs = ["baz.h"], )
下表列出了本示例中允许直接包含的内容。例如,foo.cc
可以直接包含 foo.h
和 bar.h
,但不能直接包含 baz.h
。
包含的文件 | 允许包含的内容 |
---|---|
foo.h | bar.h |
foo.cc | foo.h bar.h |
bar.h | bar-impl.h baz.h |
bar-impl.h | bar.h baz.h |
bar.cc | bar.h bar-impl.h baz.h |
baz.h | baz-impl.h |
baz-impl.h | baz.h |
baz.cc | baz.h baz-impl.h |
包含项检查规则仅适用于直接包含项。在上面的示例中,foo.cc
允许包含 bar.h
,其中可能会包含 baz.h
,反过来又允许包含 baz-impl.h
。从技术上讲,.cc
文件的编译可以在传递 deps
闭包的任意 cc_library
的 hdrs
或 srcs
中传递任何头文件。在这种情况下,编译器可能会在编译 foo.cc
时读取 baz.h
和 baz-impl.h
,但 foo.cc
不得包含 #include "baz.h"
。若要允许这种行为,必须将 baz
添加到 foo
的 deps
中。
遗憾的是,Bazel 目前无法区分直接包含项和传递包含项,因此它无法检测到文件非法直接包含仅允许以传递方式包含的标头的错误情况。例如,在上面的示例中,如果 foo.cc
直接包含 baz.h
,则 Bazel 不会发出错误消息。这样做是非法的,因为 foo
不直接依赖于 baz
。目前,在这种情况下不会产生错误,但未来可能会添加此类错误检查。
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
deps
|
这些可以是 |
srcs
|
系统将编译所有
所有 如果规则的名称位于
允许的
...以及生成这些文件的任何规则。 按照 gcc 惯例,不同的扩展名表示不同的编程语言。 |
hdrs
|
这是声明描述库接口的头文件的首选位置。这些标头将可供来源添加到此规则或相关规则中。不应由此库的客户端包含的标头应改为列在 |
additional_compiler_inputs
|
|
additional_linker_inputs
|
例如,可在此处提供已编译的 Windows .res 文件,以将其嵌入二进制目标中。 |
alwayslink
|
srcs 中列出的文件的所有对象文件,即使某些文件不包含任何二进制文件引用的符号也是如此。
如果二进制文件中的代码未明确调用您的代码(例如,您的代码注册以接收某个服务提供的某个回调),那么这会非常有用。
由于已知问题,如果始终链接在 Windows 上对 VS 2017 不起作用,请将 VS 2017 升级到最新版本。 |
copts
|
在编译二进制目标之前,此属性中的每个字符串都会按给定顺序添加到
如果软件包声明功能
|
defines
|
-D ,并添加到此目标以及依赖于它的每条规则的编译命令行中。请务必小心,因为这可能会造成深远的影响。如有疑问,请改为将定义值添加到 local_defines 。
|
implementation_deps
|
deps 不同,这些库(及其所有传递依赖项)的头文件和 include 路径仅用于编译此库,而不用于编译依赖于此库的库。使用 implementation_deps 指定的库仍链接到依赖于此库的二进制目标中。目前,只能在 cc_ libraries 中使用,并受 |
include_prefix
|
设置后,此规则的 在添加此前缀之前,系统会移除 |
includes
|
可使用“生成变量”替换值。
每个字符串都会以 必须将头文件添加到 src 或 hdrs,否则当编译被沙盒化(默认设置)时,这些头文件将不适用于相关规则。 |
linkopts
|
LINKOPTS 。
此列表中不以 |
linkstamp
|
base 软件包中才需要此选项。
|
linkstatic
|
cc_binary 和 cc_test :在静态模式下链接二进制文件。对于 cc_library.linkstatic :请参阅下文。
默认情况下,系统会针对
启用后,如果这是一个二进制文件或测试,此选项会指示构建工具尽可能关联 链接可执行文件的方法实际上有三种:
在
如果为 |
local_defines
|
-D 并添加到此目标的编译命令行中,但不会添加到其依赖性。
|
nocopts
|
COPTS (包括规则的 copts 属性中明确指定的值)都将从 COPTS 中移除。此属性应很少需要用到,
|
strip_include_prefix
|
设置后,此规则的 如果它是相对路径,则视为相对于软件包的路径。如果为绝对路径,则将其视为代码库相对路径。
|
textual_hdrs
|
此位置用于声明无法自行编译的头文件;也就是说,要编译有效代码,其他源文件始终需要以文本形式包含这些文件。 |
win_def_file
|
仅当 Windows 是目标平台时,才应使用此属性。 它可用于在关联共享库期间 导出符号。 |
cc_proto_library
cc_proto_library(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)
cc_proto_library
会从 .proto
文件生成 C++ 代码。
deps
必须指向 proto_library
规则。
例如:
cc_library( name = "lib", deps = [":foo_cc_proto"], ) cc_proto_library( name = "foo_cc_proto", deps = [":foo_proto"], ) proto_library( name = "foo_proto", )
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
deps
|
proto_library 规则列表。
|
fdo_prefetch_hints
fdo_prefetch_hints(name, compatible_with, deprecation, distribs, features, licenses, profile, restricted_to, tags, target_compatible_with, testonly, visibility)
表示位于工作区或指定的绝对路径上的 FDO 预提取提示配置文件。 示例:
fdo_prefetch_hints( name = "hints", profile = "//path/to/hints:profile.afdo", ) fdo_profile( name = "hints_abs", absolute_path_profile = "/absolute/path/profile.afdo", )
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
profile
|
|
fdo_profile
fdo_profile(name, absolute_path_profile, compatible_with, deprecation, distribs, features, licenses, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, visibility)
表示位于工作区或指定绝对路径上的 FDO 配置文件。 示例:
fdo_profile( name = "fdo", profile = "//path/to/fdo:profile.zip", ) fdo_profile( name = "fdo_abs", absolute_path_profile = "/absolute/path/profile.zip", )
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
absolute_path_profile
|
|
profile
|
|
proto_profile
|
|
propeller_optimize
propeller_optimize(name, compatible_with, deprecation, distribs, features, ld_profile, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)
表示工作区中的 Propeller 优化配置文件。 例如:
propeller_optimize( name = "layout", cc_profile = "//path:cc_profile.txt", ld_profile = "//path:ld_profile.txt" ) propeller_optimize( name = "layout_absolute", absolute_cc_profile = "/absolute/cc_profile.txt", absolute_ld_profile = "/absolute/ld_profile.txt" )
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
ld_profile
|
|
cc_test
cc_test(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, copts, defines, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, includes, licenses, linkopts, linkstatic, local, local_defines, malloc, nocopts, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file)
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
deps
|
这些可以是 |
srcs
|
系统将编译所有
所有 如果规则的名称位于
允许的
...以及生成这些文件的任何规则。 按照 gcc 惯例,不同的扩展名表示不同的编程语言。 |
additional_linker_inputs
|
例如,可在此处提供已编译的 Windows .res 文件,以将其嵌入二进制目标中。 |
copts
|
在编译二进制目标之前,此属性中的每个字符串都会按给定顺序添加到
如果软件包声明功能
|
defines
|
-D ,并添加到此目标以及依赖于它的每条规则的编译命令行中。请务必小心,因为这可能会造成深远的影响。如有疑问,请改为将定义值添加到 local_defines 。
|
includes
|
可使用“生成变量”替换值。
每个字符串都会以 必须将头文件添加到 src 或 hdrs,否则当编译被沙盒化(默认设置)时,这些头文件将不适用于相关规则。 |
linkopts
|
LINKOPTS 。
此列表中不以 |
linkstatic
|
cc_binary 和 cc_test :在静态模式下链接二进制文件。对于 cc_library.linkstatic :请参阅下文。
默认情况下,系统会针对
启用后,如果这是一个二进制文件或测试,此选项会指示构建工具尽可能关联 链接可执行文件的方法实际上有三种:
在
如果为 |
local_defines
|
-D 并添加到此目标的编译命令行中,但不会添加到其依赖性。
|
malloc
|
默认情况下,C++ 二进制文件链接到 |
nocopts
|
COPTS (包括规则的 copts 属性中明确指定的值)都将从 COPTS 中移除。此属性应很少需要用到,
|
stamp
|
带时间戳的二进制文件不会重新构建,除非其依赖项发生更改。 |
win_def_file
|
仅当 Windows 是目标平台时,才应使用此属性。 它可用于在关联共享库期间 导出符号。 |
cc_toolchain
cc_toolchain(name, all_files, ar_files, as_files, compatible_with, compiler, compiler_files, compiler_files_without_includes, coverage_files, cpu, deprecation, distribs, dwp_files, dynamic_runtime_lib, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, visibility)
表示 C++ 工具链。
此规则负责:
-
收集运行 C++ 操作所需的所有工件。这是通过
all_files
、compiler_files
、linker_files
等属性或以_files
结尾的其他属性实现的。这些文件组是对所有必需文件进行全局访问的最常用文件组。 -
为 C++ 操作生成正确的命令行。此操作是使用
CcToolchainConfigInfo
提供程序完成的(详见下文)。
使用 toolchain_config
属性配置 C++ 工具链。另请参阅此
页面
,查看详细的 C++ 工具链配置和工具链选择文档。
使用 tags = ["manual"]
可防止在调用 bazel build //...
时不必要地构建和配置工具链
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
all_files
|
all_files 是所有其他提供工件的属性的超集(例如,linkstamp 编译同时需要编译和链接文件,因此它采用 all_files )。
这是 |
ar_files
|
归档操作所需的所有 cc_toolchain 工件的集合。 |
as_files
|
汇编操作所需的所有 cc_toolchain 工件的集合。 |
compiler
|
toolchain_identifier 属性。在
从 CROSSTOOL 迁移到 Starlark
后,它将成为空操作,并将于 #7075 之前移除。设置后,它将用于执行 crosstool_config.toolchain 选择。此选项的优先级高于 --cpu Bazel 选项。 |
compiler_files
|
|
compiler_files_without_includes
|
|
coverage_files
|
|
cpu
|
设置后,它将用于执行 crosstool_config.toolchain 选择。此选项的优先级高于 --cpu Bazel 选项。 |
dwp_files
|
|
dynamic_runtime_lib
|
启用“static_link_cpp_runtimes”功能时将使用此变量,并且我们会动态关联依赖项。 |
exec_transition_for_inputs
|
|
libc_top
|
|
linker_files
|
|
module_map
|
|
objcopy_files
|
|
static_runtime_lib
|
如果启用了“static_link_cpp_runtimes”功能,并且我们将静态链接依赖项,则会用到此变量。 |
strip_files
|
|
supports_header_parsing
|
|
supports_param_files
|
|
toolchain_config
|
cc_toolchain_config_info 的规则的标签。 |
toolchain_identifier
|
在问题 #5380 得到解决之前,建议您采用这种方法将 |
cc_toolchain_suite
cc_toolchain_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)
表示 C++ 工具链的集合。
此规则负责:
- 收集所有相关的 C++ 工具链。
-
根据传递给 Bazel 的
--cpu
和--compiler
选项选择一个工具链。
另请参阅此 页面 ,查看详细的 C++ 工具链配置和工具链选择文档。
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
toolchains
|
cc_toolchain 标签的映射。当仅将 --cpu 传递给 Bazel 时,将使用“<cpu>”,当 --cpu 和 --compiler 均传递到 Bazel 时,将使用“<cpu>|<compiler>”。示例:
cc_toolchain_suite( name = "toolchain", toolchains = { "piii|gcc": ":my_cc_toolchain_for_piii_using_gcc", "piii": ":my_cc_toolchain_for_piii_using_default_compiler", }, ) |