| <html devsite> | |
| <head> | |
| <meta name="project_path" value="/_project.yaml"> | |
| <meta name="book_path" value="/versions/8.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.0/reference/be/make-variables">"Make" variable</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.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.3.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.3.0/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and | |
| <a href="/versions/8.3.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.3.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.3.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.3.0/reference/be/make-variables">"Make" variable</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.strip_include_prefix">strip_include_prefix</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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.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_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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.0/reference/be/make-variables">"Make" variable</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.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.3.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.3.0/reference/be/c-cpp.html#cc_binary.malloc"><code>malloc</code></a> | |
| attribute of <a href="/versions/8.3.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.3.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.3.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.3.0/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and | |
| <a href="/versions/8.3.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.3.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.3.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.3.0/reference/be/make-variables">"Make" variable</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.0/reference/be/make-variables">"Make variable"</a> substitution and | |
| <a href="/versions/8.3.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.3.0/reference/be/make-variables">"Make" variable</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.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.3.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.3.0/reference/be/c-cpp.html#cc_binary"><code>cc_binary</code></a> and | |
| <a href="/versions/8.3.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.3.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.3.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.3.0/reference/be/make-variables">"Make" variable</a> substitution and | |
| <a href="/versions/8.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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> |