C / C++ Rules

Report an issue View source Nightly · 8.0 · 7.4 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Rules

cc_binary

View rule source 
cc_binary(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, exec_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, output_licenses, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file)

It produces an executable binary.


The name of the target should be the same as the name of the source file that is the main entry point of the application (minus the extension). For example, if your entry point is in main.cc, then your name should be main.

Implicit output targets

  • name.stripped (only built if explicitly requested): A stripped version of the binary. strip -g is run on the binary to remove debug symbols. Additional strip options can be provided on the command line using --stripopt=-foo.
  • name.dwp (only built if explicitly requested): If Fission is enabled: a debug information package file suitable for debugging remotely deployed binaries. Else: an empty file.

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; default is []

The list of other libraries to be linked in to the binary target.

These can be cc_library or objc_library targets.

It is also allowed to put linker scripts (.lds) into deps, and reference them in linkopts.
srcs

List of labels; default is []

The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated.

All .cc, .c, and .cpp files will be compiled. These might be generated files: if a named file is in the outs of some other rule, this cc_library will automatically depend on that other rule.

Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler.

A .h file will not be compiled, but will be available for inclusion by sources in this rule. Both .cc and .h files can directly include headers listed in these srcs or in the hdrs of this rule or any rule listed in the deps argument.

All #included files must be mentioned in the hdrs attribute of this or referenced cc_library rules, or they should be listed in srcs if they are private to this library. See "Header inclusion checking" for a more detailed description.

.so, .lo, and .a files are pre-compiled files. Your library might have these as srcs if it uses third-party code for which we don't have source code.

If the srcs attribute includes the label of another rule, cc_library will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the cc_common API)

Permitted srcs file types:

  • C and C++ source files: .c, .cc, .cpp, .cxx, .c++, .C
  • C and C++ header files: .h, .hh, .hpp, .hxx, .inc, .inl, .H
  • Assembler with C preprocessor: .S
  • Archive: .a, .pic.a
  • "Always link" library: .lo, .pic.lo
  • Shared library, versioned or unversioned: .so, .so.version
  • Object file: .o, .pic.o

... and any rules that produce those files (e.g. cc_embed_data). Different extensions denote different programming languages in accordance with gcc convention.

data

List of labels; default is []

The list of files needed by this library at runtime. See general comments about data at Typical attributes defined by most build rules.

If a data is the name of a generated file, then this cc_library rule automatically depends on the generating rule.

If a data is a rule name, then this cc_library rule automatically depends on that rule, and that rule's outs are automatically added to this cc_library's data files.

Your C++ code can access these data files like so:


  const std::string path = devtools_build::GetDataDependencyFilepath(
      "my/test/data/file");
additional_linker_inputs

List of labels; default is []

Pass these files to the C++ linker command.

For example, compiled Windows .res files can be provided here to be embedded in the binary target.

conlyopts

List of strings; default is []

Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.
copts

List of strings; default is []

Add these options to the C/C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.

Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of third_party.

If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.

cxxopts

List of strings; default is []

Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.
defines

List of strings; default is []

List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead.
dynamic_deps

List of labels; default is []

These are other cc_shared_library dependencies the current target depends on.

The cc_shared_library implementation will use the list of dynamic_deps (transitively, i.e. also the dynamic_deps of the current target's dynamic_deps) to decide which cc_libraries in the transitive deps should not be linked in because they are already provided by a different cc_shared_library.

hdrs_check

String; default is ""

Deprecated, no-op.
includes

List of strings; default is []

List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce -isystem path_to_package/include_entry. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead.

The added include paths will include generated files as well as files in the source tree.

Label; default is "@bazel_tools//tools/cpp:link_extra_lib"

Control linking of extra libraries.

By default, C++ binaries are linked against //tools/cpp:link_extra_lib, which by default depends on the label flag //tools/cpp:link_extra_libs. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer malloc or --custom_malloc). Setting this attribute to None disables this behaviour.

linkopts

List of strings; default is []

Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target.

Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps.

linkshared

Boolean; default is False

Create a shared library. To enable this attribute, include linkshared=True in your rule. By default this option is off.

The presence of this flag means that linking occurs with the -shared flag to gcc, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a cc_binary rule are only loaded manually by other programs, so it should not be considered a substitute for the cc_library rule. For sake of scalability we recommend avoiding this approach altogether and simply letting java_library depend on cc_library rules instead.

If you specify both linkopts=['-static'] and linkshared=True, you get a single completely self-contained unit. If you specify both linkstatic=True and linkshared=True, you get a single, mostly self-contained unit.

linkstatic

Boolean; default is True

For cc_binary and cc_test: link the binary in static mode. For cc_library.link_static: see below.

By default this option is on for cc_binary and off for the rest.

If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static.

There are really three different ways to link an executable:

  • STATIC with fully_static_link feature, in which everything is linked statically; e.g. "gcc -static foo.o libbar.a libbaz.a -lm".
    This mode is enabled by specifying fully_static_link in the features attribute.
  • STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "gcc foo.o libfoo.a libbaz.a -lm".
    This mode is enabled by specifying linkstatic=True.
  • DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "gcc foo.o libfoo.so libbaz.so -lm".
    This mode is enabled by specifying linkstatic=False.

If the linkstatic attribute or fully_static_link in features is used outside of //third_party please include a comment near the rule to explain why.

The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries.

There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area.

local_defines

List of strings; default is []

List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents.
malloc

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

Override the default dependency on malloc.

By default, C++ binaries are linked against //tools/cpp:malloc, which is an empty library so the binary ends up using libc malloc. This label must refer to a cc_library. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if linkshared=True is specified.

module_interfaces

List of labels; default is []

The list of files are regarded as C++20 Modules Interface.

C++ Standard has no restriction about module interface file extension

  • Clang use cppm
  • GCC can use any source file extension
  • MSVC use ixx

The use is guarded by the flag --experimental_cpp_modules.
nocopts

String; default is ""

Remove matching options from the C++ compilation command. Subject to "Make" variable substitution. The value of this attribute is interpreted as a regular expression. Any preexisting COPTS that match this regular expression (including values explicitly specified in the rule's copts attribute) will be removed from COPTS for purposes of compiling this rule. This attribute should not be needed or used outside of third_party. The values are not preprocessed in any way other than the "Make" variable substitution.
reexport_deps

List of labels; default is []
stamp

Integer; default is -1

Whether to encode build information into the binary. Possible values:
  • stamp = 1: Always stamp the build information into the binary, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the binary and any downstream actions that depend on it.
  • stamp = 0: Always replace build information by constant values. This gives good build result caching.
  • stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped binaries are not rebuilt unless their dependencies change.
win_def_file

Label; default is None

The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.

cc_import

View rule source 
cc_import(name, deps, data, hdrs, alwayslink, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, includes, interface_library, linkopts, objects, pic_objects, pic_static_library, restricted_to, shared_library, static_library, system_provided, tags, target_compatible_with, testonly, toolchains, visibility)

cc_import rules allows users to import precompiled C/C++ libraries.

The following are the typical use cases:
1. Linking a static library 


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 = True,
)
2. Linking a shared library (Unix) 

cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  shared_library = "libmylib.so",
)
3. Linking a shared library with interface library

On Unix: 


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  # libmylib.ifso is an interface library for libmylib.so which will be passed to linker
  interface_library = "libmylib.ifso",
  # libmylib.so will be available for runtime
  shared_library = "libmylib.so",
)

On 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 will be available for runtime
  shared_library = "mylib.dll",
)
4. Linking a shared library with system_provided=True

On Unix: 


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  interface_library = "libmylib.ifso", # Or we can also use libmylib.so as its own interface library
  # libmylib.so is provided by system environment, for example it can be found in LD_LIBRARY_PATH.
  # This indicates that Bazel is not responsible for making libmylib.so available.
  system_provided = True,
)

On 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 = True,
)
5. Linking to static or shared library

On Unix: 


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  static_library = "libmylib.a",
  shared_library = "libmylib.so",
)

On 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",
)

The remaining is the same on Unix and Windows: 


# first will link to libmylib.a (or libmylib.lib)
cc_binary(
  name = "first",
  srcs = ["first.cc"],
  deps = [":mylib"],
  linkstatic = True, # default value
)

# second will link to libmylib.so (or libmylib.lib)
cc_binary(
  name = "second",
  srcs = ["second.cc"],
  deps = [":mylib"],
  linkstatic = False,
)

cc_import supports an include attribute. For example: 


cc_import(
  name = "curl_lib",
  hdrs = glob(["vendor/curl/include/curl/*.h"]),
  includes = ["vendor/curl/include"],
  shared_library = "vendor/curl/lib/.libs/libcurl.dylib",
)

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; default is []

The list of other libraries that the target depends upon. See general comments about deps at Typical attributes defined by most build rules.
hdrs

List of labels; default is []

The list of header files published by this precompiled library to be directly included by sources in dependent rules.

Boolean; default is False

If 1, any binary that depends (directly or indirectly) on this C++ precompiled library will link in all the object files archived in the static library, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service.

If alwayslink doesn't work with VS 2017 on Windows, that is due to a known issue, please upgrade your VS 2017 to the latest version.
includes

List of strings; default is []

List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce -isystem path_to_package/include_entry. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead.

The default include path doesn't include generated files. If you need to #include a generated header file, list it in the srcs.

interface_library

Label; default is None

A single interface library for linking the shared library.

Permitted file types: .ifso, .tbd, .lib, .so or .dylib

linkopts

List of strings; default is []

Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target.

Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps.

objects

List of labels; default is []
pic_objects

List of labels; default is []
pic_static_library

Label; default is None
shared_library

Label; default is None

A single precompiled shared library. Bazel ensures it is available to the binary that depends on it during runtime.

Permitted file types: .so, .dll or .dylib

static_library

Label; default is None

A single precompiled static library.

Permitted file types: .a, .pic.a or .lib

system_provided

Boolean; default is False

If 1, it indicates the shared library required at runtime is provided by the system. In this case, interface_library should be specified and shared_library should be empty.

cc_library

View rule source 
cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, exec_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, module_interfaces, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file)

Use cc_library() for C++-compiled libraries. The result is either a .so, .lo, or .a, depending on what is needed.

If you build something with static linking that depends on a cc_library, the output of a depended-on library rule is the .a file. If you specify alwayslink=True, you get the .lo file.

The actual output file name is libfoo.so for the shared library, where foo is the name of the rule. The other kinds of libraries end with .lo and .a, respectively. If you need a specific shared library name, for example, to define a Python module, use a genrule to copy the library to the desired name.

Header inclusion checking

All header files that are used in the build must be declared in the hdrs or srcs of cc_* rules. This is enforced.

For cc_library rules, headers in hdrs comprise the public interface of the library and can be directly included both from the files in hdrs and srcs of the library itself as well as from files in hdrs and srcs of cc_* rules that list the library in their deps. Headers in srcs must only be directly included from the files in hdrs and srcs of the library itself. When deciding whether to put a header into hdrs or srcs, you should ask whether you want consumers of this library to be able to directly include it. This is roughly the same decision as between public and private visibility in programming languages.

cc_binary and cc_test rules do not have an exported interface, so they also do not have a hdrs attribute. All headers that belong to the binary or test directly should be listed in the srcs.

To illustrate these rules, look at the following example. 


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"],
)

The allowed direct inclusions in this example are listed in the table below. For example foo.cc is allowed to directly include foo.h and bar.h, but not baz.h.

Including fileAllowed inclusions
foo.hbar.h
foo.ccfoo.h bar.h
bar.hbar-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

The inclusion checking rules only apply to direct inclusions. In the example above foo.cc is allowed to include bar.h, which may include baz.h, which in turn is allowed to include baz-impl.h. Technically, the compilation of a .cc file may transitively include any header file in the hdrs or srcs in any cc_library in the transitive deps closure. In this case the compiler may read baz.h and baz-impl.h when compiling foo.cc, but foo.cc must not contain #include "baz.h". For that to be allowed, baz must be added to the deps of foo.

Bazel depends on toolchain support to enforce the inclusion checking rules. The layering_check feature has to be supported by the toolchain and requested explicitly, for example via the --features=layering_check command-line flag or the features parameter of the package function. The toolchains provided by Bazel only support this feature with clang on Unix and macOS.

Examples


cc_library(
    name = "ast_inspector_lib",
    srcs = ["ast_inspector_lib.cc"],
    hdrs = ["ast_inspector_lib.h"],
    visibility = ["//visibility:public"],
    deps = ["//third_party/llvm/llvm/tools/clang:frontend"],
    # alwayslink as we want to be able to call things in this library at
    # debug time, even if they aren't used anywhere in the code.
    alwayslink = 1,
)

The following example comes from third_party/python2_4_3/BUILD. Some of the code uses the dl library (to load another, dynamic library), so this rule specifies the -ldl link option to link the dl library. 


cc_library(
    name = "python2_4_3",
    linkopts = [
        "-ldl",
        "-lutil",
    ],
    deps = ["//third_party/expat"],
)

The following example comes from third_party/kde/BUILD. We keep pre-built .so files in the depot. The header files live in a subdirectory named include. 


cc_library(
    name = "kde",
    srcs = [
        "lib/libDCOP.so",
        "lib/libkdesu.so",
        "lib/libkhtml.so",
        "lib/libkparts.so",
        ...more .so files...,
    ],
    includes = ["include"],
    deps = ["//third_party/X11"],
)

The following example comes from third_party/gles/BUILD. Third-party code often needs some defines and linkopts. 


cc_library(
    name = "gles",
    srcs = [
        "GLES/egl.h",
        "GLES/gl.h",
        "ddx.c",
        "egl.c",
    ],
    defines = [
        "USE_FLOAT",
        "__GL_FLOAT",
        "__GL_COMMON",
    ],
    linkopts = ["-ldl"],  # uses dlopen(), dl library
    deps = [
        "es",
        "//third_party/X11",
    ],
)

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; default is []

The list of other libraries that the library target depends upon.

These can be cc_library or objc_library targets.

See general comments about deps at Typical attributes defined by most build rules.

These should be names of C++ library rules. When you build a binary that links this rule's library, you will also link the libraries in deps.

Despite the "deps" name, not all of this library's clients belong here. Run-time data dependencies belong in data. Source files generated by other rules belong in srcs.

To link in a pre-compiled third-party library, add its name to the srcs instead.

To depend on something without linking it to this library, add its name to the data instead.

srcs

List of labels; default is []

The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated.

All .cc, .c, and .cpp files will be compiled. These might be generated files: if a named file is in the outs of some other rule, this cc_library will automatically depend on that other rule.

Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler.

A .h file will not be compiled, but will be available for inclusion by sources in this rule. Both .cc and .h files can directly include headers listed in these srcs or in the hdrs of this rule or any rule listed in the deps argument.

All #included files must be mentioned in the hdrs attribute of this or referenced cc_library rules, or they should be listed in srcs if they are private to this library. See "Header inclusion checking" for a more detailed description.

.so, .lo, and .a files are pre-compiled files. Your library might have these as srcs if it uses third-party code for which we don't have source code.

If the srcs attribute includes the label of another rule, cc_library will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the cc_common API)

Permitted srcs file types:

  • C and C++ source files: .c, .cc, .cpp, .cxx, .c++, .C
  • C and C++ header files: .h, .hh, .hpp, .hxx, .inc, .inl, .H
  • Assembler with C preprocessor: .S
  • Archive: .a, .pic.a
  • "Always link" library: .lo, .pic.lo
  • Shared library, versioned or unversioned: .so, .so.version
  • Object file: .o, .pic.o

... and any rules that produce those files (e.g. cc_embed_data). Different extensions denote different programming languages in accordance with gcc convention.

data

List of labels; default is []

The list of files needed by this library at runtime. See general comments about data at Typical attributes defined by most build rules.

If a data is the name of a generated file, then this cc_library rule automatically depends on the generating rule.

If a data is a rule name, then this cc_library rule automatically depends on that rule, and that rule's outs are automatically added to this cc_library's data files.

Your C++ code can access these data files like so:


  const std::string path = devtools_build::GetDataDependencyFilepath(
      "my/test/data/file");
hdrs

List of labels; default is []

The list of header files published by this library to be directly included by sources in dependent rules.

This is the strongly preferred location for declaring header files that describe the interface for the library. These headers will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the srcs attribute instead, even if they are included by a published header. See "Header inclusion checking" for a more detailed description.

Permitted headers file types: .h, .hh, .hpp, .hxx.

additional_compiler_inputs

List of labels; default is []

Any additional files you might want to pass to the compiler command line, such as sanitizer ignorelists, for example. Files specified here can then be used in copts with the $(location) function.
additional_linker_inputs

List of labels; default is []

Pass these files to the C++ linker command.

For example, compiled Windows .res files can be provided here to be embedded in the binary target.

Boolean; default is False

If 1, any binary that depends (directly or indirectly) on this C++ library will link in all the object files for the files listed in srcs, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service.

If alwayslink doesn't work with VS 2017 on Windows, that is due to a known issue, please upgrade your VS 2017 to the latest version.
conlyopts

List of strings; default is []

Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.
copts

List of strings; default is []

Add these options to the C/C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.

Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of third_party.

If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.

cxxopts

List of strings; default is []

Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.
defines

List of strings; default is []

List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead.
hdrs_check

String; default is ""

Deprecated, no-op.
implementation_deps

List of labels; default is []

The list of other libraries that the library target depends on. Unlike with deps, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with implementation_deps are still linked in binary targets that depend on this library.
include_prefix

String; default is ""

The prefix to add to the paths of the headers of this rule.

When set, the headers in the hdrs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path.

The prefix in the strip_include_prefix attribute is removed before this prefix is added.

This attribute is only legal under third_party.

includes

List of strings; default is []

List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce -isystem path_to_package/include_entry. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead.

The added include paths will include generated files as well as files in the source tree.

linkopts

List of strings; default is []

See cc_binary.linkopts. The linkopts attribute is also applied to any target that depends, directly or indirectly, on this library via deps attributes (or via other attributes that are treated similarly: the malloc attribute of cc_binary). Dependency linkopts take precedence over dependent linkopts (i.e. dependency linkopts appear later in the command line). Linkopts specified in --linkopt take precedence over rule linkopts.

Note that the linkopts attribute only applies when creating .so files or executables, not when creating .a or .lo files. So if the linkstatic=True attribute is set, the linkopts attribute has no effect on the creation of this library, only on other targets which depend on this library.

Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname" options are not supported and should never be specified in this attribute.

The .so files produced by cc_library rules are not linked against the libraries that they depend on. If you're trying to create a shared library for use outside of the main repository, e.g. for manual use with dlopen() or LD_PRELOAD, it may be better to use a cc_binary rule with the linkshared=True attribute. See cc_binary.linkshared.

linkstamp

Label; default is None

Simultaneously compiles and links the specified C++ source file into the final binary. This trickery is required to introduce timestamp information into binaries; if we compiled the source file to an object file in the usual way, the timestamp would be incorrect. A linkstamp compilation may not include any particular set of compiler flags and so should not depend on any particular header, compiler option, or other build variable. This option should only be needed in the base package.
linkstatic

Boolean; default is False

For cc_binary and cc_test: link the binary in static mode. For cc_library.link_static: see below.

By default this option is on for cc_binary and off for the rest.

If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static.

There are really three different ways to link an executable:

  • STATIC with fully_static_link feature, in which everything is linked statically; e.g. "gcc -static foo.o libbar.a libbaz.a -lm".
    This mode is enabled by specifying fully_static_link in the features attribute.
  • STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "gcc foo.o libfoo.a libbaz.a -lm".
    This mode is enabled by specifying linkstatic=True.
  • DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "gcc foo.o libfoo.so libbaz.so -lm".
    This mode is enabled by specifying linkstatic=False.

If the linkstatic attribute or fully_static_link in features is used outside of //third_party please include a comment near the rule to explain why.

The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries.

There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area.

local_defines

List of strings; default is []

List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents.
module_interfaces

List of labels; default is []

The list of files are regarded as C++20 Modules Interface.

C++ Standard has no restriction about module interface file extension

  • Clang use cppm
  • GCC can use any source file extension
  • MSVC use ixx

The use is guarded by the flag --experimental_cpp_modules.
strip_include_prefix

String; default is ""

The prefix to strip from the paths of the headers of this rule.

When set, the headers in the hdrs attribute of this rule are accessible at their path with this prefix cut off.

If it's a relative path, it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path.

The prefix in the include_prefix attribute is added after this prefix is stripped.

This attribute is only legal under third_party.

textual_hdrs

List of labels; default is []

The list of header files published by this library to be textually included by sources in dependent rules.

This is the location for declaring header files that cannot be compiled on their own; that is, they always need to be textually included by other source files to build valid code.
win_def_file

Label; default is None

The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.

cc_shared_library

View rule source 
cc_shared_library(name, deps, additional_linker_inputs, compatible_with, deprecation, distribs, dynamic_deps, exec_compatible_with, exec_properties, exports_filter, features, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file)

It produces a shared library.

Example

cc_shared_library(
    name = "foo_shared",
    deps = [
        ":foo",
    ],
    dynamic_deps = [
        ":bar_shared",
    ],
    additional_linker_inputs = [
        ":foo.lds",
    ],
    user_link_flags = [
        "-Wl,--version-script=$(location :foo.lds)",
    ],
)
cc_library(
    name = "foo",
    srcs = ["foo.cc"],
    hdrs = ["foo.h"],
    deps = [
        ":bar",
        ":baz",
    ],
)
cc_shared_library(
    name = "bar_shared",
    shared_lib_name = "bar.so",
    deps = [":bar"],
)
cc_library(
    name = "bar",
    srcs = ["bar.cc"],
    hdrs = ["bar.h"],
)
cc_library(
    name = "baz",
    srcs = ["baz.cc"],
    hdrs = ["baz.h"],
)

In the example foo_shared statically links foo and baz, the latter being a transitive dependency. It doesn't link bar because it is already provided dynamically by the dynamic_dep bar_shared.

foo_shared uses a linker script *.lds file to control which symbols should be exported. The cc_shared_library rule logic does not control which symbols get exported, it only uses what is assumed to be exported to give errors during analysis phase if two shared libraries export the same targets.

Every direct dependency of cc_shared_library is assumed to be exported. Therefore, Bazel assumes during analysis that foo is being exported by foo_shared. baz is not assumed to be exported by foo_shared. Every target matched by the exports_filter is also assumed to be exported.

Every single cc_library in the example should appear at most in one cc_shared_library. If we wanted to link baz also into bar_shared we would need to add tags = ["LINKABLE_MORE_THAN_ONCE"] to baz.

Due to the shared_lib_name attribute, the file produced by bar_shared will have the name bar.so as opposed to the name libbar.so that it would have by default on Linux.

Errors

Two shared libraries in dependencies export the same symbols.

This will happen whenever you are creating a target with two different cc_shared_library dependencies that export the same target. To fix this you need to stop the libraries from being exported in one of the cc_shared_library dependencies.

This will happen whenever you are creating a new cc_shared_library with two different cc_shared_library dependencies that link the same target statically. Similar to the error with exports.

One way to fix this is to stop linking the library into one of the cc_shared_library dependencies. At the same time, the one that still links it needs to export the library so that the one not linking it keeps visibility to the symbols. Another way is to pull out a third library that exports the target. A third way is to tag the culprit cc_library with LINKABLE_MORE_THAN_ONCE but this fix should be rare and you should absolutely make sure that the cc_library is indeed safe to link more than once.

'//foo:foo' is already linked statically in '//bar:bar' but not exported`

This means that a library in the transitive closure of your deps is reachable without going through one of the cc_shared_library dependencies but is already linked into a different cc_shared_library in dynamic_deps and is not exported.

The solution is to export it from the cc_shared_library dependency or pull out a third cc_shared_library that exports it.

Do not place libraries which only contain a precompiled dynamic library in deps.

If you have a precompiled dynamic library, this doesn't need to and cannot be linked statically into the current cc_shared_library target that you are currently creating. Therefore, it doesn't belong in deps of the cc_shared_library. If this precompiled dynamic library is a dependency of one of your cc_libraries, then the cc_library needs to depend on it directly.

Trying to export a library already exported by a different shared library

You will see this error if on the current rule you are claiming to export a target that is already being exported by one of your dynamic dependencies.

To fix this, remove the target from deps and just rely on it from the dynamic dependency or make sure that the exports_filter doesn't catch this target.

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; default is []

Top level libraries that will unconditionally be statically linked into the shared library after being whole-archived.

Any transitive library dependency of these direct deps will be linked into this shared library as long as they have not already been linked by a cc_shared_library in dynamic_deps.

During analysis, the rule implementation will consider any target listed in deps as being exported by the shared library in order to give errors when multiple cc_shared_libraries export the same targets. The rule implementation does not take care of informing the linker about which symbols should be exported by the shared object. The user should take care of this via linker scripts or visibility declarations in the source code.

The implementation will also trigger errors whenever the same library is linked statically into more than one cc_shared_library. This can be avoided by adding "LINKABLE_MORE_THAN_ONCE" to the cc_library.tags or by listing the `cc_library` as an export of one of the shared libraries so that one can be made a dynamic_dep of the other.

additional_linker_inputs

List of labels; default is []

Any additional files that you may want to pass to the linker, for example, linker scripts. You have to separately pass any linker flags that the linker needs in order to be aware of this file. You can do so via the user_link_flags attribute.
dynamic_deps

List of labels; default is []

These are other cc_shared_library dependencies the current target depends on.

The cc_shared_library implementation will use the list of dynamic_deps (transitively, i.e. also the dynamic_deps of the current target's dynamic_deps) to decide which cc_libraries in the transitive deps should not be linked in because they are already provided by a different cc_shared_library.

exports_filter

List of strings; default is []

This attribute contains a list of targets that are claimed to be exported by the current shared library.

Any target deps is already understood to be exported by the shared library. This attribute should be used to list any targets that are exported by the shared library but are transitive dependencies of deps.

Note that this attribute is not actually adding a dependency edge to those targets, the dependency edge should instead be created by deps.The entries in this attribute are just strings. Keep in mind that when placing a target in this attribute, this is considered a claim that the shared library exports the symbols from that target. The cc_shared_library logic doesn't actually handle telling the linker which symbols should be exported.

The following syntax is allowed:

//foo:__pkg__ to account for any target in foo/BUILD

//foo:__subpackages__ to account for any target in foo/BUILD or any other package below foo/ like foo/bar/BUILD
roots

List of labels; default is []
shared_lib_name

String; default is ""

By default cc_shared_library will use a name for the shared library output file based on the target's name and the platform. This includes an extension and sometimes a prefix. Sometimes you may not want the default name, for example, when loading C++ shared libraries for Python the default lib* prefix is often not desired, in which case you can use this attribute to choose a custom name.
static_deps

List of strings; default is []

List of strings; default is []

Any additional flags that you may want to pass to the linker. For example, to make the linker aware of a linker script passed via additional_linker_inputs you can use the following: 

 cc_shared_library(
    name = "foo_shared",
    additional_linker_inputs = select({
      "//src/conditions:linux": [
        ":foo.lds",
        ":additional_script.txt",
      ],
      "//conditions:default": []}),
    user_link_flags = select({
      "//src/conditions:linux": [
        "-Wl,-rpath,kittens",
        "-Wl,--version-script=$(location :foo.lds)",
        "-Wl,--script=$(location :additional_script.txt)",
      ],
      "//conditions:default": []}),
      ...
 )
win_def_file

Label; default is None

The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.

cc_static_library

View rule source 
cc_static_library(name, deps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)
 This rule is currently experimental and can only be used with the --experimental_cc_static_library flag. Produces a static library from a list of targets and their transitive dependencies.

The resulting static library contains the object files of the targets listed in deps as well as their transitive dependencies, with preference given to PIC objects.

Output groups

linkdeps

A text file containing the labels of those transitive dependencies of targets listed in deps that did not contribute any object files to the static library, but do provide at least one static, dynamic or interface library. The resulting static library may require these libraries to be available at link time.

linkopts

A text file containing the user-provided linkopts of all transitive dependencies of targets listed in deps.

Duplicate symbols

By default, the cc_static_library rule checks that the resulting static library does not contain any duplicate symbols. If it does, the build fails with an error message that lists the duplicate symbols and the object files containing them.

This check can be disabled per target or per package by setting features = ["-symbol_check"] or globally via --features=-symbol_check.

Toolchain support for symbol_check

The auto-configured C++ toolchains shipped with Bazel support the symbol_check feature on all platforms. Custom toolchains can add support for it in one of two ways:

  • Implementing the ACTION_NAMES.validate_static_library action and enabling it with the symbol_check feature. The tool set in the action is invoked with two arguments, the static library to check for duplicate symbols and the path of a file that must be created if the check passes.
  • Having the symbol_check feature add archiver flags that cause the action creating the static library to fail on duplicate symbols.

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; default is []

The list of targets to combine into a static library, including all their transitive dependencies.

Dependencies that do not provide any object files are not included in the static library, but their labels are collected in the file provided by the linkdeps output group.

cc_test

View rule source 
cc_test(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, malloc, module_interfaces, nocopts, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file)

A cc_test() rule compiles a test. Here, a test is a binary wrapper around some testing code.

By default, C++ tests are dynamically linked.
To statically link a unit test, specify linkstatic=True. It would probably be good to comment why your test needs linkstatic; this is probably not obvious.

Implicit output targets

  • name.stripped (only built if explicitly requested): A stripped version of the binary. strip -g is run on the binary to remove debug symbols. Additional strip options can be provided on the command line using --stripopt=-foo.
  • name.dwp (only built if explicitly requested): If Fission is enabled: a debug information package file suitable for debugging remotely deployed binaries. Else: an empty file.

See the cc_binary() arguments, except that the stamp argument is set to 0 by default for tests and that cc_test has extra attributes common to all test rules (*_test).

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; default is []

The list of other libraries to be linked in to the binary target.

These can be cc_library or objc_library targets.

It is also allowed to put linker scripts (.lds) into deps, and reference them in linkopts.
srcs

List of labels; default is []

The list of C and C++ files that are processed to create the library target. These are C/C++ source and header files, either non-generated (normal source code) or generated.

All .cc, .c, and .cpp files will be compiled. These might be generated files: if a named file is in the outs of some other rule, this cc_library will automatically depend on that other rule.

Pure assembler files (.s, .asm) are not preprocessed and are typically built using the assembler. Preprocessed assembly files (.S) are preprocessed and are typically built using the C/C++ compiler.

A .h file will not be compiled, but will be available for inclusion by sources in this rule. Both .cc and .h files can directly include headers listed in these srcs or in the hdrs of this rule or any rule listed in the deps argument.

All #included files must be mentioned in the hdrs attribute of this or referenced cc_library rules, or they should be listed in srcs if they are private to this library. See "Header inclusion checking" for a more detailed description.

.so, .lo, and .a files are pre-compiled files. Your library might have these as srcs if it uses third-party code for which we don't have source code.

If the srcs attribute includes the label of another rule, cc_library will use the output files of that rule as source files to compile. This is useful for one-off generation of source code (for more than occasional use, it's better to implement a Starlark rule class and use the cc_common API)

Permitted srcs file types:

  • C and C++ source files: .c, .cc, .cpp, .cxx, .c++, .C
  • C and C++ header files: .h, .hh, .hpp, .hxx, .inc, .inl, .H
  • Assembler with C preprocessor: .S
  • Archive: .a, .pic.a
  • "Always link" library: .lo, .pic.lo
  • Shared library, versioned or unversioned: .so, .so.version
  • Object file: .o, .pic.o

... and any rules that produce those files (e.g. cc_embed_data). Different extensions denote different programming languages in accordance with gcc convention.

data

List of labels; default is []

The list of files needed by this library at runtime. See general comments about data at Typical attributes defined by most build rules.

If a data is the name of a generated file, then this cc_library rule automatically depends on the generating rule.

If a data is a rule name, then this cc_library rule automatically depends on that rule, and that rule's outs are automatically added to this cc_library's data files.

Your C++ code can access these data files like so:


  const std::string path = devtools_build::GetDataDependencyFilepath(
      "my/test/data/file");
additional_linker_inputs

List of labels; default is []

Pass these files to the C++ linker command.

For example, compiled Windows .res files can be provided here to be embedded in the binary target.

conlyopts

List of strings; default is []

Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.
copts

List of strings; default is []

Add these options to the C/C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.

Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. This attribute should not be needed outside of third_party.

If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.

cxxopts

List of strings; default is []

Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.
defines

List of strings; default is []

List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead.
dynamic_deps

List of labels; default is []

These are other cc_shared_library dependencies the current target depends on.

The cc_shared_library implementation will use the list of dynamic_deps (transitively, i.e. also the dynamic_deps of the current target's dynamic_deps) to decide which cc_libraries in the transitive deps should not be linked in because they are already provided by a different cc_shared_library.

hdrs_check

String; default is ""

Deprecated, no-op.
includes

List of strings; default is []

List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with the package path and passed to the C++ toolchain for expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system with typical feature definitions will produce -isystem path_to_package/include_entry. This should only be used for third-party libraries that do not conform to the Google style of writing #include statements. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead.

The added include paths will include generated files as well as files in the source tree.

Label; default is "@bazel_tools//tools/cpp:link_extra_lib"

Control linking of extra libraries.

By default, C++ binaries are linked against //tools/cpp:link_extra_lib, which by default depends on the label flag //tools/cpp:link_extra_libs. Without setting the flag, this library is empty by default. Setting the label flag allows linking optional dependencies, such as overrides for weak symbols, interceptors for shared library functions, or special runtime libraries (for malloc replacements, prefer malloc or --custom_malloc). Setting this attribute to None disables this behaviour.

linkopts

List of strings; default is []

Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target.

Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps.

linkshared

Boolean; default is False

Create a shared library. To enable this attribute, include linkshared=True in your rule. By default this option is off.

The presence of this flag means that linking occurs with the -shared flag to gcc, and the resulting shared library is suitable for loading into for example a Java program. However, for build purposes it will never be linked into the dependent binary, as it is assumed that shared libraries built with a cc_binary rule are only loaded manually by other programs, so it should not be considered a substitute for the cc_library rule. For sake of scalability we recommend avoiding this approach altogether and simply letting java_library depend on cc_library rules instead.

If you specify both linkopts=['-static'] and linkshared=True, you get a single completely self-contained unit. If you specify both linkstatic=True and linkshared=True, you get a single, mostly self-contained unit.

linkstatic

Boolean; default is False

For cc_binary and cc_test: link the binary in static mode. For cc_library.link_static: see below.

By default this option is on for cc_binary and off for the rest.

If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static.

There are really three different ways to link an executable:

  • STATIC with fully_static_link feature, in which everything is linked statically; e.g. "gcc -static foo.o libbar.a libbaz.a -lm".
    This mode is enabled by specifying fully_static_link in the features attribute.
  • STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "gcc foo.o libfoo.a libbaz.a -lm".
    This mode is enabled by specifying linkstatic=True.
  • DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "gcc foo.o libfoo.so libbaz.so -lm".
    This mode is enabled by specifying linkstatic=False.

If the linkstatic attribute or fully_static_link in features is used outside of //third_party please include a comment near the rule to explain why.

The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries.

There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area.

local_defines

List of strings; default is []

List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents.
malloc

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

Override the default dependency on malloc.

By default, C++ binaries are linked against //tools/cpp:malloc, which is an empty library so the binary ends up using libc malloc. This label must refer to a cc_library. If compilation is for a non-C++ rule, this option has no effect. The value of this attribute is ignored if linkshared=True is specified.

module_interfaces

List of labels; default is []

The list of files are regarded as C++20 Modules Interface.

C++ Standard has no restriction about module interface file extension

  • Clang use cppm
  • GCC can use any source file extension
  • MSVC use ixx

The use is guarded by the flag --experimental_cpp_modules.
nocopts

String; default is ""

Remove matching options from the C++ compilation command. Subject to "Make" variable substitution. The value of this attribute is interpreted as a regular expression. Any preexisting COPTS that match this regular expression (including values explicitly specified in the rule's copts attribute) will be removed from COPTS for purposes of compiling this rule. This attribute should not be needed or used outside of third_party. The values are not preprocessed in any way other than the "Make" variable substitution.
reexport_deps

List of labels; default is []
stamp

Integer; default is 0

Whether to encode build information into the binary. Possible values:
  • stamp = 1: Always stamp the build information into the binary, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the binary and any downstream actions that depend on it.
  • stamp = 0: Always replace build information by constant values. This gives good build result caching.
  • stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.

Stamped binaries are not rebuilt unless their dependencies change.
win_def_file

Label; default is None

The Windows DEF file to be passed to linker.

This attribute should only be used when Windows is the target platform. It can be used to export symbols during linking a shared library.

cc_toolchain

View rule source 
cc_toolchain(name, all_files, ar_files, as_files, compatible_with, compiler_files, compiler_files_without_includes, coverage_files, deprecation, distribs, dwp_files, dynamic_runtime_lib, exec_compatible_with, exec_properties, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, output_licenses, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, toolchains, visibility)

Represents a C++ toolchain.

This rule is responsible for:

  • Collecting all artifacts needed for C++ actions to run. This is done by attributes such as all_files, compiler_files, linker_files, or other attributes ending with _files). These are most commonly filegroups globbing all required files.
  • Generating correct command lines for C++ actions. This is done using CcToolchainConfigInfo provider (details below).

Use toolchain_config attribute to configure the C++ toolchain. See also this page for elaborate C++ toolchain configuration and toolchain selection documentation.

Use tags = ["manual"] in order to prevent toolchains from being built and configured unnecessarily when invoking bazel build //...

Arguments

Attributes
name

Name; required

A unique name for this target.
all_files

Label; required

Collection of all cc_toolchain artifacts. These artifacts will be added as inputs to all rules_cc related actions (with the exception of actions that are using more precise sets of artifacts from attributes below). Bazel assumes that all_files is a superset of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile and link files, so it takes all_files).

This is what cc_toolchain.files contains, and this is used by all Starlark rules using C++ toolchain.
ar_files

Label; default is None

Collection of all cc_toolchain artifacts required for archiving actions.
as_files

Label; default is None

Collection of all cc_toolchain artifacts required for assembly actions.
compiler_files

Label; required

Collection of all cc_toolchain artifacts required for compile actions.
compiler_files_without_includes

Label; default is None

Collection of all cc_toolchain artifacts required for compile actions in case when input discovery is supported (currently Google-only).
coverage_files

Label; default is None

Collection of all cc_toolchain artifacts required for coverage actions. If not specified, all_files are used.
dwp_files

Label; required

Collection of all cc_toolchain artifacts required for dwp actions.
dynamic_runtime_lib

Label; default is None

Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so).

This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies dynamically.
exec_transition_for_inputs

Boolean; default is False

Deprecated. No-op.
libc_top

Label; default is None

A collection of artifacts for libc passed as inputs to compile/linking actions.
linker_files

Label; required

Collection of all cc_toolchain artifacts required for linking actions.
module_map

Label; default is None

Module map artifact to be used for modular builds.
objcopy_files

Label; required

Collection of all cc_toolchain artifacts required for objcopy actions.
output_licenses

List of strings; default is []
static_runtime_lib

Label; default is None

Static library artifact for the C++ runtime library (e.g. libstdc++.a).

This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies statically.
strip_files

Label; required

Collection of all cc_toolchain artifacts required for strip actions.
supports_header_parsing

Boolean; default is False

Set to True when cc_toolchain supports header parsing actions.
supports_param_files

Boolean; default is True

Set to True when cc_toolchain supports using param files for linking actions.
toolchain_config

Label; required

The label of the rule providing cc_toolchain_config_info.
toolchain_identifier

String; default is ""

The identifier used to match this cc_toolchain with the corresponding crosstool_config.toolchain.

Until issue #5380 is fixed this is the recommended way of associating cc_toolchain with CROSSTOOL.toolchain. It will be replaced by the toolchain_config attribute (#5380).

cc_toolchain_suite

View rule source 
cc_toolchain_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

Deprecated: the rule is a no-op and will be removed.

Arguments

Attributes
name

Name; required

A unique name for this target.

fdo_prefetch_hints

View rule source 
fdo_prefetch_hints(name, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

Represents an FDO prefetch hints profile that is either in the workspace. Examples:


fdo_prefetch_hints(
    name = "hints",
    profile = "//path/to/hints:profile.afdo",
)

Arguments

Attributes
name

Name; required

A unique name for this target.
profile

Label; required

Label of the hints profile. The hints file has the .afdo extension The label can also point to an fdo_absolute_path_profile rule.

fdo_profile

View rule source 
fdo_profile(name, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, memprof_profile, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

Represents an FDO profile that is in the workspace. Example:


fdo_profile(
    name = "fdo",
    profile = "//path/to/fdo:profile.zip",
)

Arguments

Attributes
name

Name; required

A unique name for this target.
memprof_profile

Label; default is None

Label of the MemProf profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file.
profile

Label; required

Label of the FDO profile or a rule which generates it. The FDO file can have one of the following extensions: .profraw for unindexed LLVM profile, .profdata for indexed LLVM profile, .zip that holds an LLVM profraw profile, .afdo for AutoFDO profile, .xfdo for XBinary profile. The label can also point to an fdo_absolute_path_profile rule.
proto_profile

Label; default is None

Label of the protobuf profile.

memprof_profile

View rule source 
memprof_profile(name, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

Represents a MEMPROF profile that is in the workspace. Example:


memprof_profile(
    name = "memprof",
    profile = "//path/to/memprof:profile.afdo",
)

Arguments

Attributes
name

Name; required

A unique name for this target.
profile

Label; required

Label of the MEMPROF profile. The profile is expected to have either a .profdata extension (for an indexed/symbolized memprof profile), or a .zip extension for a zipfile containing a memprof.profdata file. The label can also point to an fdo_absolute_path_profile rule.

propeller_optimize

View rule source 
propeller_optimize(name, cc_profile, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, ld_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

Represents a Propeller optimization profile in the workspace. Example:


propeller_optimize(
    name = "layout",
    cc_profile = "//path:cc_profile.txt",
    ld_profile = "//path:ld_profile.txt"
)

Arguments

Attributes
name

Name; required

A unique name for this target.
cc_profile

Label; required

Label of the profile passed to the various compile actions. This file has the .txt extension.
ld_profile

Label; required

Label of the profile passed to the link action. This file has the .txt extension.