C / C++ Rules
Rules
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 |
A unique name for this target. |
deps
|
These can be |
srcs
|
All A All If a rule's name is in the
Permitted
...and any rules that produce those files. Different extensions denote different programming languages in accordance with gcc convention. |
copts
|
Each string in this attribute is added in the given order to
If the package declares the feature
|
defines
|
-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
|
Subject to "Make variable" substitution.
Each string is prepended with Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default). |
linkopts
|
LINKOPTS before
linking the binary target.
Each element of this list that does not start with |
linkshared
|
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
If you specify both |
linkstatic
|
cc_binary and
cc_test : link the binary in static
mode. For cc_library.linkstatic : see below.
By default this option is on for
If enabled and this is a binary or test, this option tells the build tool to link in
There are really three different ways to link an executable:
The
If |
malloc
|
By default, C++ binaries are linked against |
nocopts
|
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
|
|
toolchains
|
|
win_def_file
|
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 |
A unique name for this target. |
hdrs
|
|
alwayslink
|
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
|
Permitted file types:
|
shared_library
|
Permitted file types:
|
static_library
|
Permitted file types:
|
system_provided
|
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 |
A unique name for this target. |
deps
|
These can be |
srcs
|
All A All If a rule's name is in the
Permitted
...and any rules that produce those files. Different extensions denote different programming languages in accordance with gcc convention. |
hdrs
|
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 |
alwayslink
|
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
|
Each string in this attribute is added in the given order to
If the package declares the feature
|
defines
|
-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
|
When set, the headers in the The prefix in the |
includes
|
Subject to "Make variable" substitution.
Each string is prepended with Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default). |
linkopts
|
LINKOPTS before
linking the binary target.
Each element of this list that does not start with |
linkstatic
|
cc_binary and
cc_test : link the binary in static
mode. For cc_library.linkstatic : see below.
By default this option is on for
If enabled and this is a binary or test, this option tells the build tool to link in
There are really three different ways to link an executable:
The
If |
nocopts
|
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
|
When set, the headers in the 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 |
textual_hdrs
|
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
|
|
win_def_file
|
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 |
A unique name for this target. |
deps
|
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 |
A unique name for this target. |
profile
|
|
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 |
A unique name for this target. |
absolute_path_profile
|
|
profile
|
|
proto_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 |
A unique name for this target. |
deps
|
These can be |
srcs
|
All A All If a rule's name is in the
Permitted
...and any rules that produce those files. Different extensions denote different programming languages in accordance with gcc convention. |
copts
|
Each string in this attribute is added in the given order to
If the package declares the feature
|
defines
|
-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
|
Subject to "Make variable" substitution.
Each string is prepended with Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default). |
linkopts
|
LINKOPTS before
linking the binary target.
Each element of this list that does not start with |
linkstatic
|
cc_binary and
cc_test : link the binary in static
mode. For cc_library.linkstatic : see below.
By default this option is on for
If enabled and this is a binary or test, this option tells the build tool to link in
There are really three different ways to link an executable:
The
If |
malloc
|
By default, C++ binaries are linked against |
nocopts
|
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
|
|
toolchains
|
|
win_def_file
|
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, features, libc_top, licenses, linker_files, module_map, objcopy_files, proto, restricted_to, static_runtime_lib, 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 |
A unique name for this target. |
all_files
|
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 |
as_files
|
Collection of all cc_toolchain artifacts required for assembly actions. |
compiler
|
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
|
Currently only used by lto_backend actions, regular compile actions use all_files (#6927). |
compiler_files_without_includes
|
|
coverage_files
|
|
cpu
|
When set, it will be used to perform crosstool_config.toolchain selection. It will take precedence over --cpu Bazel option. |
dwp_files
|
|
dynamic_runtime_lib
|
This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies dynamically. |
libc_top
|
|
linker_files
|
Currently also used for archiving actions (#6928). |
module_map
|
|
objcopy_files
|
|
proto
|
|
static_runtime_lib
|
This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking dependencies statically. |
strip_files
|
|
supports_header_parsing
|
|
supports_param_files
|
|
toolchain_config
|
cc_toolchain_config_info . When specified,
cc_toolchain will not use the CROSSTOOL file at all.
|
toolchain_identifier
|
Until issue #5380 is fixed
this is the recommended way of associating |
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 |
A unique name for this target. |
proto
|
|
toolchains
|
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", }, ) |