2022 年 BazelCon 将于 11 月 16 日至 17 日在纽约和线上举办。
立即报名!

C / C++ 规则

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

规则

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

Name; required

此目标的唯一名称。

deps

List of labels; optional

要链接到二进制目标的其他库的列表。

可以是 cc_libraryobjc_library 目标。

srcs

List of labels; optional

为创建目标而处理的 C 和 C++ 文件的列表。这些是 C/C++ 源文件和头文件,可以是非生成的(常规源代码)文件,也可以是生成的文件。

所有 .cc.c.cpp 文件都将被编译。这些可能是生成的文件:如果某个已命名文件位于某个其他规则的 outs 中,此规则将自动依赖于该另一个规则。

系统不会编译 .h 文件,但会将此规则纳入到来源中。.cc.h 文件都可以直接包含这些 srcsdeps 参数中列出的任何规则的 hdrs 中列出的标头。

所有 #included 文件都必须在此规则的 srcs 属性或引用 cc_library()hdrs 属性中。推荐的样式是与某个库关联的头文件列在库的 hdrs 属性中,而与此规则关联的任何剩余头文件要在 srcs 中列出。如需更详细的说明,请参阅“标头包含值检查”

如果规则的名称位于 srcs 中,则此规则会自动依赖于此规则。如果指定的规则的 outs 是 C 或 C++ 源文件,系统会将其编译到此规则中;如果它们是库文件,则会链接到这些文件。

允许的 srcs 文件类型:

  • C 和 C++ 源文件:.c.cc.cpp.cxx.c++.C
  • C 和 C++ 头文件:.h.hh.hpp.hxx.inc.inl.H
  • 具有 C 预处理器的汇编程序:.S
  • 归档:.a.pic.a
  • “始终链接”库:.lo.pic.lo
  • 有版本控制或未版本控制的共享库:.so.so.version
  • 对象文件:.o.pic.o

...以及生成这些文件的所有规则。 根据 gcc 惯例,不同的扩展名表示不同的编程语言。

additional_linker_inputs

List of labels; optional

将这些文件传递给 C++ 链接器命令。

例如,在此处提供的经过编译的 Windows .res 文件可嵌入到二进制目标中。

copts

List of strings; optional

将这些选项添加到 C++ 编译命令。 根据 Make VariableBourne shell 令牌化

此属性中的每个字符串都按指定顺序添加到 COPTS 中,然后再编译二进制目标。这些标记仅在编译此目标(而非其依赖项)时才生效,因此请谨慎处理在别处添加的头文件。所有路径都应该相对于工作区,而不是当前软件包。

如果软件包声明 feature no_copts_tokenization,则 Bourne shell 标记化功能仅适用于由单个“Make”变量组成的字符串。

defines

List of strings; optional

要添加到编译行的定义列表。符合 Makequot 变量替换和 Bourne shell 词法单元化。每个字符串都必须包含一个 Bourne shell 令牌,请在前面加上 -D,然后将其添加到此目标的编译命令行以及依赖于该目标的每条规则。请格外小心,因为这可能会造成深远的影响。如有疑问,请改用 local_defines 定义定义值。
includes

List of strings; optional

要添加到编译行中的包含目录。

适用 Make 设为变量替换。 每个字符串前面都会附加 -isystem 并将其添加到 COPTS 中。与 COPTS 不同,这些标记是为此规则以及依赖于此规则的每条规则添加的。(注意:并非取决于其所依赖的规则!)请务必小心,这可能会产生深远的影响。如有疑问,请改为将“-I”标记添加到 COPTS

必须将头文件添加到 src 或 hdr,否则在编译时被沙盒化(默认情况)时,头文件将不可用于依赖规则。

linkopts

List of strings; optional

将这些标志添加到 C++ 链接器命令。符合 Makequot 变量替换、Bourne shell 令牌化标签扩展要求。 此属性中的每个字符串都会先添加到 LINKOPTS,然后再关联二进制目标。

此列表中不以 $- 开头的每个元素都被视为 deps 中的目标标签。该目标生成的文件列表会附加到链接器选项中。如果标签无效或未在 deps 中声明,系统便会报告错误。

linkshared

Boolean; optional; nonconfigurable; default is False

创建共享库。 要启用此属性,请在规则中添加 linkshared=True。默认情况下,此选项处于关闭状态。

如果存在此标记,则表示将 -shared 标志链接到 gcc,并且生成的共享库适合加载到 例如 Java 程序中。不过,出于构建目的,它绝不会链接到从属二进制文件,因为系统会假定使用 cc_binary 规则构建的共享库仅由其他程序手动加载,因此不应将其视为可替代 cc_library 规则。为了实现可伸缩性,我们建议完全避免使用这种方法,而只是让 java_library 改为依赖于 cc_library 规则。

如果您同时指定 linkopts=['-static']linkshared=True,您将得到一个完全独立的单元。如果您同时指定 linkstatic=1linkshared=True,您将得到一个基本独立的单元。

linkstatic

Boolean; optional; default is True

对于 cc_binarycc_test:以静态模式关联二进制文件。对于 cc_library.linkstatic:请参阅下文。

默认情况下,此选项会为 cc_binary 启用,而为其余选项关闭。

如果启用此选项,则为二进制文件或测试。此选项会指示构建工具尽可能在 .a 而不是 .so 中链接到用户库。 有些系统库仍可能是动态链接的,没有静态库的库也是如此。因此,生成的可执行文件仍会动态链接,因此大部分是静态的。

关联可执行文件的方法有很多,如下所示:

  • 具有 full_static_link 功能的 STATIC,其中所有内容静态关联;例如 "gcc -static foo.o libbar.a libbaz.a -lm"。
    此模式通过在 features 属性中指定 fully_static_link 来启用。
  • STATIC,其中静态关联所有用户库(如果有静态版本),但动态关联系统库(C/C++ 运行时库除外),例如 "gcc foo.o libfoo.a libbaz.a -lm"。
    通过指定 linkstatic=True 启用此模式。
  • DYNAMIC,其中所有库都动态链接(如果动态版本可用),例如 "gcc foo.o libfoo.so libbaz.so -lm".
    此模式通过指定 linkstatic=False 启用。

cc_library() 规则中使用时,linkstatic 特性具有不同的含义。对于 C++ 库,linkstatic=True 表示仅允许静态链接,因此不会生成 .so。linkstatic=False 不会阻止创建静态库。此属性用于控制动态库的创建。

如果为 linkstatic=False,构建工具会在 *.runfiles 区域中创建指向依赖于共享库的符号链接。

local_defines

List of strings; optional

要添加到编译行的定义列表。符合 Makequot 变量替换和 Bourne shell 词法单元化。每个字符串都必须由单个 Bourne shell 令牌组成,前面会附加 -D 并添加到此目标的编译命令行中,但不会添加到其依赖项中。
malloc

Label; optional; default is @bazel_tools//tools/cpp:malloc

覆盖 malloc 的默认依赖项。

默认情况下,C++ 二进制文件与 //tools/cpp:malloc 相关联,后者是一个空库,因此二进制文件最终使用 libc malloc。此标签必须引用 cc_library。如果编译针对的是非 C++ 规则,此选项无效。如果指定了 linkshared=True,此属性的值会被忽略。

nocopts

String; optional

从 C++ 编译命令中移除匹配选项。 适用 Make 变量。 此属性的值解释为正则表达式。出于编译此规则的目的,将从 COPTS 中移除任何与此正则表达式匹配的预先存在的 COPTS(包括在规则的 copts 属性中明确指定的值)。但应该很少需要用到此属性。
stamp

Integer; optional; default is -1

是否将构建信息编码到二进制文件中。可能的值:
  • stamp = 1:始终将构建信息标记到二进制文件中,即使在 --nostamp build 中也是如此。应该避免此设置,因为此设置可能会终止二进制文件的远程缓存以及依赖于二进制文件的任何下游操作。
  • stamp = 0:始终使用常量值替换 build 信息。这样可以提供良好的构建结果缓存。
  • stamp = -1:build 信息的嵌入由 --[no]stamp 标志控制。

除非二进制文件的依赖项发生变化,否则它们不会重新构建。

win_def_file

Label; optional

要传递给链接器的 Windows DEF 文件。

仅当 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

Name; required

此目标的唯一名称。

hdrs

List of labels; optional

此预编译库发布的要由依赖项直接包含的来源头文件的列表。

Boolean; optional; default is False

如果该值为 1,依赖于(直接或间接)此 C++ 预编译库的任何二进制文件都将链接到静态库中归档的所有对象文件,即使某些二进制文件不包含二进制文件引用的符号也是如此。 如果您的代码没有在二进制文件中明确调用它(例如,如果您的代码注册为接收某些服务提供的某个回调),这会非常有用。

如果由于 Windows 中的已知问题,始终使用 VS 2017 而无法始终使用 VS 2017,请将 VS 2017 升级到最新版本。

interface_library

Label; optional

用于关联共享库的单个接口库。

允许的文件类型:.ifso.tbd.lib.so.dylib

shared_library

Label; optional

单个预编译共享库。Bazel 会确保在运行时供依赖于它的二进制文件使用。

允许的文件类型:.so.dll.dylib

static_library

Label; optional

单个预编译的静态库。

允许的文件类型:.a.pic.a.lib

system_provided

Boolean; optional; default is False

如果为 1,则表示由运行时提供所需的共享库。在这种情况下,应指定 interface_library,且 shared_library 应为空。

cc_library

cc_library(name, deps, srcs, data, hdrs, alwayslink, compatible_with, copts, defines, deprecation, distribs, exec_compatible_with, exec_properties, features, include_prefix, includes, interface_deps, 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_* 规则的 hdrssrcs 中声明。系统会强制执行此政策。

对于 cc_library 规则,hdrs 中的头文件构成了该库的公共接口,可以直接从库本身的 hdrssrcs 文件中添加,也可以直接包含在 cc_* 规则的 hdrssrcs 中列出,后者会在其 deps 中列出相应库。srcs 中的头文件必须直接从库本身的 hdrssrcs 的文件中添加。在确定将某个头文件放入 hdrs 还是 srcs 时,您应询问是否希望此库的使用者能够直接包含该头文件。这与在编程语言中的 publicprivate 可见性之间的决定大致相同。

cc_binarycc_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.hbar.h,但不能包含 baz.h

包含的文件允许包含的内容
foo.h吧台
foo.ccfoo.h bar.h
吧台bar-impl.h baz.h
bar-impl.hbar.h baz.h
bar.ccbar.h bar-impl.h baz.h
baz.hbaz-impl.h
baz-impl.hbaz.h
baz.ccbaz.h baz-impl.h

包含检查规则仅适用于直接包含。在上面的示例中,foo.cc 可以包含 bar.h,而 baz.h 中也可以包含 baz-impl.h。从技术上讲,编译 .cc 文件时,可以在传递 deps 闭包的任何 cc_library 中以传递方式包含 hdrssrcs 中的任何头文件。在这种情况下,编译器在编译 foo.cc 时可能会读取 baz.hbaz-impl.h,但 foo.cc 不得包含 #include "baz.h"。为此,必须将 baz 添加到 foodeps

遗憾的是,Bazel 目前无法区分直接包含和传递包含,因此,它无法检测出文件错误地包含仅允许以传递方式包含的头文件的错误情况。例如,如果上面的示例中 foo.cc 直接包含 baz.h,则 Bazel 不会投诉。这是违法的,因为 foo 不直接依赖于 baz。在这种情况下,目前不会产生任何错误,但将来可能会添加此类错误检查。

参数

特性
name

Name; required

此目标的唯一名称。

deps

List of labels; optional

要链接到二进制目标的其他库的列表。

可以是 cc_libraryobjc_library 目标。

srcs

List of labels; optional

为创建目标而处理的 C 和 C++ 文件的列表。这些是 C/C++ 源文件和头文件,可以是非生成的(常规源代码)文件,也可以是生成的文件。

所有 .cc.c.cpp 文件都将被编译。这些可能是生成的文件:如果某个已命名文件位于某个其他规则的 outs 中,此规则将自动依赖于该另一个规则。

系统不会编译 .h 文件,但会将此规则纳入到来源中。.cc.h 文件都可以直接包含这些 srcsdeps 参数中列出的任何规则的 hdrs 中列出的标头。

所有 #included 文件都必须在此规则的 srcs 属性或引用 cc_library()hdrs 属性中。推荐的样式是与某个库关联的头文件列在库的 hdrs 属性中,而与此规则关联的任何剩余头文件要在 srcs 中列出。如需更详细的说明,请参阅“标头包含值检查”

如果规则的名称位于 srcs 中,则此规则会自动依赖于此规则。如果指定的规则的 outs 是 C 或 C++ 源文件,系统会将其编译到此规则中;如果它们是库文件,则会链接到这些文件。

允许的 srcs 文件类型:

  • C 和 C++ 源文件:.c.cc.cpp.cxx.c++.C
  • C 和 C++ 头文件:.h.hh.hpp.hxx.inc.inl.H
  • 具有 C 预处理器的汇编程序:.S
  • 归档:.a.pic.a
  • “始终链接”库:.lo.pic.lo
  • 有版本控制或未版本控制的共享库:.so.so.version
  • 对象文件:.o.pic.o

...以及生成这些文件的所有规则。 根据 gcc 惯例,不同的扩展名表示不同的编程语言。

hdrs

List of labels; optional

此库发布的要由源文件直接包含的头文件列表。

这是声明声明库接口头文件的首选位置。这些头文件将可由此规则或依赖规则中的来源包含。 不应由此库的客户端包含的标头应列在 srcs 属性中,即使这些头文件包含在已发布的头文件中也是如此。如需更详细的说明,请参阅标头包含值检查

Boolean; optional; default is False

如果该值为 1,则依赖(直接或间接)此 C++ 库的任何二进制文件都将在 srcs 中列出的文件的所有对象文件中进行链接,即使某些二进制文件不包含二进制文件引用的符号也是如此。 如果您的代码没有在二进制文件中明确调用它(例如,如果您的代码注册为接收某些服务提供的某个回调),这会非常有用。

如果由于 Windows 中的已知问题,始终使用 VS 2017 而无法始终使用 VS 2017,请将 VS 2017 升级到最新版本。

copts

List of strings; optional

将这些选项添加到 C++ 编译命令。 根据 Make VariableBourne shell 令牌化

此属性中的每个字符串都按指定顺序添加到 COPTS 中,然后再编译二进制目标。这些标记仅在编译此目标(而非其依赖项)时才生效,因此请谨慎处理在别处添加的头文件。所有路径都应该相对于工作区,而不是当前软件包。

如果软件包声明 feature no_copts_tokenization,则 Bourne shell 标记化功能仅适用于由单个“Make”变量组成的字符串。

defines

List of strings; optional

要添加到编译行的定义列表。符合 Makequot 变量替换和 Bourne shell 词法单元化。每个字符串都必须包含一个 Bourne shell 令牌,请在前面加上 -D,然后将其添加到此目标的编译命令行以及依赖于该目标的每条规则。请格外小心,因为这可能会造成深远的影响。如有疑问,请改用 local_defines 定义定义值。
include_prefix

String; optional

要添加到此规则的标头路径中的前缀。

设置后,此规则的 hdrs 属性中的标头可以访问该属性的值,附加到其存储库相对路径的前面。

在添加此前缀之前,系统会移除 strip_include_prefix 属性中的前缀。

includes

List of strings; optional

要添加到编译行中的包含目录。

适用 Make 设为变量替换。 每个字符串前面都会附加 -isystem 并将其添加到 COPTS 中。与 COPTS 不同,这些标记是为此规则以及依赖于此规则的每条规则添加的。(注意:并非取决于其所依赖的规则!)请务必小心,这可能会产生深远的影响。如有疑问,请改为将“-I”标记添加到 COPTS

必须将头文件添加到 src 或 hdr,否则在编译时被沙盒化(默认情况)时,头文件将不可用于依赖规则。

interface_deps

List of labels; optional

--experimental_cc_interface_deps 为 True 时,依赖项中列出的目标将用作实现依赖项。与常规依赖项不同,头文件和包含实现依赖项的路径(及其所有传递依赖项)仅用于编译此库,而不用于依赖此库的库。由于依赖于此库的实现依赖项仍然在依赖此库的二进制目标中,因此需要依赖这些库。interface_deps 中列出的依赖项将继续具有与旧版依赖项相同的行为,即头文件和 include 路径在下游传播。
linkopts

List of strings; optional

将这些标志添加到 C++ 链接器命令。符合 Makequot 变量替换、Bourne shell 令牌化标签扩展要求。 此属性中的每个字符串都会先添加到 LINKOPTS,然后再关联二进制目标。

此列表中不以 $- 开头的每个元素都被视为 deps 中的目标标签。该目标生成的文件列表会附加到链接器选项中。如果标签无效或未在 deps 中声明,系统便会报告错误。

linkstamp

Label; optional

同时编译指定的 C++ 源文件,并将其链接到最终二进制文件。需要使用这种技巧才能将时间戳信息引入二进制文件;如果我们以常规方式将源文件编译到对象文件中,时间戳就会出错。 链接 AMP 编译不得包含任何一组特定的编译器标记,因此不应依赖于任何特定的头文件、编译器选项或其他构建变量。 此选项应仅在 base 软件包中需要。
linkstatic

Boolean; optional; default is False

对于 cc_binarycc_test:以静态模式关联二进制文件。对于 cc_library.linkstatic:请参阅下文。

默认情况下,此选项会为 cc_binary 启用,而为其余选项关闭。

如果启用此选项,则为二进制文件或测试。此选项会指示构建工具尽可能在 .a 而不是 .so 中链接到用户库。 有些系统库仍可能是动态链接的,没有静态库的库也是如此。因此,生成的可执行文件仍会动态链接,因此大部分是静态的。

关联可执行文件的方法有很多,如下所示:

  • 具有 full_static_link 功能的 STATIC,其中所有内容静态关联;例如 "gcc -static foo.o libbar.a libbaz.a -lm"。
    此模式通过在 features 属性中指定 fully_static_link 来启用。
  • STATIC,其中静态关联所有用户库(如果有静态版本),但动态关联系统库(C/C++ 运行时库除外),例如 "gcc foo.o libfoo.a libbaz.a -lm"。
    通过指定 linkstatic=True 启用此模式。
  • DYNAMIC,其中所有库都动态链接(如果动态版本可用),例如 "gcc foo.o libfoo.so libbaz.so -lm".
    此模式通过指定 linkstatic=False 启用。

cc_library() 规则中使用时,linkstatic 特性具有不同的含义。对于 C++ 库,linkstatic=True 表示仅允许静态链接,因此不会生成 .so。linkstatic=False 不会阻止创建静态库。此属性用于控制动态库的创建。

如果为 linkstatic=False,构建工具会在 *.runfiles 区域中创建指向依赖于共享库的符号链接。

local_defines

List of strings; optional

要添加到编译行的定义列表。符合 Makequot 变量替换和 Bourne shell 词法单元化。每个字符串都必须由单个 Bourne shell 令牌组成,前面会附加 -D 并添加到此目标的编译命令行中,但不会添加到其依赖项中。
nocopts

String; optional

从 C++ 编译命令中移除匹配选项。 适用 Make 变量。 此属性的值解释为正则表达式。出于编译此规则的目的,将从 COPTS 中移除任何与此正则表达式匹配的预先存在的 COPTS(包括在规则的 copts 属性中明确指定的值)。但应该很少需要用到此属性。
strip_include_prefix

String; optional

用于从此规则的标头路径中移除的前缀。

设置后,此规则的 hdrs 属性中的头文件可以在其路径上访问,但此前缀被截断。

如果是相对路径,则将其视为与软件包相对的路径。如果它是绝对路径,它可以被理解为存储库的相对路径。

在去除此前缀后,系统会在 include_prefix 属性中添加前缀。

textual_hdrs

List of labels; optional

此库发布的标头文件列表,在依赖项规则中,源文件将以文本形式包含。

这是声明无法自行编译的头文件的位置;也就是说,它们始终需要由其他源文件以文本形式添加,才能构建有效的代码。

win_def_file

Label; optional

要传递给链接器的 Windows DEF 文件。

仅当 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

Name; required

此目标的唯一名称。

deps

List of labels; optional

要为其生成 C++ 代码的 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

Name; required

此目标的唯一名称。

profile

Label; optional

提示个人资料的标签。提示文件具有 .afdo 扩展名 标签也可以指向 fdo_绝对_path_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

Name; required

此目标的唯一名称。

absolute_path_profile

String; optional

FDO 配置文件的绝对路径。FDO 文件只能采用 .afdo 扩展名。
profile

Label; optional

FDO 配置文件的标签。{0}该标签还可以指向 fdo_绝对_路径_配置文件规则。
proto_profile

Label; optional

protobuf 配置文件的标签。

propeller_optimize

propeller_optimize(name, compatible_with, deprecation, distribs, features, ld_profile, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)

表示工作区中的推进器优化配置文件。 示例:

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

Name; required

此目标的唯一名称。

ld_profile

Label; optional

传递给关联操作的配置文件的标签。此文件的扩展名为 .txt。

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

Name; required

此目标的唯一名称。

deps

List of labels; optional

要链接到二进制目标的其他库的列表。

可以是 cc_libraryobjc_library 目标。

srcs

List of labels; optional

为创建目标而处理的 C 和 C++ 文件的列表。这些是 C/C++ 源文件和头文件,可以是非生成的(常规源代码)文件,也可以是生成的文件。

所有 .cc.c.cpp 文件都将被编译。这些可能是生成的文件:如果某个已命名文件位于某个其他规则的 outs 中,此规则将自动依赖于该另一个规则。

系统不会编译 .h 文件,但会将此规则纳入到来源中。.cc.h 文件都可以直接包含这些 srcsdeps 参数中列出的任何规则的 hdrs 中列出的标头。

所有 #included 文件都必须在此规则的 srcs 属性或引用 cc_library()hdrs 属性中。推荐的样式是与某个库关联的头文件列在库的 hdrs 属性中,而与此规则关联的任何剩余头文件要在 srcs 中列出。如需更详细的说明,请参阅“标头包含值检查”

如果规则的名称位于 srcs 中,则此规则会自动依赖于此规则。如果指定的规则的 outs 是 C 或 C++ 源文件,系统会将其编译到此规则中;如果它们是库文件,则会链接到这些文件。

允许的 srcs 文件类型:

  • C 和 C++ 源文件:.c.cc.cpp.cxx.c++.C
  • C 和 C++ 头文件:.h.hh.hpp.hxx.inc.inl.H
  • 具有 C 预处理器的汇编程序:.S
  • 归档:.a.pic.a
  • “始终链接”库:.lo.pic.lo
  • 有版本控制或未版本控制的共享库:.so.so.version
  • 对象文件:.o.pic.o

...以及生成这些文件的所有规则。 根据 gcc 惯例,不同的扩展名表示不同的编程语言。

additional_linker_inputs

List of labels; optional

将这些文件传递给 C++ 链接器命令。

例如,在此处提供的经过编译的 Windows .res 文件可嵌入到二进制目标中。

copts

List of strings; optional

将这些选项添加到 C++ 编译命令。 根据 Make VariableBourne shell 令牌化

此属性中的每个字符串都按指定顺序添加到 COPTS 中,然后再编译二进制目标。这些标记仅在编译此目标(而非其依赖项)时才生效,因此请谨慎处理在别处添加的头文件。所有路径都应该相对于工作区,而不是当前软件包。

如果软件包声明 feature no_copts_tokenization,则 Bourne shell 标记化功能仅适用于由单个“Make”变量组成的字符串。

defines

List of strings; optional

要添加到编译行的定义列表。符合 Makequot 变量替换和 Bourne shell 词法单元化。每个字符串都必须包含一个 Bourne shell 令牌,请在前面加上 -D,然后将其添加到此目标的编译命令行以及依赖于该目标的每条规则。请格外小心,因为这可能会造成深远的影响。如有疑问,请改用 local_defines 定义定义值。
includes

List of strings; optional

要添加到编译行中的包含目录。

适用 Make 设为变量替换。 每个字符串前面都会附加 -isystem 并将其添加到 COPTS 中。与 COPTS 不同,这些标记是为此规则以及依赖于此规则的每条规则添加的。(注意:并非取决于其所依赖的规则!)请务必小心,这可能会产生深远的影响。如有疑问,请改为将“-I”标记添加到 COPTS

必须将头文件添加到 src 或 hdr,否则在编译时被沙盒化(默认情况)时,头文件将不可用于依赖规则。

linkopts

List of strings; optional

将这些标志添加到 C++ 链接器命令。符合 Makequot 变量替换、Bourne shell 令牌化标签扩展要求。 此属性中的每个字符串都会先添加到 LINKOPTS,然后再关联二进制目标。

此列表中不以 $- 开头的每个元素都被视为 deps 中的目标标签。该目标生成的文件列表会附加到链接器选项中。如果标签无效或未在 deps 中声明,系统便会报告错误。

linkstatic

Boolean; optional; default is False

对于 cc_binarycc_test:以静态模式关联二进制文件。对于 cc_library.linkstatic:请参阅下文。

默认情况下,此选项会为 cc_binary 启用,而为其余选项关闭。

如果启用此选项,则为二进制文件或测试。此选项会指示构建工具尽可能在 .a 而不是 .so 中链接到用户库。 有些系统库仍可能是动态链接的,没有静态库的库也是如此。因此,生成的可执行文件仍会动态链接,因此大部分是静态的。

关联可执行文件的方法有很多,如下所示:

  • 具有 full_static_link 功能的 STATIC,其中所有内容静态关联;例如 "gcc -static foo.o libbar.a libbaz.a -lm"。
    此模式通过在 features 属性中指定 fully_static_link 来启用。
  • STATIC,其中静态关联所有用户库(如果有静态版本),但动态关联系统库(C/C++ 运行时库除外),例如 "gcc foo.o libfoo.a libbaz.a -lm"。
    通过指定 linkstatic=True 启用此模式。
  • DYNAMIC,其中所有库都动态链接(如果动态版本可用),例如 "gcc foo.o libfoo.so libbaz.so -lm".
    此模式通过指定 linkstatic=False 启用。

cc_library() 规则中使用时,linkstatic 特性具有不同的含义。对于 C++ 库,linkstatic=True 表示仅允许静态链接,因此不会生成 .so。linkstatic=False 不会阻止创建静态库。此属性用于控制动态库的创建。

如果为 linkstatic=False,构建工具会在 *.runfiles 区域中创建指向依赖于共享库的符号链接。

local_defines

List of strings; optional

要添加到编译行的定义列表。符合 Makequot 变量替换和 Bourne shell 词法单元化。每个字符串都必须由单个 Bourne shell 令牌组成,前面会附加 -D 并添加到此目标的编译命令行中,但不会添加到其依赖项中。
malloc

Label; optional; default is @bazel_tools//tools/cpp:malloc

覆盖 malloc 的默认依赖项。

默认情况下,C++ 二进制文件与 //tools/cpp:malloc 相关联,后者是一个空库,因此二进制文件最终使用 libc malloc。此标签必须引用 cc_library。如果编译针对的是非 C++ 规则,此选项无效。如果指定了 linkshared=True,此属性的值会被忽略。

nocopts

String; optional

从 C++ 编译命令中移除匹配选项。 适用 Make 变量。 此属性的值解释为正则表达式。出于编译此规则的目的,将从 COPTS 中移除任何与此正则表达式匹配的预先存在的 COPTS(包括在规则的 copts 属性中明确指定的值)。但应该很少需要用到此属性。
stamp

Integer; optional; default is 0

是否将构建信息编码到二进制文件中。可能的值:
  • stamp = 1:始终将构建信息标记到二进制文件中,即使在 --nostamp build 中也是如此。应该避免此设置,因为此设置可能会终止二进制文件的远程缓存以及依赖于二进制文件的任何下游操作。
  • stamp = 0:始终使用常量值替换 build 信息。这样可以提供良好的构建结果缓存。
  • stamp = -1:build 信息的嵌入由 --[no]stamp 标志控制。

除非二进制文件的依赖项发生变化,否则它们不会重新构建。

win_def_file

Label; optional

要传递给链接器的 Windows DEF 文件。

仅当 Windows 是目标平台时,才应使用此属性。 它可用于在链接共享库期间导出符号

cc_工具链

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_filescompiler_fileslinker_files 等属性或以 _files 结尾的其他属性来完成。这些是最常见的文件组,会合并所有必需文件。
  • 为 C++ 操作生成正确的命令行。这是使用 CcToolchainConfigInfo 提供程序实现的(详情如下)。

使用 toolchain_config 属性配置 C++ 工具链。另请参阅此页面,获取详细的 C++ 工具链配置和工具链选择文档。

使用 tags = ["manual"] 可防止在调用 bazel build //... 时不必要地构建和配置工具链

参数

特性
name

Name; required

此目标的唯一名称。

all_files

Label; required

所有 cc_工具链工件的集合。这些工件将作为输入添加到所有 rules_cc 相关操作(使用来自以下特性的更精确工件集合的操作除外)。Bazel 假定 all_files 是所有其他提供工件的属性的超集(例如,linksamp 编译需要编译和链接文件,因此需要 all_files)。

这是 cc_toolchain.files 包含的内容,供所有使用 C++ 工具链的 Starlark 规则使用。

ar_files

Label; optional

归档操作所需的所有 cc_工具链工件的集合。

as_files

Label; optional

汇编操作所需的全部 cc_工具链工件的集合。

compiler

String; optional; nonconfigurable

已弃用。请改用 toolchain_identifier 属性。在将 CROSSTOOL 迁移到 Starlark 后,它会是一个空函数,将在 #7075 中移除。

设置后,它将用于执行 crosstool_config.工具链选择。它优先于 --cpu Bazel 选项。

compiler_files

Label; required

编译操作所需的所有 cc_工具链工件的集合。

目前仅 lto_backend 操作使用,常规编译操作使用 all_files (#6927)。

compiler_files_without_includes

Label; optional

在支持输入发现的情况下,编译操作所需的所有 cc_工具链工件(目前仅限 Google)的集合。
coverage_files

Label; optional

收集操作所需的所有 cc_工具链工件的集合。如果未指定,则使用 all_files。
cpu

String; optional; nonconfigurable

已弃用。请改为使用 工具链属性标识符。在 CROSSTOOL 迁移到 Starlark 之后,这将是一个空操作,并且将由 #7075 移除。

设置后,它将用于执行 crosstool_config.工具链选择。它优先于 --cpu Bazel 选项。

dwp_files

Label; required

DWP 操作所需的所有 cc_工具链工件的集合。
dynamic_runtime_lib

Label; optional

C++ 运行时库的动态库工件(例如 libstdc++.so)。

此属性将在启用“静态链接链接运行时”功能时使用,并且我们会动态关联依赖项。

exec_transition_for_inputs

Boolean; optional; default is True

如果设置为 True,则会针对执行平台将所有文件输入构建到 cc_工具链,而不是无过渡(即默认目标平台)。
libc_top

Label; optional

作为传递至编译/关联操作的输入的 libc 工件集合。
linker_files

Label; required

关联操作所需的所有 cc_工具链工件的集合。
module_map

Label; optional

将用于模块化 build 的模块映射工件。
objcopy_files

Label; required

objcopy 操作所需的所有 cc_工具链工件的集合。
static_runtime_lib

Label; optional

C++ 运行时库的静态库工件(例如 libstdc++.a)。

这将在以下情况下使用:静态链接功能已启用,我们会静态地链接依赖项。

strip_files

Label; required

执行剥离操作所需的所有 cc_工具链工件的集合。
supports_header_parsing

Boolean; optional; default is False

如果 cc_工具链支持标头解析操作,则设置为 True。
supports_param_files

Boolean; optional; default is True

如果 cc_toolchain 支持使用参数文件关联操作,则设为 True。
toolchain_config

Label; required

提供 cc_toolchain_config_info 的规则的标签。
toolchain_identifier

String; optional; nonconfigurable

用于将此 cc_工具链与对应的 crosstool_config.toolchain 匹配的标识符。

在问题 #5380 的问题解决之前,建议采用此方法将 cc_toolchainCROSSTOOL.toolchain 相关联。取而代之的是 toolchain_config 属性 (#5380)。

cc_工具链_套件

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

Name; required

此目标的唯一名称。

toolchains

Dictionary mapping strings to labels; required; nonconfigurable

从 "<cpu>" 或 "<cpu>|<compiler>" 字符串到 cc_toolchain 标签的映射。"<cpu>" 仅在 --cpu 传递到 Bazel 时使用,而 "<cpu>|<compiler>" 将在 --cpu--compiler 都传递给 Bazel 时使用。示例:

          cc_toolchain_suite(
            name = "toolchain",
            toolchains = {
              "piii|gcc": ":my_cc_toolchain_for_piii_using_gcc",
              "piii": ":my_cc_toolchain_for_piii_using_default_compiler",
            },
          )