Rules
- cc_binary
- cc_import
- cc_library
- cc_shared_library
- cc_static_library
- cc_test
- cc_toolchain
- cc_toolchain_suite
- fdo_prefetch_hints
- fdo_profile
- memprof_profile
- propeller_optimize
cc_binary
View rule sourcecc_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 These can be |
srcs
|
List of labels; default is All 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 All
If the
Permitted
... and any rules that produce those files (e.g. |
data
|
List of labels; default is data
at Typical attributes defined by
most build rules.
If a If a Your C++ code can access these data files like so:
|
additional_linker_inputs
|
List of labels; default is For example, compiled Windows .res files can be provided here to be embedded in the binary target. |
conlyopts
|
List of strings; default is |
copts
|
List of strings; default is
Each string in this attribute is added in the given order to
If the package declares the feature
|
cxxopts
|
List of strings; default is |
defines
|
List of strings; default is -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 cc_shared_library dependencies the current target depends on.
The |
hdrs_check
|
String; default is |
includes
|
List of strings; default is -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 |
link_extra_lib
|
Label; default is
By default, C++ binaries are linked against |
linkopts
|
List of strings; default is LINKOPTS before
linking the binary target.
Each element of this list that does not start with |
linkshared
|
Boolean; default is linkshared=True in your rule. By default
this option is off.
The presence of this flag means that linking occurs with the
If you specify both |
linkstatic
|
Boolean; default is 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
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:
If the
The
There should be very little code built with |
local_defines
|
List of strings; default is -D and added to the compile command line for this target,
but not to its dependents.
|
malloc
|
Label; default is
By default, C++ binaries are linked against |
module_interfaces
|
List of labels; default is C++ Standard has no restriction about module interface file extension
The use is guarded by the flag
|
nocopts
|
String; default is 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
Stamped binaries are not rebuilt unless their dependencies change. |
win_def_file
|
Label; default is 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 sourcecc_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 = 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
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 = 1,
)
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 = 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",
)
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 = 1, # default value
)
# second will link to libmylib.so (or libmylib.lib)
cc_binary(
name = "second",
srcs = ["second.cc"],
deps = [":mylib"],
linkstatic = 0,
)
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 deps
at Typical attributes defined by
most build rules.
|
hdrs
|
List of labels; default is |
alwayslink
|
Boolean; default is 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 -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 |
interface_library
|
Label; default is Permitted file types:
|
linkopts
|
List of strings; default is LINKOPTS before
linking the binary target.
Each element of this list that does not start with |
objects
|
List of labels; default is |
pic_objects
|
List of labels; default is |
pic_static_library
|
Label; default is |
shared_library
|
Label; default is Permitted file types:
|
static_library
|
Label; default is Permitted file types:
|
system_provided
|
Boolean; default is interface_library should be specified and
shared_library should be empty.
|
cc_library
View rule sourcecc_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 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
.
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
We use the alwayslink
flag to force the linker to link in
this code although the main binary code doesn't reference it.
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 These can be See general comments about 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 Despite the "deps" name, not all of this library's clients
belong here. Run-time data dependencies belong in To link in a pre-compiled third-party library, add its name to
the To depend on something without linking it to this library, add its
name to the |
srcs
|
List of labels; default is All 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 All
If the
Permitted
... and any rules that produce those files (e.g. |
data
|
List of labels; default is data
at Typical attributes defined by
most build rules.
If a If a Your C++ code can access these data files like so:
|
hdrs
|
List of labels; default is 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 Permitted |
additional_compiler_inputs
|
List of labels; default is |
additional_linker_inputs
|
List of labels; default is For example, compiled Windows .res files can be provided here to be embedded in the binary target. |
alwayslink
|
Boolean; default is 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 |
copts
|
List of strings; default is
Each string in this attribute is added in the given order to
If the package declares the feature
|
cxxopts
|
List of strings; default is |
defines
|
List of strings; default is -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 |
implementation_deps
|
List of labels; default is 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 When set, the headers in the The prefix in the This attribute is only legal under |
includes
|
List of strings; default is -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 |
linkopts
|
List of strings; default is 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 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 |
linkstamp
|
Label; default is base package.
|
linkstatic
|
Boolean; default is 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
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:
If the
The
There should be very little code built with |
local_defines
|
List of strings; default is -D and added to the compile command line for this target,
but not to its dependents.
|
module_interfaces
|
List of labels; default is C++ Standard has no restriction about module interface file extension
The use is guarded by the flag
|
strip_include_prefix
|
String; default is 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 This attribute is only legal under |
textual_hdrs
|
List of labels; default is 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 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 sourcecc_shared_library(name, deps, additional_linker_inputs, compatible_with, deprecation, distribs, dynamic_deps, exec_compatible_with, exec_properties, experimental_disable_topo_sort_do_not_use_remove_before_7_0, 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.
Two shared libraries in dependencies link the same library statically
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
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
During analysis, the rule implementation will consider any target listed in
The implementation will also trigger errors whenever the same library is linked statically
into more than one |
additional_linker_inputs
|
List of labels; default is user_link_flags attribute.
|
dynamic_deps
|
List of labels; default is cc_shared_library dependencies the current target depends on.
The |
experimental_disable_topo_sort_do_not_use_remove_before_7_0
|
Boolean; default is |
exports_filter
|
List of strings; default is
Any target
Note that this attribute is not actually adding a dependency edge to those targets, the
dependency edge should instead be created by The following syntax is allowed:
|
roots
|
List of labels; default is |
shared_lib_name
|
String; default is |
static_deps
|
List of strings; default is |
user_link_flags
|
List of strings; default is
|
win_def_file
|
Label; default is 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 sourcecc_static_library(name, deps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)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 thesymbol_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 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
|
cc_test
View rule sourcecc_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 These can be |
srcs
|
List of labels; default is All 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 All
If the
Permitted
... and any rules that produce those files (e.g. |
data
|
List of labels; default is data
at Typical attributes defined by
most build rules.
If a If a Your C++ code can access these data files like so:
|
additional_linker_inputs
|
List of labels; default is For example, compiled Windows .res files can be provided here to be embedded in the binary target. |
conlyopts
|
List of strings; default is |
copts
|
List of strings; default is
Each string in this attribute is added in the given order to
If the package declares the feature
|
cxxopts
|
List of strings; default is |
defines
|
List of strings; default is -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 cc_shared_library dependencies the current target depends on.
The |
hdrs_check
|
String; default is |
includes
|
List of strings; default is -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 |
link_extra_lib
|
Label; default is
By default, C++ binaries are linked against |
linkopts
|
List of strings; default is LINKOPTS before
linking the binary target.
Each element of this list that does not start with |
linkshared
|
Boolean; default is linkshared=True in your rule. By default
this option is off.
The presence of this flag means that linking occurs with the
If you specify both |
linkstatic
|
Boolean; default is 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
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:
If the
The
There should be very little code built with |
local_defines
|
List of strings; default is -D and added to the compile command line for this target,
but not to its dependents.
|
malloc
|
Label; default is
By default, C++ binaries are linked against |
module_interfaces
|
List of labels; default is C++ Standard has no restriction about module interface file extension
The use is guarded by the flag
|
nocopts
|
String; default is 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
Stamped binaries are not rebuilt unless their dependencies change. |
win_def_file
|
Label; default is 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 sourcecc_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 thatall_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 |
ar_files
|
Label; default is |
as_files
|
Label; default is |
compiler_files
|
Label; required Collection of all cc_toolchain artifacts required for compile actions. |
compiler_files_without_includes
|
Label; default is |
coverage_files
|
Label; default is |
dwp_files
|
Label; required Collection of all cc_toolchain artifacts required for dwp actions. |
dynamic_runtime_lib
|
Label; default is 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 |
libc_top
|
Label; default is |
linker_files
|
Label; required Collection of all cc_toolchain artifacts required for linking actions. |
module_map
|
Label; default is |
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 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 |
supports_param_files
|
Boolean; default is |
toolchain_config
|
Label; required The label of the rule providingcc_toolchain_config_info .
|
toolchain_identifier
|
String; default is
Until issue #5380 is fixed
this is the recommended way of associating |
cc_toolchain_suite
View rule sourcecc_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 sourcefdo_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 sourcefdo_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 |
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 |
memprof_profile
View rule sourcememprof_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 sourcepropeller_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. |