C / C++ Rules

Rules

cc_binary
cc_import
cc_library
cc_proto_library
fdo_prefetch_hints
fdo_profile
cc_test
cc_toolchain
cc_toolchain_suite

cc_binary

cc_binary(name, deps, srcs, data, args, compatible_with, copts, defines, deprecation, distribs, features, includes, licenses, linkopts, linkshared, linkstatic, malloc, nocopts, output_licenses, restricted_to, stamp, tags, testonly, toolchains, visibility, win_def_file)

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. This output is only built if explicitly requested.
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; optional` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets.
`srcs`	`List of labels; optional` The list of C and C++ files that are processed to create the 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 rule will automatically depend on that other rule. 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 any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `srcs` attribute of this rule, or in the `hdrs` attribute of referenced `cc_library()`s. The recommended style is for headers associated with a library to be listed in that library's `hdrs` attribute, and any remaining headers associated with this rule's sources to be listed in `srcs`. See "Header inclusion checking" for a more detailed description. If a rule's name is in the `srcs`, then this rule automatically depends on that one. If the named rule's `outs` are C or C++ source files, they are compiled into this rule; if they are library files, they are linked in. 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. Different extensions denote different programming languages in accordance with gcc convention.
`copts`	`List of strings; optional` Add these options to the 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. If the package declares the feature `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.
`defines`	`List of strings; optional` 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` (or `/D` on Windows) and added to `COPTS`. Unlike `copts`, these flags are added for the target and every rule that depends on it! Be very careful, since this may have far-reaching effects. When in doubt, add "-D" (or `/D` on Windows) flags to `copts` instead.
`includes`	`List of strings; optional` List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with `-isystem` and added to `COPTS`. 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. Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).
`linkopts`	`List of strings; optional` 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; optional; nonconfigurable; default is False` Create a shared library. To enable this attribute, include `linkshared=True` in your rule. By default this option is off. If you enable it, you must name your binary `libfoo.so` (or whatever is the naming convention of libraries on the target platform) for some sensible value of foo. 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=1` and `linkshared=True`, you get a single, mostly self-contained unit.
`linkstatic`	`Boolean; optional; default is True` For `cc_binary` and `cc_test`: link the binary in static mode. For `cc_library.linkstatic`: 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. Some system libraries may still be 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`. 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. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area.
`malloc`	`Label; optional; 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.
`nocopts`	`String; optional` 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 rarely be needed.
`stamp`	`Integer; optional; default is -1` Enable link stamping. Whether to encode build information into the binary. Possible values: `stamp = 1`: Stamp the build information into the binary. Stamped binaries are only rebuilt when their dependencies change. Use this if there are tests that depend on the build information. `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.
`toolchains`	`List of labels; optional` The set of toolchains that supply "Make variables" that this target can use in some of its attributes. Some rules have toolchains whose Make variables they can use by default.
`win_def_file`	`Label; optional` 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

cc_import(name, data, hdrs, alwayslink, compatible_with, deprecation, distribs, features, interface_library, licenses, restricted_to, shared_library, static_library, system_provided, tags, testonly, 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 = 1,
)

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 (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. Linking a shared library with 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. Linking to static or shared library
On 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,
)

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

# 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,
)

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`hdrs`	`List of labels; optional` The list of header files published by this precompiled library to be directly included by sources in dependent rules.
`alwayslink`	`Boolean; optional; 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](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version.
`interface_library`	`Label; optional` A single interface library for linking the shared library. Permitted file types: `.ifso`, `.tbd`, `.lib`, `.so` or `.dylib`
`shared_library`	`Label; optional` 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; optional` A single precompiled static library. Permitted file types: `.a`, `.pic.a` or `.lib`
`system_provided`	`Boolean; optional; 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

cc_library(name, deps, srcs, data, hdrs, alwayslink, compatible_with, copts, defines, deprecation, distribs, features, include_prefix, includes, licenses, linkopts, linkstatic, nocopts, restricted_to, strip_include_prefix, tags, testonly, textual_hdrs, toolchains, visibility, win_def_file)

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 file	Allowed inclusions
foo.h	bar.h
foo.cc	foo.h bar.h
bar.h	bar-impl.h baz.h
bar-impl.h	bar.h baz.h
bar.cc	bar.h bar-impl.h baz.h
baz.h	baz-impl.h
baz-impl.h	baz.h
baz.cc	baz.h baz-impl.h

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.

Unfortunately Bazel currently cannot distinguish between direct and transitive inclusions, so it cannot detect error cases where a file illegally includes a header directly that is only allowed to be included transitively. For example, Bazel would not complain if in the example above foo.cc directly includes baz.h. This would be illegal, because foo does not directly depend on baz. Currently, no error is produced in that case, but such error checking may be added in the future.

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`deps`	`List of labels; optional` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets.
`srcs`	`List of labels; optional` The list of C and C++ files that are processed to create the 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 rule will automatically depend on that other rule. 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 any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `srcs` attribute of this rule, or in the `hdrs` attribute of referenced `cc_library()`s. The recommended style is for headers associated with a library to be listed in that library's `hdrs` attribute, and any remaining headers associated with this rule's sources to be listed in `srcs`. See "Header inclusion checking" for a more detailed description. If a rule's name is in the `srcs`, then this rule automatically depends on that one. If the named rule's `outs` are C or C++ source files, they are compiled into this rule; if they are library files, they are linked in. 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. Different extensions denote different programming languages in accordance with gcc convention.
`hdrs`	`List of labels; optional` 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.
`alwayslink`	`Boolean; optional; 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](https://github.com/bazelbuild/bazel/issues/3949), please upgrade your VS 2017 to the latest version.
`copts`	`List of strings; optional` Add these options to the 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. If the package declares the feature `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.
`defines`	`List of strings; optional` 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` (or `/D` on Windows) and added to `COPTS`. Unlike `copts`, these flags are added for the target and every rule that depends on it! Be very careful, since this may have far-reaching effects. When in doubt, add "-D" (or `/D` on Windows) flags to `copts` instead.
`include_prefix`	`String; optional` 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.
`includes`	`List of strings; optional` List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with `-isystem` and added to `COPTS`. 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. Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).
`linkopts`	`List of strings; optional` 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`.
`linkstatic`	`Boolean; optional; default is False` For `cc_binary` and `cc_test`: link the binary in static mode. For `cc_library.linkstatic`: 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. Some system libraries may still be 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`. 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. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area.
`nocopts`	`String; optional` 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 rarely be needed.
`strip_include_prefix`	`String; optional` 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.
`textual_hdrs`	`List of labels; optional` 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.
`toolchains`	`List of labels; optional` The set of toolchains that supply "Make variables" that this target can use in some of its attributes. Some rules have toolchains whose Make variables they can use by default.
`win_def_file`	`Label; optional` 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_proto_library

cc_proto_library(name, deps, data, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, testonly, visibility)

cc_proto_library generates C++ code from .proto files.

deps must point to proto_library rules.

Example:

cc_library(
    name = "lib",
    deps = [":foo_cc_proto"],
)

cc_proto_library(
    name = "foo_cc_proto",
    deps = [":foo_proto"],
)

proto_library(
    name = "foo_proto",
)

Arguments

Attributes

name

Name; required

A unique name for this target.

deps

List of labels; optional

The list of proto_library rules to generate C++ code for.

fdo_prefetch_hints

fdo_prefetch_hints(name, compatible_with, deprecation, distribs, features, licenses, profile, restricted_to, tags, testonly, visibility)

Represents an FDO prefetch hints profile that is either in the workspace or at a specified absolute path. Examples:

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

fdo_profile(
  name = "hints_abs",
  absolute_path_profile = "/absolute/path/profile.afdo",
)

Arguments

Attributes

name

Name; required

A unique name for this target.

profile

Label; optional

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

fdo_profile(name, absolute_path_profile, compatible_with, deprecation, distribs, features, licenses, profile, proto_profile, restricted_to, tags, testonly, visibility)

Represents an FDO profile that is either in the workspace or at a specified absolute path. Examples:

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

fdo_profile(
  name = "fdo_abs",
  absolute_path_profile = "/absolute/path/profile.zip",
)

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`absolute_path_profile`	`String; optional` Absolute path to the FDO profile. 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, or .afdo for AutoFDO profile.
`profile`	`Label; optional` Label of the FDO profile. 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; optional` Label of the protobuf profile.

cc_test

cc_test(name, deps, srcs, data, args, compatible_with, copts, defines, deprecation, distribs, exec_compatible_with, features, flaky, includes, licenses, linkopts, linkstatic, local, malloc, nocopts, restricted_to, shard_count, size, stamp, tags, testonly, timeout, toolchains, visibility, win_def_file)

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`deps`	`List of labels; optional` The list of other libraries to be linked in to the binary target. These can be `cc_library` or `objc_library` targets.
`srcs`	`List of labels; optional` The list of C and C++ files that are processed to create the 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 rule will automatically depend on that other rule. 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 any rule listed in the `deps` argument. All `#include`d files must be mentioned in the `srcs` attribute of this rule, or in the `hdrs` attribute of referenced `cc_library()`s. The recommended style is for headers associated with a library to be listed in that library's `hdrs` attribute, and any remaining headers associated with this rule's sources to be listed in `srcs`. See "Header inclusion checking" for a more detailed description. If a rule's name is in the `srcs`, then this rule automatically depends on that one. If the named rule's `outs` are C or C++ source files, they are compiled into this rule; if they are library files, they are linked in. 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. Different extensions denote different programming languages in accordance with gcc convention.
`copts`	`List of strings; optional` Add these options to the 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. If the package declares the feature `no_copts_tokenization`, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.
`defines`	`List of strings; optional` 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` (or `/D` on Windows) and added to `COPTS`. Unlike `copts`, these flags are added for the target and every rule that depends on it! Be very careful, since this may have far-reaching effects. When in doubt, add "-D" (or `/D` on Windows) flags to `copts` instead.
`includes`	`List of strings; optional` List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with `-isystem` and added to `COPTS`. 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. Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).
`linkopts`	`List of strings; optional` 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`.
`linkstatic`	`Boolean; optional; default is False` For `cc_binary` and `cc_test`: link the binary in static mode. For `cc_library.linkstatic`: 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. Some system libraries may still be 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`. 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. If `linkstatic=False`, then the build tool will create symlinks to depended-upon shared libraries in the `*.runfiles` area.
`malloc`	`Label; optional; 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.
`nocopts`	`String; optional` 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 rarely be needed.
`stamp`	`Integer; optional; default is 0` Enable link stamping. Whether to encode build information into the binary. Possible values: `stamp = 1`: Stamp the build information into the binary. Stamped binaries are only rebuilt when their dependencies change. Use this if there are tests that depend on the build information. `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.
`toolchains`	`List of labels; optional` The set of toolchains that supply "Make variables" that this target can use in some of its attributes. Some rules have toolchains whose Make variables they can use by default.
`win_def_file`	`Label; optional` 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

cc_toolchain(name, all_files, as_files, compatible_with, compiler, compiler_files, compiler_files_without_includes, coverage_files, cpu, deprecation, distribs, dwp_files, dynamic_runtime_lib, dynamic_runtime_libs, features, libc_top, licenses, linker_files, module_map, objcopy_files, proto, restricted_to, static_runtime_lib, static_runtime_libs, strip_files, supports_header_parsing, supports_param_files, tags, testonly, toolchain_config, toolchain_identifier, 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 CROSSTOOL, or using CcToolchainConfigInfo provider (details below).

When using CROSSTOOL to configure command line generation, use toolchain_identifier attribute to match current cc_toolchain with the corresponding CROSSTOOL.toolchain. See also this page for elaborate CROSSTOOL documentation.

When using CcToolchainConfigInfo provider to configure command line generation, use toolchain_config attribute to point to a rule that provides CcToolchainConfigInfo. This will be the preferred way of configuring command line generation once the issue #5380 is fixed.

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.
`as_files`	`Label; optional` Currently unused (#6928). Collection of all cc_toolchain artifacts required for assembly actions.
`compiler`	`String; optional; nonconfigurable` Deprecated. Use `toolchain_identifier` attribute instead. It will be a noop after CROSSTOOL migration to Starlark , and will be removed by #7075. When set, it will be used to perform crosstool_config.toolchain selection. It will take precedence over --cpu Bazel option.
`compiler_files`	`Label; required` Collection of all cc_toolchain artifacts required for compile actions. Currently only used by lto_backend actions, regular compile actions use all_files (#6927).
`compiler_files_without_includes`	`Label; optional` Collection of all cc_toolchain artifacts required for compile actions in case when input discovery is supported (currently Google-only).
`coverage_files`	`Label; optional` Collection of all cc_toolchain artifacts required for coverage actions. If not specified, all_files are used.
`cpu`	`String; optional; nonconfigurable` Deprecated. Use toolchain_identifier attribute instead. It will be a noop after CROSSTOOL migration to Starlark , and will be removed by #7075. When set, it will be used to perform crosstool_config.toolchain selection. It will take precedence over --cpu Bazel option.
`dwp_files`	`Label; required` Collection of all cc_toolchain artifacts required for dwp actions.
`dynamic_runtime_lib`	`Label; optional` Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so). When specified, this will take precedence over 'dynamic_runtime_libs'. This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies dynamically.
`dynamic_runtime_libs`	`List of labels; optional` Deprecated, use `dynamic_runtime_lib` (see #6942). A collection of artifacts for dynamic libraries for the C++ runtime library (e.g. libstdc++.so). cc_toolchain will select one of these libraries based on the label from crosstool_proto.dynamic_runtimes_filegroup field. This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies dynamically.
`libc_top`	`Label; optional` 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. Currently also used for archiving actions (#6928).
`module_map`	`Label; optional` Module map artifact to be used for modular builds.
`objcopy_files`	`Label; required` Collection of all cc_toolchain artifacts required for objcopy actions.
`proto`	`String; optional` Deprecated, will be removed as part of CROSSTOOL migration to Starlark . Inline content of the crosstool_config.toolchain. When specified, it will take precedence over the CROSSTOOL file.
`static_runtime_lib`	`Label; optional` Static library artifact for the C++ runtime library (e.g. libstdc++.a). When specified, this will take precedence over 'static_runtime_libs'. This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies statically.
`static_runtime_libs`	`List of labels; optional` Deprecated, use `static_runtime_lib` (see #6942). A collection of artifacts for static libraries for the C++ runtime library (e.g. libstdc++.a). cc_toolchain will select one of these libraries based on the label from crosstool_proto.static_runtimes_filegroup field. 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; optional; default is False` Set to True when cc_toolchain supports header parsing actions.
`supports_param_files`	`Boolean; optional; default is True` Set to True when cc_toolchain supports using param files for linking actions.
`toolchain_config`	`Label; optional` The label of the rule providing `cc_toolchain_config_info`. When specified, cc_toolchain will not use the CROSSTOOL file at all.
`toolchain_identifier`	`String; optional; nonconfigurable` 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

cc_toolchain_suite(name, compatible_with, deprecation, distribs, features, licenses, proto, restricted_to, tags, testonly, toolchains, visibility)

Represents a collections of C++ toolchains.

This rule is responsible for:

Collecting all relevant C++ toolchains.
Selecting one toolchain depending on --cpu and --compiler options passed to Bazel.

See also this page for elaborate CROSSTOOL and toolchain selection documentation.

Arguments

Attributes

name

Name; required

A unique name for this target.

proto

String; optional; nonconfigurable

Deprecated, will be removed as part of CROSSTOOL migration to Starlark . Allows passing the content of the CROSSTOOL directly into the BUILD file. Only used for testing.

toolchains

Dictionary mapping strings to labels; required; nonconfigurable

A map from "<cpu>" or "<cpu>|<compiler>" strings to a cc_toolchain label. "<cpu>" will be used when only --cpu is passed to Bazel, and "<cpu>|<compiler>" will be used when both --cpu and --compiler are passed to Bazel. Example:

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