Google Git
Sign in
bazel/bazel/a640dc240f79ef811fb4089436f1ba6d84ea6bc9/./docs/versions/8.1.0/reference/be/c-cpp.mdx
blob: ad0b5dbbf896a9b6dea115cec68419a46927c793 [file]
<html devsite>
<head>
<meta name="project_path" value="/_project.yaml">
<meta name="book_path" value="/versions/8.1.0/_book.yaml">
</head>
<body>
<!--
This document is synchronized with Bazel releases.
To edit, submit changes to the Bazel source code.
-->
<!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip -->
<html>
<body>
<h1 class="page-title">C / C++ Rules</h1>
{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %}
{% dynamic setvar version "8.1.0" %}
{% dynamic setvar original_path "/reference/be/c-cpp" %}
{% include "_buttons.html" %}
<h2>Rules</h2>
<ul>
<li>
<a href="#cc_binary">
cc_binary </a>
</li>
<li>
<a href="#cc_import">
cc_import </a>
</li>
<li>
<a href="#cc_library">
cc_library </a>
</li>
<li>
<a href="#cc_shared_library">
cc_shared_library </a>
</li>
<li>
<a href="#cc_static_library">
cc_static_library </a>
</li>
<li>
<a href="#cc_test">
cc_test </a>
</li>
<li>
<a href="#cc_toolchain">
cc_toolchain </a>
</li>
<li>
<a href="#cc_toolchain_suite">
cc_toolchain_suite </a>
</li>
<li>
<a href="#fdo_prefetch_hints">
fdo_prefetch_hints </a>
</li>
<li>
<a href="#fdo_profile">
fdo_profile </a>
</li>
<li>
<a href="#memprof_profile">
memprof_profile </a>
</li>
<li>
<a href="#propeller_optimize">
propeller_optimize </a>
</li>
</ul>
<h2 id="cc_binary">
cc_binary
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_binary.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_binary(<a href="#cc_binary.name">name</a>, <a href="#cc_binary.deps">deps</a>, <a href="#cc_binary.srcs">srcs</a>, <a href="#cc_binary.data">data</a>, <a href="#cc_binary.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_binary.conlyopts">conlyopts</a>, <a href="#cc_binary.copts">copts</a>, <a href="#cc_binary.cxxopts">cxxopts</a>, <a href="#cc_binary.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#cc_binary.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#cc_binary.hdrs_check">hdrs_check</a>, <a href="#cc_binary.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_binary.link_extra_lib">link_extra_lib</a>, <a href="#cc_binary.linkopts">linkopts</a>, <a href="#cc_binary.linkshared">linkshared</a>, <a href="#cc_binary.linkstatic">linkstatic</a>, <a href="#cc_binary.local_defines">local_defines</a>, <a href="#cc_binary.malloc">malloc</a>, <a href="#cc_binary.module_interfaces">module_interfaces</a>, <a href="#cc_binary.nocopts">nocopts</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="#cc_binary.reexport_deps">reexport_deps</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_binary.stamp">stamp</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_binary.win_def_file">win_def_file</a>)</pre>
<p>It produces an executable binary.</p>
<br/>The <code>name</code> 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 <code>main.cc</code>, then your name should
be <code>main</code>.
<h4>Implicit output targets</h4>
<ul>
<li><code><var>name</var>.stripped</code> (only built if explicitly requested): A stripped
version of the binary. <code>strip -g</code> is run on the binary to remove debug
symbols. Additional strip options can be provided on the command line using
<code>--stripopt=-foo</code>.</li>
<li><code><var>name</var>.dwp</code> (only built if explicitly requested): If
<a href="https://gcc.gnu.org/wiki/DebugFission">Fission</a> is enabled: a debug
information package file suitable for debugging remotely deployed binaries. Else: an
empty file.</li>
</ul>
<h3 id="cc_binary_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_binary.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="cc_binary.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of other libraries to be linked in to the binary target.
<p>These can be <code>cc_library</code> or <code>objc_library</code>
targets.</p>
It is also allowed to
put linker scripts (.lds) into deps, and reference them in
<a href="#cc_binary.linkopts">linkopts</a>.
</td>
</tr>
<tr>
<td id="cc_binary.srcs">
<code>srcs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of C and C++ files that are processed to create the library target.
These are C/C++ source and header files, either non-generated (normal source
code) or generated.
<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will
be compiled. These might be generated files: if a named file is in
the <code>outs</code> of some other rule, this <code>cc_library</code>
will automatically depend on that other rule.
</p>
<p>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.
</p>
<p>A <code>.h</code> file will not be compiled, but will be available for
inclusion by sources in this rule. Both <code>.cc</code> and
<code>.h</code> files can directly include headers listed in
these <code>srcs</code> or in the <code>hdrs</code> of this rule or any
rule listed in the <code>deps</code> argument.
</p>
<p>All <code>#include</code>d files must be mentioned in the
<code>hdrs</code> attribute of this or referenced <code>cc_library</code>
rules, or they should be listed in <code>srcs</code> if they are private
to this library. See <a href="#hdrs">"Header inclusion checking"</a> for
a more detailed description.
</p>
<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are
pre-compiled files. Your library might have these as
<code>srcs</code> if it uses third-party code for which we don't
have source code.
</p>
<p>If the <code>srcs</code> attribute includes the label of another rule,
<code>cc_library</code> will use the output files of that rule as source files to
compile. This is useful for one-off generation of source code (for more than occasional
use, it's better to implement a Starlark rule class and use the <code>cc_common</code>
API)
</p>
<p>
Permitted <code>srcs</code> file types:
</p>
<ul>
<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>,
<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li>
<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>,
<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li>
<li>Assembler with C preprocessor: <code>.S</code></li>
<li>Archive: <code>.a</code>, <code>.pic.a</code></li>
<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li>
<li>Shared library, versioned or unversioned: <code>.so</code>,
<code>.so.<i>version</i></code></li>
<li>Object file: <code>.o</code>, <code>.pic.o</code></li>
</ul>
<p>
... and any rules that produce those files (e.g. <code>cc_embed_data</code>).
Different extensions denote different programming languages in
accordance with gcc convention.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.data">
<code>data</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of files needed by this library at runtime.
See general comments about <code>data</code>
at <a href="/versions/8.1.0/reference/be/common-definitions#typical-attributes">Typical attributes defined by
most build rules</a>.
<p>If a <code>data</code> is the name of a generated file, then this
<code>cc_library</code> rule automatically depends on the generating
rule.
</p>
<p>If a <code>data</code> is a rule name, then this
<code>cc_library</code> rule automatically depends on that rule,
and that rule's <code>outs</code> are automatically added to
this <code>cc_library</code>'s data files.
</p>
<p>Your C++ code can access these data files like so:</p>
<pre><code class="lang-starlark">
const std::string path = devtools_build::GetDataDependencyFilepath(
"my/test/data/file");
</code></pre>
</td>
</tr>
<tr>
<td id="cc_binary.additional_linker_inputs">
<code>additional_linker_inputs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
Pass these files to the C++ linker command.
<p>
For example, compiled Windows .res files can be provided here to be embedded in
the binary target.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.conlyopts">
<code>conlyopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="cc_binary.copts">
<code>copts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C/C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
<p>
Each string in this attribute is added in the given order to <code>COPTS</code> before
compiling the binary target. The flags take effect only for compiling this target, not
its dependencies, so be careful about header files included elsewhere.
All paths should be relative to the workspace, not to the current package.
This attribute should not be needed outside of <code>third_party</code>.
</p>
<p>
If the package declares the <a href="/versions/8.1.0/reference/be/functions.html#package.features">feature</a>
<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings
that consist of a single "Make" variable.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.cxxopts">
<code>cxxopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="cc_binary.defines">
<code>defines</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of defines to add to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
Each string, which must consist of a single Bourne shell token,
is prepended with <code>-D</code> 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
<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.
</td>
</tr>
<tr>
<td id="cc_binary.dynamic_deps">
<code>dynamic_deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
These are other <code>cc_shared_library</code> dependencies the current target depends on.
<p>
The <code>cc_shared_library</code> implementation will use the list of
<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the
current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in
the transitive <code>deps</code> should not be linked in because they are already provided
by a different <code>cc_shared_library</code>.
</td>
</tr>
<tr>
<td id="cc_binary.hdrs_check">
<code>hdrs_check</code>
</td>
<td>
<p>String; default is <code>""</code></p>
Deprecated, no-op.
</td>
</tr>
<tr>
<td id="cc_binary.includes">
<code>includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of include dirs to be added to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution.
Each string is prepended with the package path and passed to the C++ toolchain for
expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system
with typical feature definitions will produce
<code>-isystem path_to_package/include_entry</code>.
This should only be used for third-party libraries that
do not conform to the Google style of writing #include statements.
Unlike <a href="#cc_binary.copts">COPTS</a>, 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 <a href="#cc_binary.copts">COPTS</a> instead.
<p>
The added <code>include</code> paths will include generated files as well as
files in the source tree.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.link_extra_lib">
<code>link_extra_lib</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p>
Control linking of extra libraries.
<p>
By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>,
which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>.
Without setting the flag, this library is empty by default. Setting the label flag
allows linking optional dependencies, such as overrides for weak symbols, interceptors
for shared library functions, or special runtime libraries (for malloc replacements,
prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to
<code>None</code> disables this behaviour.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.linkopts">
<code>linkopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these flags to the C++ linker command.
Subject to <a href="make-variables.html">"Make" variable</a> substitution,
<a href="common-definitions.html#sh-tokenization">
Bourne shell tokenization</a> and
<a href="common-definitions.html#label-expansion">label expansion</a>.
Each string in this attribute is added to <code>LINKOPTS</code> before
linking the binary target.
<p>
Each element of this list that does not start with <code>$</code> or <code>-</code> is
assumed to be the label of a target in <code>deps</code>. 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 <code>deps</code>.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.linkshared">
<code>linkshared</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
Create a shared library.
To enable this attribute, include <code>linkshared=True</code> in your rule. By default
this option is off.
<p>
The presence of this flag means that linking occurs with the <code>-shared</code> flag
to <code>gcc</code>, 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
<a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so
it should not be considered a substitute for the <a href="#cc_library">cc_library</a>
rule. For sake of scalability we recommend avoiding this approach altogether and
simply letting <code>java_library</code> depend on <code>cc_library</code> rules
instead.
</p>
<p>
If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>,
you get a single completely self-contained unit. If you specify both
<code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly
self-contained unit.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.linkstatic">
<code>linkstatic</code>
</td>
<td>
<p>Boolean; default is <code>True</code></p>
For <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and
<a href="/versions/8.1.0/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static
mode. For <code>cc_library.link_static</code>: see below.
<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p>
<p>
If enabled and this is a binary or test, this option tells the build tool to link in
<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible.
System libraries such as libc (but <i>not</i> the C/C++ runtime libraries,
see below) are still linked dynamically, as are libraries for which
there is no static library. So the resulting executable will still be dynamically
linked, hence only <i>mostly</i> static.
</p>
<p>
There are really three different ways to link an executable:
</p>
<ul>
<li> STATIC with fully_static_link feature, in which everything is linked statically;
e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/>
This mode is enabled by specifying <code>fully_static_link</code> in the
<a href="/versions/8.1.0/reference/be/common-definitions#features"><code>features</code></a> attribute.</li>
<li> 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. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/>
This mode is enabled by specifying <code>linkstatic=True</code>.</li>
<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is
available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/>
This mode is enabled by specifying <code>linkstatic=False</code>.</li>
</ul>
<p>
If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in
<code>features</code> is used outside of <code>//third_party</code>
please include a comment near the rule to explain why.
</p>
<p>
The <code>linkstatic</code> attribute has a different meaning if used on a
<a href="/versions/8.1.0/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule.
For a C++ library, <code>linkstatic=True</code> indicates that only
static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does
not prevent static libraries from being created. The attribute is meant to control the
creation of dynamic libraries.
</p>
<p>
There should be very little code built with <code>linkstatic=False</code> in production.
If <code>linkstatic=False</code>, then the build tool will create symlinks to
depended-upon shared libraries in the <code>*.runfiles</code> area.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.local_defines">
<code>local_defines</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of defines to add to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
Each string, which must consist of a single Bourne shell token,
is prepended with <code>-D</code> and added to the compile command line for this target,
but not to its dependents.
</td>
</tr>
<tr>
<td id="cc_binary.malloc">
<code>malloc</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p>
Override the default dependency on malloc.
<p>
By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>,
which is an empty library so the binary ends up using libc malloc.
This label must refer to a <code>cc_library</code>. If compilation is for a non-C++
rule, this option has no effect. The value of this attribute is ignored if
<code>linkshared=True</code> is specified.
</p>
</td>
</tr>
<tr>
<td id="cc_binary.module_interfaces">
<code>module_interfaces</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of files are regarded as C++20 Modules Interface.
<p>
C++ Standard has no restriction about module interface file extension
<ul>
<li>Clang use cppm </li>
<li>GCC can use any source file extension </li>
<li>MSVC use ixx </li>
</ul>
</p>
<p>The use is guarded by the flag
<code>--experimental_cpp_modules</code>.</p>
</td>
</tr>
<tr>
<td id="cc_binary.nocopts">
<code>nocopts</code>
</td>
<td>
<p>String; default is <code>""</code></p>
Remove matching options from the C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution.
The value of this attribute is interpreted as a regular expression.
Any preexisting <code>COPTS</code> that match this regular expression
(including values explicitly specified in the rule's <a
href="#cc_binary.copts">copts</a> attribute)
will be removed from <code>COPTS</code> for purposes of compiling this rule.
This attribute should not be needed or used
outside of <code>third_party</code>. The values are not preprocessed
in any way other than the "Make" variable substitution.
</td>
</tr>
<tr>
<td id="cc_binary.reexport_deps">
<code>reexport_deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
</td>
</tr>
<tr>
<td id="cc_binary.stamp">
<code>stamp</code>
</td>
<td>
<p>Integer; default is <code>-1</code></p>
Whether to encode build information into the binary. Possible values:
<ul>
<li>
<code>stamp = 1</code>: Always stamp the build information into the binary, even in
<a href="/versions/8.1.0/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This
setting should be avoided</b>, since it potentially kills remote caching for the
binary and any downstream actions that depend on it.
</li>
<li>
<code>stamp = 0</code>: Always replace build information by constant values. This
gives good build result caching.
</li>
<li>
<code>stamp = -1</code>: Embedding of build information is controlled by the
<a href="/versions/8.1.0/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.
</li>
</ul>
<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p>
</td>
</tr>
<tr>
<td id="cc_binary.win_def_file">
<code>win_def_file</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
The Windows DEF file to be passed to linker.
<p>This attribute should only be used when Windows is the target platform.
It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">
export symbols</a> during linking a shared library.</p>
</td>
</tr>
</tbody>
</table>
<h2 id="cc_import">
cc_import
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_import.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_import(<a href="#cc_import.name">name</a>, <a href="#cc_import.deps">deps</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#cc_import.hdrs">hdrs</a>, <a href="#cc_import.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#cc_import.includes">includes</a>, <a href="#cc_import.interface_library">interface_library</a>, <a href="#cc_import.linkopts">linkopts</a>, <a href="#cc_import.objects">objects</a>, <a href="#cc_import.pic_objects">pic_objects</a>, <a href="#cc_import.pic_static_library">pic_static_library</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_import.shared_library">shared_library</a>, <a href="#cc_import.static_library">static_library</a>, <a href="#cc_import.system_provided">system_provided</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>
<code>cc_import</code> rules allows users to import precompiled C/C++ libraries.
</p>
<p>
The following are the typical use cases: <br/>
1. Linking a static library
<pre><code class="lang-starlark">
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,
)
</code></pre>
2. Linking a shared library (Unix)
<pre><code class="lang-starlark">
cc_import(
name = "mylib",
hdrs = ["mylib.h"],
shared_library = "libmylib.so",
)
</code></pre>
3. Linking a shared library with interface library
<p>On Unix:
<pre><code class="lang-starlark">
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",
)
</code></pre>
<p>On Windows:
<pre><code class="lang-starlark">
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",
)
</code></pre>
4. Linking a shared library with <code>system_provided=True</code>
<p>On Unix:
<pre><code class="lang-starlark">
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,
)
</code></pre>
<p>On Windows:
<pre><code class="lang-starlark">
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,
)
</code></pre>
5. Linking to static or shared library
<p>On Unix:
<pre><code class="lang-starlark">
cc_import(
name = "mylib",
hdrs = ["mylib.h"],
static_library = "libmylib.a",
shared_library = "libmylib.so",
)
</code></pre>
<p>On Windows:
<pre><code class="lang-starlark">
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",
)
</code></pre>
<p>The remaining is the same on Unix and Windows:
<pre><code class="lang-starlark">
# 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,
)
</code></pre>
<p>
<code>cc_import</code> supports an include attribute. For example:
<pre><code class="lang-starlark">
cc_import(
name = "curl_lib",
hdrs = glob(["vendor/curl/include/curl/*.h"]),
includes = ["vendor/curl/include"],
shared_library = "vendor/curl/lib/.libs/libcurl.dylib",
)
</code></pre>
</p>
<h3 id="cc_import_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_import.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="cc_import.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of other libraries that the target depends upon.
See general comments about <code>deps</code>
at <a href="/versions/8.1.0/reference/be/common-definitions#typical-attributes">Typical attributes defined by
most build rules</a>.
</td>
</tr>
<tr>
<td id="cc_import.hdrs">
<code>hdrs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of header files published by
this precompiled library to be directly included by sources in dependent rules.
</td>
</tr>
<tr>
<td id="cc_import.alwayslink">
<code>alwayslink</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
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.
<p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a
<a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>,
please upgrade your VS 2017 to the latest version.</p>
</td>
</tr>
<tr>
<td id="cc_import.includes">
<code>includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of include dirs to be added to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution.
Each string is prepended with the package path and passed to the C++ toolchain for
expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system
with typical feature definitions will produce
<code>-isystem path_to_package/include_entry</code>.
This should only be used for third-party libraries that
do not conform to the Google style of writing #include statements.
Unlike <a href="#cc_binary.copts">COPTS</a>, 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 <a href="#cc_binary.copts">COPTS</a> instead.
<p>
The default <code>include</code> path doesn't include generated
files. If you need to <code>#include</code> a generated header
file, list it in the <code>srcs</code>.
</p>
</td>
</tr>
<tr>
<td id="cc_import.interface_library">
<code>interface_library</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
A single interface library for linking the shared library.
<p> Permitted file types:
<code>.ifso</code>,
<code>.tbd</code>,
<code>.lib</code>,
<code>.so</code>
or <code>.dylib</code>
</p>
</td>
</tr>
<tr>
<td id="cc_import.linkopts">
<code>linkopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these flags to the C++ linker command.
Subject to <a href="make-variables.html">"Make" variable</a> substitution,
<a href="common-definitions.html#sh-tokenization">
Bourne shell tokenization</a> and
<a href="common-definitions.html#label-expansion">label expansion</a>.
Each string in this attribute is added to <code>LINKOPTS</code> before
linking the binary target.
<p>
Each element of this list that does not start with <code>$</code> or <code>-</code> is
assumed to be the label of a target in <code>deps</code>. 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 <code>deps</code>.
</p>
</td>
</tr>
<tr>
<td id="cc_import.objects">
<code>objects</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
</td>
</tr>
<tr>
<td id="cc_import.pic_objects">
<code>pic_objects</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
</td>
</tr>
<tr>
<td id="cc_import.pic_static_library">
<code>pic_static_library</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
</td>
</tr>
<tr>
<td id="cc_import.shared_library">
<code>shared_library</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
A single precompiled shared library. Bazel ensures it is available to the
binary that depends on it during runtime.
<p> Permitted file types:
<code>.so</code>,
<code>.dll</code>
or <code>.dylib</code>
</p>
</td>
</tr>
<tr>
<td id="cc_import.static_library">
<code>static_library</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
A single precompiled static library.
<p> Permitted file types:
<code>.a</code>,
<code>.pic.a</code>
or <code>.lib</code>
</p>
</td>
</tr>
<tr>
<td id="cc_import.system_provided">
<code>system_provided</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
If 1, it indicates the shared library required at runtime is provided by the system. In
this case, <code>interface_library</code> should be specified and
<code>shared_library</code> should be empty.
</td>
</tr>
</tbody>
</table>
<h2 id="cc_library">
cc_library
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_library.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_library(<a href="#cc_library.name">name</a>, <a href="#cc_library.deps">deps</a>, <a href="#cc_library.srcs">srcs</a>, <a href="#cc_library.data">data</a>, <a href="#cc_library.hdrs">hdrs</a>, <a href="#cc_library.additional_compiler_inputs">additional_compiler_inputs</a>, <a href="#cc_library.additional_linker_inputs">additional_linker_inputs</a>, <a href="#cc_library.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_library.conlyopts">conlyopts</a>, <a href="#cc_library.copts">copts</a>, <a href="#cc_library.cxxopts">cxxopts</a>, <a href="#cc_library.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#cc_library.hdrs_check">hdrs_check</a>, <a href="#cc_library.implementation_deps">implementation_deps</a>, <a href="#cc_library.include_prefix">include_prefix</a>, <a href="#cc_library.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_library.linkopts">linkopts</a>, <a href="#cc_library.linkstamp">linkstamp</a>, <a href="#cc_library.linkstatic">linkstatic</a>, <a href="#cc_library.local_defines">local_defines</a>, <a href="#cc_library.module_interfaces">module_interfaces</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_library.strip_include_prefix">strip_include_prefix</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#cc_library.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_library.win_def_file">win_def_file</a>)</pre>
<p>Use <code>cc_library()</code> for C++-compiled libraries.
The result is either a <code>.so</code>, <code>.lo</code>,
or <code>.a</code>, depending on what is needed.
</p>
<p>
If you build something with static linking that depends on
a <code>cc_library</code>, the output of a depended-on library rule
is the <code>.a</code> file. If you specify
<code>alwayslink=True</code>, you get the <code>.lo</code> file.
</p>
<p>
The actual output file name is <code>lib<i>foo</i>.so</code> for
the shared library, where <i>foo</i> is the name of the rule. The
other kinds of libraries end with <code>.lo</code> and <code>.a</code>,
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.
</p>
<h4 id="hdrs">Header inclusion checking</h4>
<p>
All header files that are used in the build must be declared in
the <code>hdrs</code> or <code>srcs</code> of <code>cc_*</code> rules.
This is enforced.
</p>
<p>
For <code>cc_library</code> rules, headers in <code>hdrs</code> comprise the
public interface of the library and can be directly included both
from the files in <code>hdrs</code> and <code>srcs</code> of the library
itself as well as from files in <code>hdrs</code> and <code>srcs</code>
of <code>cc_*</code> rules that list the library in their <code>deps</code>.
Headers in <code>srcs</code> must only be directly included from the files
in <code>hdrs</code> and <code>srcs</code> of the library itself. When
deciding whether to put a header into <code>hdrs</code> or <code>srcs</code>,
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 <code>public</code> and <code>private</code> visibility in programming languages.
</p>
<p>
<code>cc_binary</code> and <code>cc_test</code> rules do not have an exported
interface, so they also do not have a <code>hdrs</code> attribute. All headers
that belong to the binary or test directly should be listed in
the <code>srcs</code>.
</p>
<p>
To illustrate these rules, look at the following example.
</p>
<pre><code class="lang-starlark">
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"],
)
</code></pre>
<p>
The allowed direct inclusions in this example are listed in the table below.
For example <code>foo.cc</code> is allowed to directly
include <code>foo.h</code> and <code>bar.h</code>, but not <code>baz.h</code>.
</p>
<table class="table table-striped table-bordered table-condensed">
<thead>
<tr><th>Including file</th><th>Allowed inclusions</th></tr>
</thead>
<tbody>
<tr><td>foo.h</td><td>bar.h</td></tr>
<tr><td>foo.cc</td><td>foo.h bar.h</td></tr>
<tr><td>bar.h</td><td>bar-impl.h baz.h</td></tr>
<tr><td>bar-impl.h</td><td>bar.h baz.h</td></tr>
<tr><td>bar.cc</td><td>bar.h bar-impl.h baz.h</td></tr>
<tr><td>baz.h</td><td>baz-impl.h</td></tr>
<tr><td>baz-impl.h</td><td>baz.h</td></tr>
<tr><td>baz.cc</td><td>baz.h baz-impl.h</td></tr>
</tbody>
</table>
<p>
The inclusion checking rules only apply to <em>direct</em>
inclusions. In the example above <code>foo.cc</code> is allowed to
include <code>bar.h</code>, which may include <code>baz.h</code>, which in
turn is allowed to include <code>baz-impl.h</code>. Technically, the
compilation of a <code>.cc</code> file may transitively include any header
file in the <code>hdrs</code> or <code>srcs</code> in
any <code>cc_library</code> in the transitive <code>deps</code> closure. In
this case the compiler may read <code>baz.h</code> and <code>baz-impl.h</code>
when compiling <code>foo.cc</code>, but <code>foo.cc</code> must not
contain <code>#include "baz.h"</code>. For that to be
allowed, <code>baz</code> must be added to the <code>deps</code>
of <code>foo</code>.
</p>
<p>
Bazel depends on toolchain support to enforce the inclusion checking rules.
The <code>layering_check</code> feature has to be supported by the toolchain
and requested explicitly, for example via the
<code>--features=layering_check</code> command-line flag or the
<code>features</code> parameter of the
<a href="/versions/8.1.0/reference/be/functions.html#package"><code>package</code></a> function. The toolchains
provided by Bazel only support this feature with clang on Unix and macOS.
</p>
<h4 id="cc_library_examples">Examples</h4>
<p id="alwayslink_lib_example">
We use the <code>alwayslink</code> flag to force the linker to link in
this code although the main binary code doesn't reference it.
</p>
<pre><code class="lang-starlark">
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,
)
</code></pre>
<p>The following example comes from
<code>third_party/python2_4_3/BUILD</code>.
Some of the code uses the <code>dl</code> library (to load
another, dynamic library), so this
rule specifies the <code>-ldl</code> link option to link the
<code>dl</code> library.
</p>
<pre><code class="lang-starlark">
cc_library(
name = "python2_4_3",
linkopts = [
"-ldl",
"-lutil",
],
deps = ["//third_party/expat"],
)
</code></pre>
<p>The following example comes from <code>third_party/kde/BUILD</code>.
We keep pre-built <code>.so</code> files in the depot.
The header files live in a subdirectory named <code>include</code>.
</p>
<pre><code class="lang-starlark">
cc_library(
name = "kde",
srcs = [
"lib/libDCOP.so",
"lib/libkdesu.so",
"lib/libkhtml.so",
"lib/libkparts.so",
<var>...more .so files...</var>,
],
includes = ["include"],
deps = ["//third_party/X11"],
)
</code></pre>
<p>The following example comes from <code>third_party/gles/BUILD</code>.
Third-party code often needs some <code>defines</code> and
<code>linkopts</code>.
</p>
<pre><code class="lang-starlark">
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",
],
)
</code></pre>
<h3 id="cc_library_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_library.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="cc_library.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of other libraries that the library target depends upon.
<p>These can be <code>cc_library</code> or <code>objc_library</code> targets.</p>
<p>See general comments about <code>deps</code>
at <a href="/versions/8.1.0/reference/be/common-definitions#typical-attributes">Typical attributes defined by
most build rules</a>.
</p>
<p>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 <code>deps</code>.
</p>
<p>Despite the "deps" name, not all of this library's clients
belong here. Run-time data dependencies belong in <code>data</code>.
Source files generated by other rules belong in <code>srcs</code>.
</p>
<p>To link in a pre-compiled third-party library, add its name to
the <code>srcs</code> instead.
</p>
<p>To depend on something without linking it to this library, add its
name to the <code>data</code> instead.
</p>
</td>
</tr>
<tr>
<td id="cc_library.srcs">
<code>srcs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of C and C++ files that are processed to create the library target.
These are C/C++ source and header files, either non-generated (normal source
code) or generated.
<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will
be compiled. These might be generated files: if a named file is in
the <code>outs</code> of some other rule, this <code>cc_library</code>
will automatically depend on that other rule.
</p>
<p>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.
</p>
<p>A <code>.h</code> file will not be compiled, but will be available for
inclusion by sources in this rule. Both <code>.cc</code> and
<code>.h</code> files can directly include headers listed in
these <code>srcs</code> or in the <code>hdrs</code> of this rule or any
rule listed in the <code>deps</code> argument.
</p>
<p>All <code>#include</code>d files must be mentioned in the
<code>hdrs</code> attribute of this or referenced <code>cc_library</code>
rules, or they should be listed in <code>srcs</code> if they are private
to this library. See <a href="#hdrs">"Header inclusion checking"</a> for
a more detailed description.
</p>
<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are
pre-compiled files. Your library might have these as
<code>srcs</code> if it uses third-party code for which we don't
have source code.
</p>
<p>If the <code>srcs</code> attribute includes the label of another rule,
<code>cc_library</code> will use the output files of that rule as source files to
compile. This is useful for one-off generation of source code (for more than occasional
use, it's better to implement a Starlark rule class and use the <code>cc_common</code>
API)
</p>
<p>
Permitted <code>srcs</code> file types:
</p>
<ul>
<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>,
<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li>
<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>,
<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li>
<li>Assembler with C preprocessor: <code>.S</code></li>
<li>Archive: <code>.a</code>, <code>.pic.a</code></li>
<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li>
<li>Shared library, versioned or unversioned: <code>.so</code>,
<code>.so.<i>version</i></code></li>
<li>Object file: <code>.o</code>, <code>.pic.o</code></li>
</ul>
<p>
... and any rules that produce those files (e.g. <code>cc_embed_data</code>).
Different extensions denote different programming languages in
accordance with gcc convention.
</p>
</td>
</tr>
<tr>
<td id="cc_library.data">
<code>data</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of files needed by this library at runtime.
See general comments about <code>data</code>
at <a href="/versions/8.1.0/reference/be/common-definitions#typical-attributes">Typical attributes defined by
most build rules</a>.
<p>If a <code>data</code> is the name of a generated file, then this
<code>cc_library</code> rule automatically depends on the generating
rule.
</p>
<p>If a <code>data</code> is a rule name, then this
<code>cc_library</code> rule automatically depends on that rule,
and that rule's <code>outs</code> are automatically added to
this <code>cc_library</code>'s data files.
</p>
<p>Your C++ code can access these data files like so:</p>
<pre><code class="lang-starlark">
const std::string path = devtools_build::GetDataDependencyFilepath(
"my/test/data/file");
</code></pre>
</td>
</tr>
<tr>
<td id="cc_library.hdrs">
<code>hdrs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of header files published by
this library to be directly included by sources in dependent rules.
<p>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 <code>srcs</code> attribute instead, even if they are
included by a published header. See <a href="#hdrs">"Header inclusion
checking"</a> for a more detailed description. </p>
<p>Permitted <code>headers</code> file types:
<code>.h</code>,
<code>.hh</code>,
<code>.hpp</code>,
<code>.hxx</code>.
</p>
</td>
</tr>
<tr>
<td id="cc_library.additional_compiler_inputs">
<code>additional_compiler_inputs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
Any additional files you might want to pass to the compiler command line, such as sanitizer
ignorelists, for example. Files specified here can then be used in copts with the
$(location) function.
</td>
</tr>
<tr>
<td id="cc_library.additional_linker_inputs">
<code>additional_linker_inputs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
Pass these files to the C++ linker command.
<p>
For example, compiled Windows .res files can be provided here to be embedded in
the binary target.
</p>
</td>
</tr>
<tr>
<td id="cc_library.alwayslink">
<code>alwayslink</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
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
<code>srcs</code>, 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.
<p>If alwayslink doesn't work with VS 2017 on Windows, that is due to a
<a href="https://github.com/bazelbuild/bazel/issues/3949">known issue</a>,
please upgrade your VS 2017 to the latest version.</p>
</td>
</tr>
<tr>
<td id="cc_library.conlyopts">
<code>conlyopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="cc_library.copts">
<code>copts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C/C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
<p>
Each string in this attribute is added in the given order to <code>COPTS</code> before
compiling the binary target. The flags take effect only for compiling this target, not
its dependencies, so be careful about header files included elsewhere.
All paths should be relative to the workspace, not to the current package.
This attribute should not be needed outside of <code>third_party</code>.
</p>
<p>
If the package declares the <a href="/versions/8.1.0/reference/be/functions.html#package.features">feature</a>
<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings
that consist of a single "Make" variable.
</p>
</td>
</tr>
<tr>
<td id="cc_library.cxxopts">
<code>cxxopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="cc_library.defines">
<code>defines</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of defines to add to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
Each string, which must consist of a single Bourne shell token,
is prepended with <code>-D</code> 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
<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.
</td>
</tr>
<tr>
<td id="cc_library.hdrs_check">
<code>hdrs_check</code>
</td>
<td>
<p>String; default is <code>""</code></p>
Deprecated, no-op.
</td>
</tr>
<tr>
<td id="cc_library.implementation_deps">
<code>implementation_deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of other libraries that the library target depends on. Unlike with
<code>deps</code>, 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 <code>implementation_deps</code> are still linked in
binary targets that depend on this library.
</td>
</tr>
<tr>
<td id="cc_library.include_prefix">
<code>include_prefix</code>
</td>
<td>
<p>String; default is <code>""</code></p>
The prefix to add to the paths of the headers of this rule.
<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible
at is the value of this attribute prepended to their repository-relative path.
<p>The prefix in the <code>strip_include_prefix</code> attribute is removed before this
prefix is added.
<p>This attribute is only legal under <code>third_party</code>.
</td>
</tr>
<tr>
<td id="cc_library.includes">
<code>includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of include dirs to be added to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution.
Each string is prepended with the package path and passed to the C++ toolchain for
expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system
with typical feature definitions will produce
<code>-isystem path_to_package/include_entry</code>.
This should only be used for third-party libraries that
do not conform to the Google style of writing #include statements.
Unlike <a href="#cc_binary.copts">COPTS</a>, 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 <a href="#cc_binary.copts">COPTS</a> instead.
<p>
The added <code>include</code> paths will include generated files as well as
files in the source tree.
</p>
</td>
</tr>
<tr>
<td id="cc_library.linkopts">
<code>linkopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
See <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary.linkopts"><code>cc_binary.linkopts</code></a>.
The <code>linkopts</code> attribute is also applied to any target that
depends, directly or indirectly, on this library via <code>deps</code>
attributes (or via other attributes that are treated similarly:
the <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary.malloc"><code>malloc</code></a>
attribute of <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a>). Dependency
linkopts take precedence over dependent linkopts (i.e. dependency linkopts
appear later in the command line). Linkopts specified in
<a href='../user-manual.html#flag--linkopt'><code>--linkopt</code></a>
take precedence over rule linkopts.
</p>
<p>
Note that the <code>linkopts</code> attribute only applies
when creating <code>.so</code> files or executables, not
when creating <code>.a</code> or <code>.lo</code> files.
So if the <code>linkstatic=True</code> attribute is set, the
<code>linkopts</code> attribute has no effect on the creation of
this library, only on other targets which depend on this library.
</p>
<p>
Also, it is important to note that "-Wl,-soname" or "-Xlinker -soname"
options are not supported and should never be specified in this attribute.
</p>
<p> The <code>.so</code> files produced by <code>cc_library</code>
rules are not linked against the libraries that they depend
on. If you're trying to create a shared library for use
outside of the main repository, e.g. for manual use
with <code>dlopen()</code> or <code>LD_PRELOAD</code>,
it may be better to use a <code>cc_binary</code> rule
with the <code>linkshared=True</code> attribute.
See <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary.linkshared"><code>cc_binary.linkshared</code></a>.
</p>
</td>
</tr>
<tr>
<td id="cc_library.linkstamp">
<code>linkstamp</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Simultaneously compiles and links the specified C++ source file into the final
binary. This trickery is required to introduce timestamp
information into binaries; if we compiled the source file to an
object file in the usual way, the timestamp would be incorrect.
A linkstamp compilation may not include any particular set of
compiler flags and so should not depend on any particular
header, compiler option, or other build variable.
<em class='harmful'>This option should only be needed in the
<code>base</code> package.</em>
</td>
</tr>
<tr>
<td id="cc_library.linkstatic">
<code>linkstatic</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
For <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and
<a href="/versions/8.1.0/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static
mode. For <code>cc_library.link_static</code>: see below.
<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p>
<p>
If enabled and this is a binary or test, this option tells the build tool to link in
<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible.
System libraries such as libc (but <i>not</i> the C/C++ runtime libraries,
see below) are still linked dynamically, as are libraries for which
there is no static library. So the resulting executable will still be dynamically
linked, hence only <i>mostly</i> static.
</p>
<p>
There are really three different ways to link an executable:
</p>
<ul>
<li> STATIC with fully_static_link feature, in which everything is linked statically;
e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/>
This mode is enabled by specifying <code>fully_static_link</code> in the
<a href="/versions/8.1.0/reference/be/common-definitions#features"><code>features</code></a> attribute.</li>
<li> 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. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/>
This mode is enabled by specifying <code>linkstatic=True</code>.</li>
<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is
available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/>
This mode is enabled by specifying <code>linkstatic=False</code>.</li>
</ul>
<p>
If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in
<code>features</code> is used outside of <code>//third_party</code>
please include a comment near the rule to explain why.
</p>
<p>
The <code>linkstatic</code> attribute has a different meaning if used on a
<a href="/versions/8.1.0/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule.
For a C++ library, <code>linkstatic=True</code> indicates that only
static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does
not prevent static libraries from being created. The attribute is meant to control the
creation of dynamic libraries.
</p>
<p>
There should be very little code built with <code>linkstatic=False</code> in production.
If <code>linkstatic=False</code>, then the build tool will create symlinks to
depended-upon shared libraries in the <code>*.runfiles</code> area.
</p>
</td>
</tr>
<tr>
<td id="cc_library.local_defines">
<code>local_defines</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of defines to add to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
Each string, which must consist of a single Bourne shell token,
is prepended with <code>-D</code> and added to the compile command line for this target,
but not to its dependents.
</td>
</tr>
<tr>
<td id="cc_library.module_interfaces">
<code>module_interfaces</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of files are regarded as C++20 Modules Interface.
<p>
C++ Standard has no restriction about module interface file extension
<ul>
<li>Clang use cppm </li>
<li>GCC can use any source file extension </li>
<li>MSVC use ixx </li>
</ul>
</p>
<p>The use is guarded by the flag
<code>--experimental_cpp_modules</code>.</p>
</td>
</tr>
<tr>
<td id="cc_library.strip_include_prefix">
<code>strip_include_prefix</code>
</td>
<td>
<p>String; default is <code>""</code></p>
The prefix to strip from the paths of the headers of this rule.
<p>When set, the headers in the <code>hdrs</code> attribute of this rule are accessible
at their path with this prefix cut off.
<p>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.
<p>The prefix in the <code>include_prefix</code> attribute is added after this prefix is
stripped.
<p>This attribute is only legal under <code>third_party</code>.
</td>
</tr>
<tr>
<td id="cc_library.textual_hdrs">
<code>textual_hdrs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of header files published by
this library to be textually included by sources in dependent rules.
<p>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.</p>
</td>
</tr>
<tr>
<td id="cc_library.win_def_file">
<code>win_def_file</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
The Windows DEF file to be passed to linker.
<p>This attribute should only be used when Windows is the target platform.
It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">
export symbols</a> during linking a shared library.</p>
</td>
</tr>
</tbody>
</table>
<h2 id="cc_shared_library">
cc_shared_library
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_shared_library.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_shared_library(<a href="#cc_shared_library.name">name</a>, <a href="#cc_shared_library.deps">deps</a>, <a href="#cc_shared_library.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#cc_shared_library.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0">experimental_disable_topo_sort_do_not_use_remove_before_7_0</a>, <a href="#cc_shared_library.exports_filter">exports_filter</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_shared_library.roots">roots</a>, <a href="#cc_shared_library.shared_lib_name">shared_lib_name</a>, <a href="#cc_shared_library.static_deps">static_deps</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#cc_shared_library.user_link_flags">user_link_flags</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_shared_library.win_def_file">win_def_file</a>)</pre>
<p>It produces a shared library.</p>
<h4 id="cc_shard_library_examples">Example</h4>
<pre class="code">
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"],
)
</pre>
<p>In the example <code>foo_shared</code> statically links <code>foo</code>
and <code>baz</code>, the latter being a transitive dependency. It doesn't
link <code>bar</code> because it is already provided dynamically by the
<code>dynamic_dep</code> <code>bar_shared</code>.</p>
<p><code>foo_shared</code> uses a linker script *.lds file to control which
symbols should be exported. The <code>cc_shared_library</code> 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.</p>
<p>Every direct dependency of <code>cc_shared_library</code> is assumed to be
exported. Therefore, Bazel assumes during analysis that <code>foo</code> is being
exported by <code>foo_shared</code>. <code>baz</code> is not assumed to be exported
by <code>foo_shared</code>. Every target matched by the <code>exports_filter</code>
is also assumed to be exported.</p>
<p>Every single <code>cc_library</code> in the example should appear at most in one
<code>cc_shared_library</code>. If we wanted to link <code>baz</code> also into
<code>bar_shared</code> we would need to add
<code>tags = ["LINKABLE_MORE_THAN_ONCE"]</code> to <code>baz</code>.</p>
<p>Due to the <code>shared_lib_name</code> attribute, the file produced by
<code>bar_shared</code> will have the name <code>bar.so</code> as opposed
to the name <code>libbar.so</code> that it would have by default on Linux.</p>
<h4 id="cc_shard_library_examples">Errors</h4>
<h5><code>Two shared libraries in dependencies export the same symbols.</code></h5>
<p>This will happen whenever you are creating a target with two different
<code>cc_shared_library</code> dependencies that export the same target. To fix this
you need to stop the libraries from being exported in one of the
<code>cc_shared_library</code> dependencies.</p>
<h5><code>Two shared libraries in dependencies link the same library statically</code></h5>
<p>This will happen whenever you are creating a new <code>cc_shared_library</code> with two
different <code>cc_shared_library</code> dependencies that link the same target statically.
Similar to the error with exports.</p>
<p>One way to fix this is to stop linking the library into one of the
<code>cc_shared_library</code> 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 <code>cc_library</code> with <code>LINKABLE_MORE_THAN_ONCE</code>
but this fix should be rare and you should absolutely make sure that the
<code>cc_library</code> is indeed safe to link more than once.</p>
<h5><code>'//foo:foo' is already linked statically in '//bar:bar' but not exported`</code></h5>
<p>This means that a library in the transitive closure of your <code>deps</code> is reachable
without going through one of the <code>cc_shared_library</code> dependencies but is already
linked into a different <code>cc_shared_library</code> in <code>dynamic_deps</code> and is not
exported.</p>
<p>The solution is to export it from the <code>cc_shared_library</code> dependency or pull out
a third <code>cc_shared_library</code> that exports it.</p>
<h5><code>Do not place libraries which only contain a precompiled dynamic library in deps.
</code></h5>
<p>If you have a precompiled dynamic library, this doesn't need to and cannot be
linked statically into the current <code>cc_shared_library</code> target that you are
currently creating. Therefore, it doesn't belong in <code>deps</code> of the
<code>cc_shared_library</code>. If this precompiled dynamic library is a dependency of one
of your <code>cc_libraries</code>, then the <code>cc_library</code> needs to depend on it
directly.</p>
<h5><code>Trying to export a library already exported by a different shared library</code></h5>
<p>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.</p>
<p>To fix this, remove the target from <code>deps</code> and just rely on it from the dynamic
dependency or make sure that the <code>exports_filter</code> doesn't catch this target.</p>
<h3 id="cc_shared_library_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_shared_library.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="cc_shared_library.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
Top level libraries that will unconditionally be statically linked into the shared library
after being whole-archived.
<p>
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 <code>cc_shared_library</code>
in <code>dynamic_deps</code>.</p>
<p>
During analysis, the rule implementation will consider any target listed in
<code>deps</code> as being exported by the shared library in order to give errors when
multiple <code>cc_shared_libraries</code> export the same targets. The rule implementation
does not take care of informing the linker about which symbols should be exported by the
shared object. The user should take care of this via linker scripts or visibility
declarations in the source code.</p>
<p>
The implementation will also trigger errors whenever the same library is linked statically
into more than one <code>cc_shared_library</code>. This can be avoided by adding
<code>"LINKABLE_MORE_THAN_ONCE"</code> to the <code>cc_library.tags</code> or by listing
the `cc_library` as an export of one of the shared libraries so that one can be made a
<code>dynamic_dep</code> of the other.
</p>
</td>
</tr>
<tr>
<td id="cc_shared_library.additional_linker_inputs">
<code>additional_linker_inputs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
Any additional files that you may want to pass to the linker, for example, linker scripts.
You have to separately pass any linker flags that the linker needs in order to be aware
of this file. You can do so via the <code>user_link_flags</code> attribute.
</td>
</tr>
<tr>
<td id="cc_shared_library.dynamic_deps">
<code>dynamic_deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
These are other <code>cc_shared_library</code> dependencies the current target depends on.
<p>
The <code>cc_shared_library</code> implementation will use the list of
<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the
current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in
the transitive <code>deps</code> should not be linked in because they are already provided
by a different <code>cc_shared_library</code>.
</p>
</td>
</tr>
<tr>
<td id="cc_shared_library.experimental_disable_topo_sort_do_not_use_remove_before_7_0">
<code>experimental_disable_topo_sort_do_not_use_remove_before_7_0</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
</td>
</tr>
<tr>
<td id="cc_shared_library.exports_filter">
<code>exports_filter</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
This attribute contains a list of targets that are claimed to be exported by the current
shared library.
<p>
Any target <code>deps</code> is already understood to be exported by the shared library.
This attribute should be used to list any targets that are exported by the shared library
but are transitive dependencies of <code>deps</code>.
</p>
<p>
Note that this attribute is not actually adding a dependency edge to those targets, the
dependency edge should instead be created by <code>deps</code>.The entries in this
attribute are just strings. Keep in mind that when placing a target in this attribute,
this is considered a claim that the shared library exports the symbols from that target.
The <code>cc_shared_library</code> logic doesn't actually handle telling the linker which
symbols should be exported.
</p>
<p>The following syntax is allowed:</p>
<p><code>//foo:__pkg__</code> to account for any target in foo/BUILD</p>
<p><code>//foo:__subpackages__</code> to account for any target in foo/BUILD or any other
package below foo/ like foo/bar/BUILD</p>
</td>
</tr>
<tr>
<td id="cc_shared_library.roots">
<code>roots</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
</td>
</tr>
<tr>
<td id="cc_shared_library.shared_lib_name">
<code>shared_lib_name</code>
</td>
<td>
<p>String; default is <code>""</code></p>
By default cc_shared_library will use a name for the shared library output file based on
the target's name and the platform. This includes an extension and sometimes a prefix.
Sometimes you may not want the default name, for example, when loading C++ shared libraries
for Python the default lib* prefix is often not desired, in which case you can use this
attribute to choose a custom name.
</td>
</tr>
<tr>
<td id="cc_shared_library.static_deps">
<code>static_deps</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
</td>
</tr>
<tr>
<td id="cc_shared_library.user_link_flags">
<code>user_link_flags</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Any additional flags that you may want to pass to the linker. For example, to make the
linker aware of a linker script passed via additional_linker_inputs you can use the
following:
<pre><code class="lang-starlark">
cc_shared_library(
name = "foo_shared",
additional_linker_inputs = select({
"//src/conditions:linux": [
":foo.lds",
":additional_script.txt",
],
"//conditions:default": []}),
user_link_flags = select({
"//src/conditions:linux": [
"-Wl,-rpath,kittens",
"-Wl,--version-script=$(location :foo.lds)",
"-Wl,--script=$(location :additional_script.txt)",
],
"//conditions:default": []}),
...
)
</code></pre>
</td>
</tr>
<tr>
<td id="cc_shared_library.win_def_file">
<code>win_def_file</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
The Windows DEF file to be passed to linker.
<p>This attribute should only be used when Windows is the target platform.
It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">
export symbols</a> during linking a shared library.</p>
</td>
</tr>
</tbody>
</table>
<h2 id="cc_static_library">
cc_static_library
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/experimental_cc_static_library.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_static_library(<a href="#cc_static_library.name">name</a>, <a href="#cc_static_library.deps">deps</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<b>This rule is currently experimental and can only be used with the <code>
--experimental_cc_static_library</code> flag.</b>
Produces a static library from a list of targets and their transitive dependencies.
<p>The resulting static library contains the object files of the targets listed in
<code>deps</code> as well as their transitive dependencies, with preference given to
<code>PIC</code> objects.</p>
<h4 id="cc_static_library_output_groups">Output groups</h4>
<h5><code>linkdeps</code></h5>
<p>A text file containing the labels of those transitive dependencies of targets listed in
<code>deps</code> 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.</p>
<h5><code>linkopts</code></h5>
<p>A text file containing the user-provided <code>linkopts</code> of all transitive
dependencies of targets listed in <code>deps</code>.
<h4 id="cc_static_library_symbol_check">Duplicate symbols</h4>
<p>By default, the <code>cc_static_library</code> 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.</p>
<p>This check can be disabled per target or per package by setting
<code>features = ["-symbol_check"]</code> or globally via
<code>--features=-symbol_check</code>.</p>
<h5 id="cc_static_library_symbol_check_toolchain">Toolchain support for <code>symbol_check</code></h5>
<p>The auto-configured C++ toolchains shipped with Bazel support the
<code>symbol_check</code> feature on all platforms. Custom toolchains can add support for
it in one of two ways:</p>
<ul>
<li>Implementing the <code>ACTION_NAMES.validate_static_library</code> action and
enabling it with the <code>symbol_check</code> 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.</li>
<li>Having the <code>symbol_check</code> feature add archiver flags that cause the
action creating the static library to fail on duplicate symbols.</li>
</ul>
<h3 id="cc_static_library_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_static_library.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="cc_static_library.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of targets to combine into a static library, including all their transitive
dependencies.
<p>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
<code>linkdeps</code> output group.</p>
</td>
</tr>
</tbody>
</table>
<h2 id="cc_test">
cc_test
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_test.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_test(<a href="#cc_test.name">name</a>, <a href="#cc_test.deps">deps</a>, <a href="#cc_test.srcs">srcs</a>, <a href="#cc_test.data">data</a>, <a href="#cc_test.additional_linker_inputs">additional_linker_inputs</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_test.conlyopts">conlyopts</a>, <a href="#cc_test.copts">copts</a>, <a href="#cc_test.cxxopts">cxxopts</a>, <a href="#cc_test.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#cc_test.dynamic_deps">dynamic_deps</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#test.flaky">flaky</a>, <a href="#cc_test.hdrs_check">hdrs_check</a>, <a href="#cc_test.includes">includes</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_test.link_extra_lib">link_extra_lib</a>, <a href="#cc_test.linkopts">linkopts</a>, <a href="#cc_test.linkshared">linkshared</a>, <a href="#cc_test.linkstatic">linkstatic</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#cc_test.local_defines">local_defines</a>, <a href="#cc_test.malloc">malloc</a>, <a href="#cc_test.module_interfaces">module_interfaces</a>, <a href="#cc_test.nocopts">nocopts</a>, <a href="#cc_test.reexport_deps">reexport_deps</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#cc_test.stamp">stamp</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#cc_test.win_def_file">win_def_file</a>)</pre>
<p>
A <code>cc_test()</code> rule compiles a test. Here, a test
is a binary wrapper around some testing code.
</p>
<p><i>By default, C++ tests are dynamically linked.</i><br/>
To statically link a unit test, specify
<a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary.linkstatic"><code>linkstatic=True</code></a>.
It would probably be good to comment why your test needs
<code>linkstatic</code>; this is probably not obvious.</p>
<h4>Implicit output targets</h4>
<ul>
<li><code><var>name</var>.stripped</code> (only built if explicitly requested): A stripped
version of the binary. <code>strip -g</code> is run on the binary to remove debug
symbols. Additional strip options can be provided on the command line using
<code>--stripopt=-foo</code>.</li>
<li><code><var>name</var>.dwp</code> (only built if explicitly requested): If
<a href="https://gcc.gnu.org/wiki/DebugFission">Fission</a> is enabled: a debug
information package file suitable for debugging remotely deployed binaries. Else: an
empty file.</li>
</ul>
<p>
See the <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary_args">cc_binary()</a> arguments, except that
the <code>stamp</code> argument is set to 0 by default for tests and
that <code>cc_test</code> has extra <a href="/versions/8.1.0/reference/be/common-definitions#common-attributes-tests">
attributes common to all test rules (*_test)</a>.</p>
<h3 id="cc_test_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_test.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="cc_test.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of other libraries to be linked in to the binary target.
<p>These can be <code>cc_library</code> or <code>objc_library</code>
targets.</p>
It is also allowed to
put linker scripts (.lds) into deps, and reference them in
<a href="#cc_binary.linkopts">linkopts</a>.
</td>
</tr>
<tr>
<td id="cc_test.srcs">
<code>srcs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of C and C++ files that are processed to create the library target.
These are C/C++ source and header files, either non-generated (normal source
code) or generated.
<p>All <code>.cc</code>, <code>.c</code>, and <code>.cpp</code> files will
be compiled. These might be generated files: if a named file is in
the <code>outs</code> of some other rule, this <code>cc_library</code>
will automatically depend on that other rule.
</p>
<p>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.
</p>
<p>A <code>.h</code> file will not be compiled, but will be available for
inclusion by sources in this rule. Both <code>.cc</code> and
<code>.h</code> files can directly include headers listed in
these <code>srcs</code> or in the <code>hdrs</code> of this rule or any
rule listed in the <code>deps</code> argument.
</p>
<p>All <code>#include</code>d files must be mentioned in the
<code>hdrs</code> attribute of this or referenced <code>cc_library</code>
rules, or they should be listed in <code>srcs</code> if they are private
to this library. See <a href="#hdrs">"Header inclusion checking"</a> for
a more detailed description.
</p>
<p><code>.so</code>, <code>.lo</code>, and <code>.a</code> files are
pre-compiled files. Your library might have these as
<code>srcs</code> if it uses third-party code for which we don't
have source code.
</p>
<p>If the <code>srcs</code> attribute includes the label of another rule,
<code>cc_library</code> will use the output files of that rule as source files to
compile. This is useful for one-off generation of source code (for more than occasional
use, it's better to implement a Starlark rule class and use the <code>cc_common</code>
API)
</p>
<p>
Permitted <code>srcs</code> file types:
</p>
<ul>
<li>C and C++ source files: <code>.c</code>, <code>.cc</code>, <code>.cpp</code>,
<code>.cxx</code>, <code>.c++</code>, <code>.C</code></li>
<li>C and C++ header files: <code>.h</code>, <code>.hh</code>, <code>.hpp</code>,
<code>.hxx</code>, <code>.inc</code>, <code>.inl</code>, <code>.H</code></li>
<li>Assembler with C preprocessor: <code>.S</code></li>
<li>Archive: <code>.a</code>, <code>.pic.a</code></li>
<li>"Always link" library: <code>.lo</code>, <code>.pic.lo</code></li>
<li>Shared library, versioned or unversioned: <code>.so</code>,
<code>.so.<i>version</i></code></li>
<li>Object file: <code>.o</code>, <code>.pic.o</code></li>
</ul>
<p>
... and any rules that produce those files (e.g. <code>cc_embed_data</code>).
Different extensions denote different programming languages in
accordance with gcc convention.
</p>
</td>
</tr>
<tr>
<td id="cc_test.data">
<code>data</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of files needed by this library at runtime.
See general comments about <code>data</code>
at <a href="/versions/8.1.0/reference/be/common-definitions#typical-attributes">Typical attributes defined by
most build rules</a>.
<p>If a <code>data</code> is the name of a generated file, then this
<code>cc_library</code> rule automatically depends on the generating
rule.
</p>
<p>If a <code>data</code> is a rule name, then this
<code>cc_library</code> rule automatically depends on that rule,
and that rule's <code>outs</code> are automatically added to
this <code>cc_library</code>'s data files.
</p>
<p>Your C++ code can access these data files like so:</p>
<pre><code class="lang-starlark">
const std::string path = devtools_build::GetDataDependencyFilepath(
"my/test/data/file");
</code></pre>
</td>
</tr>
<tr>
<td id="cc_test.additional_linker_inputs">
<code>additional_linker_inputs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
Pass these files to the C++ linker command.
<p>
For example, compiled Windows .res files can be provided here to be embedded in
the binary target.
</p>
</td>
</tr>
<tr>
<td id="cc_test.conlyopts">
<code>conlyopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="cc_test.copts">
<code>copts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C/C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
<p>
Each string in this attribute is added in the given order to <code>COPTS</code> before
compiling the binary target. The flags take effect only for compiling this target, not
its dependencies, so be careful about header files included elsewhere.
All paths should be relative to the workspace, not to the current package.
This attribute should not be needed outside of <code>third_party</code>.
</p>
<p>
If the package declares the <a href="/versions/8.1.0/reference/be/functions.html#package.features">feature</a>
<code>no_copts_tokenization</code>, Bourne shell tokenization applies only to strings
that consist of a single "Make" variable.
</p>
</td>
</tr>
<tr>
<td id="cc_test.cxxopts">
<code>cxxopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these options to the C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="cc_test.defines">
<code>defines</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of defines to add to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
Each string, which must consist of a single Bourne shell token,
is prepended with <code>-D</code> 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
<a href="#cc_binary.local_defines"><code>local_defines</code></a> instead.
</td>
</tr>
<tr>
<td id="cc_test.dynamic_deps">
<code>dynamic_deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
These are other <code>cc_shared_library</code> dependencies the current target depends on.
<p>
The <code>cc_shared_library</code> implementation will use the list of
<code>dynamic_deps</code> (transitively, i.e. also the <code>dynamic_deps</code> of the
current target's <code>dynamic_deps</code>) to decide which <code>cc_libraries</code> in
the transitive <code>deps</code> should not be linked in because they are already provided
by a different <code>cc_shared_library</code>.
</td>
</tr>
<tr>
<td id="cc_test.hdrs_check">
<code>hdrs_check</code>
</td>
<td>
<p>String; default is <code>""</code></p>
Deprecated, no-op.
</td>
</tr>
<tr>
<td id="cc_test.includes">
<code>includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of include dirs to be added to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution.
Each string is prepended with the package path and passed to the C++ toolchain for
expansion via the "include_paths" CROSSTOOL feature. A toolchain running on a POSIX system
with typical feature definitions will produce
<code>-isystem path_to_package/include_entry</code>.
This should only be used for third-party libraries that
do not conform to the Google style of writing #include statements.
Unlike <a href="#cc_binary.copts">COPTS</a>, 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 <a href="#cc_binary.copts">COPTS</a> instead.
<p>
The added <code>include</code> paths will include generated files as well as
files in the source tree.
</p>
</td>
</tr>
<tr>
<td id="cc_test.link_extra_lib">
<code>link_extra_lib</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:link_extra_lib"</code></p>
Control linking of extra libraries.
<p>
By default, C++ binaries are linked against <code>//tools/cpp:link_extra_lib</code>,
which by default depends on the label flag <code>//tools/cpp:link_extra_libs</code>.
Without setting the flag, this library is empty by default. Setting the label flag
allows linking optional dependencies, such as overrides for weak symbols, interceptors
for shared library functions, or special runtime libraries (for malloc replacements,
prefer <code>malloc</code> or <code>--custom_malloc</code>). Setting this attribute to
<code>None</code> disables this behaviour.
</p>
</td>
</tr>
<tr>
<td id="cc_test.linkopts">
<code>linkopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Add these flags to the C++ linker command.
Subject to <a href="make-variables.html">"Make" variable</a> substitution,
<a href="common-definitions.html#sh-tokenization">
Bourne shell tokenization</a> and
<a href="common-definitions.html#label-expansion">label expansion</a>.
Each string in this attribute is added to <code>LINKOPTS</code> before
linking the binary target.
<p>
Each element of this list that does not start with <code>$</code> or <code>-</code> is
assumed to be the label of a target in <code>deps</code>. 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 <code>deps</code>.
</p>
</td>
</tr>
<tr>
<td id="cc_test.linkshared">
<code>linkshared</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
Create a shared library.
To enable this attribute, include <code>linkshared=True</code> in your rule. By default
this option is off.
<p>
The presence of this flag means that linking occurs with the <code>-shared</code> flag
to <code>gcc</code>, 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
<a href="#cc_binary">cc_binary</a> rule are only loaded manually by other programs, so
it should not be considered a substitute for the <a href="#cc_library">cc_library</a>
rule. For sake of scalability we recommend avoiding this approach altogether and
simply letting <code>java_library</code> depend on <code>cc_library</code> rules
instead.
</p>
<p>
If you specify both <code>linkopts=['-static']</code> and <code>linkshared=True</code>,
you get a single completely self-contained unit. If you specify both
<code>linkstatic=True</code> and <code>linkshared=True</code>, you get a single, mostly
self-contained unit.
</p>
</td>
</tr>
<tr>
<td id="cc_test.linkstatic">
<code>linkstatic</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
For <a href="/versions/8.1.0/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and
<a href="/versions/8.1.0/reference/be/c-cpp.html#cc_test"><code>cc_test</code></a>: link the binary in static
mode. For <code>cc_library.link_static</code>: see below.
<p>By default this option is on for <code>cc_binary</code> and off for the rest.</p>
<p>
If enabled and this is a binary or test, this option tells the build tool to link in
<code>.a</code>'s instead of <code>.so</code>'s for user libraries whenever possible.
System libraries such as libc (but <i>not</i> the C/C++ runtime libraries,
see below) are still linked dynamically, as are libraries for which
there is no static library. So the resulting executable will still be dynamically
linked, hence only <i>mostly</i> static.
</p>
<p>
There are really three different ways to link an executable:
</p>
<ul>
<li> STATIC with fully_static_link feature, in which everything is linked statically;
e.g. "<code>gcc -static foo.o libbar.a libbaz.a -lm</code>".<br/>
This mode is enabled by specifying <code>fully_static_link</code> in the
<a href="/versions/8.1.0/reference/be/common-definitions#features"><code>features</code></a> attribute.</li>
<li> 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. "<code>gcc foo.o libfoo.a libbaz.a -lm</code>".<br/>
This mode is enabled by specifying <code>linkstatic=True</code>.</li>
<li> DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is
available), e.g. "<code>gcc foo.o libfoo.so libbaz.so -lm</code>".<br/>
This mode is enabled by specifying <code>linkstatic=False</code>.</li>
</ul>
<p>
If the <code>linkstatic</code> attribute or <code>fully_static_link</code> in
<code>features</code> is used outside of <code>//third_party</code>
please include a comment near the rule to explain why.
</p>
<p>
The <code>linkstatic</code> attribute has a different meaning if used on a
<a href="/versions/8.1.0/reference/be/c-cpp.html#cc_library"><code>cc_library()</code></a> rule.
For a C++ library, <code>linkstatic=True</code> indicates that only
static linking is allowed, so no <code>.so</code> will be produced. linkstatic=False does
not prevent static libraries from being created. The attribute is meant to control the
creation of dynamic libraries.
</p>
<p>
There should be very little code built with <code>linkstatic=False</code> in production.
If <code>linkstatic=False</code>, then the build tool will create symlinks to
depended-upon shared libraries in the <code>*.runfiles</code> area.
</p>
</td>
</tr>
<tr>
<td id="cc_test.local_defines">
<code>local_defines</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of defines to add to the compile line.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
Each string, which must consist of a single Bourne shell token,
is prepended with <code>-D</code> and added to the compile command line for this target,
but not to its dependents.
</td>
</tr>
<tr>
<td id="cc_test.malloc">
<code>malloc</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>"@bazel_tools//tools/cpp:malloc"</code></p>
Override the default dependency on malloc.
<p>
By default, C++ binaries are linked against <code>//tools/cpp:malloc</code>,
which is an empty library so the binary ends up using libc malloc.
This label must refer to a <code>cc_library</code>. If compilation is for a non-C++
rule, this option has no effect. The value of this attribute is ignored if
<code>linkshared=True</code> is specified.
</p>
</td>
</tr>
<tr>
<td id="cc_test.module_interfaces">
<code>module_interfaces</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of files are regarded as C++20 Modules Interface.
<p>
C++ Standard has no restriction about module interface file extension
<ul>
<li>Clang use cppm </li>
<li>GCC can use any source file extension </li>
<li>MSVC use ixx </li>
</ul>
</p>
<p>The use is guarded by the flag
<code>--experimental_cpp_modules</code>.</p>
</td>
</tr>
<tr>
<td id="cc_test.nocopts">
<code>nocopts</code>
</td>
<td>
<p>String; default is <code>""</code></p>
Remove matching options from the C++ compilation command.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make" variable</a> substitution.
The value of this attribute is interpreted as a regular expression.
Any preexisting <code>COPTS</code> that match this regular expression
(including values explicitly specified in the rule's <a
href="#cc_binary.copts">copts</a> attribute)
will be removed from <code>COPTS</code> for purposes of compiling this rule.
This attribute should not be needed or used
outside of <code>third_party</code>. The values are not preprocessed
in any way other than the "Make" variable substitution.
</td>
</tr>
<tr>
<td id="cc_test.reexport_deps">
<code>reexport_deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
</td>
</tr>
<tr>
<td id="cc_test.stamp">
<code>stamp</code>
</td>
<td>
<p>Integer; default is <code>0</code></p>
Whether to encode build information into the binary. Possible values:
<ul>
<li>
<code>stamp = 1</code>: Always stamp the build information into the binary, even in
<a href="/versions/8.1.0/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This
setting should be avoided</b>, since it potentially kills remote caching for the
binary and any downstream actions that depend on it.
</li>
<li>
<code>stamp = 0</code>: Always replace build information by constant values. This
gives good build result caching.
</li>
<li>
<code>stamp = -1</code>: Embedding of build information is controlled by the
<a href="/versions/8.1.0/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.
</li>
</ul>
<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p>
</td>
</tr>
<tr>
<td id="cc_test.win_def_file">
<code>win_def_file</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
The Windows DEF file to be passed to linker.
<p>This attribute should only be used when Windows is the target platform.
It can be used to <a href="https://msdn.microsoft.com/en-us/library/d91k01sh.aspx">
export symbols</a> during linking a shared library.</p>
</td>
</tr>
</tbody>
</table>
<h2 id="cc_toolchain">
cc_toolchain
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/cc_toolchain.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_toolchain(<a href="#cc_toolchain.name">name</a>, <a href="#cc_toolchain.all_files">all_files</a>, <a href="#cc_toolchain.ar_files">ar_files</a>, <a href="#cc_toolchain.as_files">as_files</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#cc_toolchain.compiler_files">compiler_files</a>, <a href="#cc_toolchain.compiler_files_without_includes">compiler_files_without_includes</a>, <a href="#cc_toolchain.coverage_files">coverage_files</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#cc_toolchain.dwp_files">dwp_files</a>, <a href="#cc_toolchain.dynamic_runtime_lib">dynamic_runtime_lib</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#cc_toolchain.exec_transition_for_inputs">exec_transition_for_inputs</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#cc_toolchain.libc_top">libc_top</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#cc_toolchain.linker_files">linker_files</a>, <a href="#cc_toolchain.module_map">module_map</a>, <a href="#cc_toolchain.objcopy_files">objcopy_files</a>, <a href="#cc_toolchain.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#cc_toolchain.static_runtime_lib">static_runtime_lib</a>, <a href="#cc_toolchain.strip_files">strip_files</a>, <a href="#cc_toolchain.supports_header_parsing">supports_header_parsing</a>, <a href="#cc_toolchain.supports_param_files">supports_param_files</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#cc_toolchain.toolchain_config">toolchain_config</a>, <a href="#cc_toolchain.toolchain_identifier">toolchain_identifier</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>Represents a C++ toolchain.</p>
<p>
This rule is responsible for:
<ul>
<li>
Collecting all artifacts needed for C++ actions to run. This is done by
attributes such as <code>all_files</code>, <code>compiler_files</code>,
<code>linker_files</code>, or other attributes ending with <code>_files</code>). These are
most commonly filegroups globbing all required files.
</li>
<li>
Generating correct command lines for C++ actions. This is done using
<code>CcToolchainConfigInfo</code> provider (details below).
</li>
</ul>
</p>
<p>
Use <code>toolchain_config</code> attribute to configure the C++ toolchain.
See also this
<a href="https://bazel.build/versions/8.1.0/docs/cc-toolchain-config-reference">
page
</a> for elaborate C++ toolchain configuration and toolchain selection documentation.
</p>
<p>
Use <code>tags = ["manual"]</code> in order to prevent toolchains from being built and configured
unnecessarily when invoking <code>bazel build //...</code>
</p>
<h3 id="cc_toolchain_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_toolchain.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="cc_toolchain.all_files">
<code>all_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
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 <code>all_files</code> is a superset
of all other artifact-providing attributes (e.g. linkstamp compilation needs both compile
and link files, so it takes <code>all_files</code>).
<p>
This is what <code>cc_toolchain.files</code> contains, and this is used by all Starlark
rules using C++ toolchain.</p>
</td>
</tr>
<tr>
<td id="cc_toolchain.ar_files">
<code>ar_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Collection of all cc_toolchain artifacts required for archiving actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.as_files">
<code>as_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Collection of all cc_toolchain artifacts required for assembly actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.compiler_files">
<code>compiler_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Collection of all cc_toolchain artifacts required for compile actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.compiler_files_without_includes">
<code>compiler_files_without_includes</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Collection of all cc_toolchain artifacts required for compile actions in case when
input discovery is supported (currently Google-only).
</td>
</tr>
<tr>
<td id="cc_toolchain.coverage_files">
<code>coverage_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Collection of all cc_toolchain artifacts required for coverage actions. If not specified,
all_files are used.
</td>
</tr>
<tr>
<td id="cc_toolchain.dwp_files">
<code>dwp_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Collection of all cc_toolchain artifacts required for dwp actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.dynamic_runtime_lib">
<code>dynamic_runtime_lib</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Dynamic library artifact for the C++ runtime library (e.g. libstdc++.so).
<p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking
dependencies dynamically.</p>
</td>
</tr>
<tr>
<td id="cc_toolchain.exec_transition_for_inputs">
<code>exec_transition_for_inputs</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
Deprecated. No-op.
</td>
</tr>
<tr>
<td id="cc_toolchain.libc_top">
<code>libc_top</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
A collection of artifacts for libc passed as inputs to compile/linking actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.linker_files">
<code>linker_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Collection of all cc_toolchain artifacts required for linking actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.module_map">
<code>module_map</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Module map artifact to be used for modular builds.
</td>
</tr>
<tr>
<td id="cc_toolchain.objcopy_files">
<code>objcopy_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Collection of all cc_toolchain artifacts required for objcopy actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.output_licenses">
<code>output_licenses</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
</td>
</tr>
<tr>
<td id="cc_toolchain.static_runtime_lib">
<code>static_runtime_lib</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Static library artifact for the C++ runtime library (e.g. libstdc++.a).
<p>This will be used when 'static_link_cpp_runtimes' feature is enabled, and we're linking
dependencies statically.</p>
</td>
</tr>
<tr>
<td id="cc_toolchain.strip_files">
<code>strip_files</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Collection of all cc_toolchain artifacts required for strip actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.supports_header_parsing">
<code>supports_header_parsing</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
Set to True when cc_toolchain supports header parsing actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.supports_param_files">
<code>supports_param_files</code>
</td>
<td>
<p>Boolean; default is <code>True</code></p>
Set to True when cc_toolchain supports using param files for linking actions.
</td>
</tr>
<tr>
<td id="cc_toolchain.toolchain_config">
<code>toolchain_config</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
The label of the rule providing <code>cc_toolchain_config_info</code>.
</td>
</tr>
<tr>
<td id="cc_toolchain.toolchain_identifier">
<code>toolchain_identifier</code>
</td>
<td>
<p>String; default is <code>""</code></p>
The identifier used to match this cc_toolchain with the corresponding
crosstool_config.toolchain.
<p>
Until issue <a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a> is fixed
this is the recommended way of associating <code>cc_toolchain</code> with
<code>CROSSTOOL.toolchain</code>. It will be replaced by the <code>toolchain_config</code>
attribute (<a href="https://github.com/bazelbuild/bazel/issues/5380">#5380</a>).</p>
</td>
</tr>
</tbody>
</table>
<h2 id="cc_toolchain_suite">
cc_toolchain_suite
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/cpp/CcToolchainSuiteRule.java" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">cc_toolchain_suite(<a href="#cc_toolchain_suite.name">name</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>Deprecated: the rule is a no-op and will be removed.
<h3 id="cc_toolchain_suite_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="cc_toolchain_suite.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
</tbody>
</table>
<h2 id="fdo_prefetch_hints">
fdo_prefetch_hints
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_prefetch_hints.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">fdo_prefetch_hints(<a href="#fdo_prefetch_hints.name">name</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#fdo_prefetch_hints.profile">profile</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>Represents an FDO prefetch hints profile that is either in the workspace.
Examples:</p>
<pre><code class="lang-starlark">
fdo_prefetch_hints(
name = "hints",
profile = "//path/to/hints:profile.afdo",
)
</code></pre>
<h3 id="fdo_prefetch_hints_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="fdo_prefetch_hints.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="fdo_prefetch_hints.profile">
<code>profile</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Label of the hints profile. The hints file has the .afdo extension
The label can also point to an fdo_absolute_path_profile rule.
</td>
</tr>
</tbody>
</table>
<h2 id="fdo_profile">
fdo_profile
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/fdo_profile.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">fdo_profile(<a href="#fdo_profile.name">name</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#fdo_profile.memprof_profile">memprof_profile</a>, <a href="#fdo_profile.profile">profile</a>, <a href="#fdo_profile.proto_profile">proto_profile</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>Represents an FDO profile that is in the workspace.
Example:</p>
<pre><code class="lang-starlark">
fdo_profile(
name = "fdo",
profile = "//path/to/fdo:profile.zip",
)
</code></pre>
<h3 id="fdo_profile_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="fdo_profile.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="fdo_profile.memprof_profile">
<code>memprof_profile</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
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.
</td>
</tr>
<tr>
<td id="fdo_profile.profile">
<code>profile</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
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.
</td>
</tr>
<tr>
<td id="fdo_profile.proto_profile">
<code>proto_profile</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
Label of the protobuf profile.
</td>
</tr>
</tbody>
</table>
<h2 id="memprof_profile">
memprof_profile
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/memprof_profile.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">memprof_profile(<a href="#memprof_profile.name">name</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#memprof_profile.profile">profile</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>Represents a MEMPROF profile that is in the workspace.
Example:</p>
<pre><code class="lang-starlark">
memprof_profile(
name = "memprof",
profile = "//path/to/memprof:profile.afdo",
)
</code></pre>
<h3 id="memprof_profile_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="memprof_profile.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="memprof_profile.profile">
<code>profile</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
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.
</td>
</tr>
</tbody>
</table>
<h2 id="propeller_optimize">
propeller_optimize
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/cc/fdo/propeller_optimize.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">propeller_optimize(<a href="#propeller_optimize.name">name</a>, <a href="#propeller_optimize.cc_profile">cc_profile</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#propeller_optimize.ld_profile">ld_profile</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>Represents a Propeller optimization profile in the workspace.
Example:</p>
<pre><code class="lang-starlark">
propeller_optimize(
name = "layout",
cc_profile = "//path:cc_profile.txt",
ld_profile = "//path:ld_profile.txt"
)
</code></pre>
<h3 id="propeller_optimize_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="propeller_optimize.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="propeller_optimize.cc_profile">
<code>cc_profile</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Label of the profile passed to the various compile actions. This file has
the .txt extension.
</td>
</tr>
<tr>
<td id="propeller_optimize.ld_profile">
<code>ld_profile</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; required</p>
Label of the profile passed to the link action. This file has
the .txt extension.
</td>
</tr>
</tbody>
</table>
<!-- Generated footer -->
</body>
</html>