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.

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 #included 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

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.

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 featureno_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).

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.

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.

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.

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

Arguments

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.

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.

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.

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 #included 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

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.

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.

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 featureno_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).

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.

Arguments

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.

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.

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 #included 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

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.

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 featureno_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).

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.

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.