| <html devsite> | |
| <head> | |
| <meta name="project_path" value="/_project.yaml"> | |
| <meta name="book_path" value="/versions/7.2.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 --> | |
| <h1 class="page-title" id="common-definitions">Common definitions</h1> | |
| {% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm" %} | |
| {% dynamic setvar version "7.2.0" %} | |
| {% dynamic setvar original_path "/reference/be/common-definitions" %} | |
| {% include "_buttons.html" %} | |
| <p>This section defines various terms and concepts that are common to | |
| many functions or build rules. | |
| </p> | |
| <h2>Contents</h2> | |
| <ul> | |
| <li><a href="#sh-tokenization">Bourne shell tokenization</a></li> | |
| <li><a href="#label-expansion">Label Expansion</a></li> | |
| <li><a href="#typical-attributes">Typical attributes defined by most build rules</a></li> | |
| <li><a href="#common-attributes">Attributes common to all build rules</a></li> | |
| <li><a href="#common-attributes-tests">Attributes common to all test rules (*_test)</a></li> | |
| <li><a href="#common-attributes-binaries">Attributes common to all binary rules (*_binary)</a></li> | |
| <li><a href="#configurable-attributes">Configurable attributes</a></li> | |
| <li><a href="#implicit-outputs">Implicit output targets</a></li> | |
| </ul> | |
| <h2 id='sh-tokenization'>Bourne shell tokenization</h2> | |
| <p> | |
| Certain string attributes of some rules are split into multiple | |
| words according to the tokenization rules of the Bourne shell: | |
| unquoted spaces delimit separate words, and single- and | |
| double-quotes characters and backslashes are used to prevent | |
| tokenization. | |
| </p> | |
| <p> | |
| Those attributes that are subject to this tokenization are | |
| explicitly indicated as such in their definitions in this document. | |
| </p> | |
| <p> | |
| Attributes subject to "Make" variable expansion and Bourne shell | |
| tokenization are typically used for passing arbitrary options to | |
| compilers and other tools. Examples of such attributes are | |
| <code>cc_library.copts</code> and <code>java_library.javacopts</code>. | |
| Together these substitutions allow a | |
| single string variable to expand into a configuration-specific list | |
| of option words. | |
| </p> | |
| <h2 id='label-expansion'>Label expansion</h2> | |
| <p> | |
| Some string attributes of a very few rules are subject to label | |
| expansion: if those strings contain a valid label as a | |
| substring, such as <code>//mypkg:target</code>, and that label is a | |
| declared prerequisite of the current rule, it is expanded into the | |
| pathname of the file represented by the | |
| <a href="https://bazel.build/versions/7.2.0/reference/glossary#target">target</a> | |
| <code>//mypkg:target</code>. | |
| </p> | |
| <p> | |
| Example attributes include <code>genrule.cmd</code> and | |
| <code>cc_binary.linkopts</code>. The details may vary significantly in | |
| each case, over such issues as: whether relative labels are | |
| expanded; how labels that expand to multiple files are | |
| treated, etc. Consult the rule attribute documentation for | |
| specifics. | |
| </p> | |
| <h2 id="typical-attributes">Typical attributes defined by most build rules</h2> | |
| <p>This section describes attributes that are defined by many build rules, | |
| but not all. | |
| </p> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th>Attribute</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="typical.data"><code>data</code></td> | |
| <td><a name="common.data"></a> | |
| <p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| <p> | |
| Files needed by this rule at runtime. May list file or rule targets. Generally | |
| allows any target. | |
| </p> | |
| <p> | |
| The default outputs and runfiles of targets in the <code>data</code> attribute | |
| should appear in the <code>*.runfiles</code> area of any executable which is | |
| output by or has a runtime dependency on this target. This may include data | |
| files or binaries used when this target's | |
| <a href="#typical.srcs"><code>srcs</code></a> are executed. See the | |
| <a href="/versions/7.2.0/concepts/dependencies#data-dependencies">data dependencies</a> | |
| section for more information about how to depend on and use data files. | |
| </p> | |
| <p> | |
| New rules should define a <code>data</code> attribute if they process | |
| inputs which might use other inputs at runtime. Rules' implementation functions | |
| must also <a href="https://bazel.build/versions/7.2.0/rules/rules#runfiles">populate the target's | |
| runfiles</a> from the outputs and runfiles of any <code>data</code> attribute, | |
| as well as runfiles from any dependency attribute which provides either | |
| source code or runtime dependencies. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="typical.deps"><code>deps</code></td> | |
| <td><a name="common.deps"></a> | |
| <p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| <p> | |
| Dependencies for this target. Generally should only list rule targets. (Though | |
| some rules permit files to be listed directly in <code>deps</code>, this | |
| should be avoided when possible.) | |
| </p> | |
| <p> | |
| Language-specific rules generally limit the listed targets to those with | |
| specific <a href="https://bazel.build/versions/7.2.0/extending/rules#providers">providers</a>.</p> | |
| <p> | |
| The precise semantics of what it means for a target to depend on another using | |
| <code>deps</code> are specific to the kind of rule, and the rule-specific | |
| documentation goes into more detail. For rules which process source code, | |
| <code>deps</code> generally specifies code dependencies used by the code in | |
| <a href="#typical.srcs"><code>srcs</code></a>. | |
| </p> | |
| <p> | |
| Most often, a <code>deps</code> dependency is used to allow one module to use | |
| symbols defined in another module written in the same programming language and | |
| separately compiled. Cross-language dependencies are also permitted in many | |
| cases: For example, a <code>java_library</code> target may depend on C++ code | |
| in a <code>cc_library</code> target, by listing the latter in the | |
| <code>deps</code> attribute. See the definition of | |
| <a href="/versions/7.2.0/concepts/build-ref#deps">dependencies</a> | |
| for more information. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="typical.licenses"><code>licenses</code></td> | |
| <td><a name="common.licenses"></a> | |
| <p>List of strings; <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code>["none"]</code></p> | |
| <p> | |
| A list of license-type strings to be used for this particular target. | |
| This is part of a deprecated licensing API that Bazel no longer uses. Don't | |
| use this. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="typical.srcs"><code>srcs</code></td> | |
| <td><p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code></p> | |
| <p> | |
| Files processed or included by this rule. Generally lists files directly, but | |
| may list rule targets (like <code>filegroup</code> or <code>genrule</code>) to | |
| include their default outputs. | |
| </p> | |
| <p> | |
| Language-specific rules often require that the listed files have particular | |
| file extensions. | |
| </p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="common-attributes">Attributes common to all build rules</h2> | |
| <p>This section describes attributes that are implicitly added to all build | |
| rules. | |
| </p> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th>Attribute</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="common.compatible_with"><code>compatible_with</code></td> | |
| <td><p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; | |
| <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> | |
| <p> | |
| The list of environments this target can be built for, in addition to | |
| default-supported environments. | |
| </p> | |
| <p> | |
| This is part of Bazel's constraint system, which lets users declare which | |
| targets can and cannot depend on each other. For example, externally deployable | |
| binaries shouldn't depend on libraries with company-secret code. See | |
| <a href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/analysis/constraints/ConstraintSemantics.java#L46"> | |
| ConstraintSemantics</a> for details. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.deprecation"><code>deprecation</code></td> | |
| <td><p>String; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>None</code></p> | |
| <p> | |
| An explanatory warning message associated with this target. | |
| Typically this is used to notify users that a target has become obsolete, | |
| or has become superseded by another rule, is private to a package, or is | |
| perhaps considered harmful for some reason. It is a good idea to include | |
| some reference (like a webpage, a bug number or example migration CLs) so | |
| that one can easily find out what changes are required to avoid the message. | |
| If there is a new target that can be used as a drop in replacement, it is a | |
| good idea to just migrate all users of the old target. | |
| </p> | |
| <p> | |
| This attribute has no effect on the way things are built, but it | |
| may affect a build tool's diagnostic output. The build tool issues a | |
| warning when a rule with a <code>deprecation</code> attribute is | |
| depended upon by a target in another package. | |
| </p> | |
| <p> | |
| Intra-package dependencies are exempt from this warning, so that, | |
| for example, building the tests of a deprecated rule does not | |
| encounter a warning. | |
| </p> | |
| <p> | |
| If a deprecated target depends on another deprecated target, no warning | |
| message is issued. | |
| </p> | |
| <p> | |
| Once people have stopped using it, the target can be removed. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.distribs"><code>distribs</code></td> | |
| <td><p>List of strings; <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code>[]</code></p> | |
| <p> | |
| A list of distribution-method strings to be used for this particular target. | |
| This is part of a deprecated licensing API that Bazel no longer uses. Don't | |
| use this. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.exec_compatible_with"><code>exec_compatible_with</code></td> | |
| <td><p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; | |
| <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code> | |
| </p> | |
| <p> | |
| A list of | |
| <code><a href="platform.html#constraint_value">constraint_values</a></code> | |
| that must be present in the execution platform for this target. This is in | |
| addition to any constraints already set by the rule type. Constraints are used | |
| to restrict the list of available execution platforms. For more details, see | |
| the description of | |
| <a href="/versions/7.2.0/docs/toolchains#toolchain-resolution">toolchain resolution</a>. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.exec_properties"><code>exec_properties</code></td> | |
| <td><p>Dictionary of strings; default is <code>{}</code></p> | |
| <p> A dictionary of strings that will be added to the <code>exec_properties</code> of a platform selected for this target. See <code>exec_properties</code> of the <a href="platform.html">platform</a> rule.</p> | |
| <p>If a key is present in both the platform and target-level properties, the value will be taken from the target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.features"><code>features</code></td> | |
| <td><p>List of <i>feature</i> strings; default is <code>[]</code></p> | |
| <p>A feature is string tag that can be enabled or disabled on a target. The | |
| meaning of a feature depends on the rule itself.</p> | |
| <p>This <code>features</code> attribute is combined with the <a href="/versions/7.2.0/reference/be/functions.html#package"> | |
| package</a> level <code>features</code> attribute. For example, if | |
| the features ["a", "b"] are enabled on the package level, and a target's | |
| <code>features</code> attribute contains ["-a", "c"], the features enabled for the | |
| rule will be "b" and "c". | |
| <a href="https://github.com/bazelbuild/examples/blob/main/rules/features/BUILD"> | |
| See example</a>. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.restricted_to"><code>restricted_to</code></td> | |
| <td><p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; | |
| <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> | |
| <p> | |
| The list of environments this target can be built for, <i>instead</i> of | |
| default-supported environments. | |
| </p> | |
| <p> | |
| This is part of Bazel's constraint system. See | |
| <code><a href="#common.compatible_with">compatible_with</a></code> | |
| for details. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.tags"><code>tags</code></td> | |
| <td><p> | |
| List of strings; <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code>[]</code> | |
| </p> | |
| <p> | |
| <i>Tags</i> can be used on any rule. <i>Tags</i> on test and | |
| <code>test_suite</code> rules are useful for categorizing the tests. | |
| <i>Tags</i> on non-test targets are used to control sandboxed execution of | |
| <code>genrule</code>s and | |
| <a href="/versions/7.2.0/rules/concepts">Starlark</a> | |
| actions, and for parsing by humans and/or external tools. | |
| </p> | |
| <p> | |
| Bazel modifies the behavior of its sandboxing code if it finds the following | |
| keywords in the <code>tags</code> attribute of any test or <code>genrule</code> | |
| target, or the keys of <code>execution_requirements</code> for any Starlark | |
| action. | |
| </p> | |
| <ul> | |
| <li><code>no-sandbox</code> keyword results in the action or test never being | |
| sandboxed; it can still be cached or run remotely - use <code>no-cache</code> | |
| or <code>no-remote</code> to prevent either or both of those. | |
| </li> | |
| <li><code>no-cache</code> keyword results in the action or test never being | |
| cached (remotely or locally) | |
| </li> | |
| <li><code>no-remote-cache</code> keyword results in the action or test never being | |
| cached remotely (but it may be cached locally; it may also be executed remotely). | |
| Note: for the purposes of this tag, the disk-cache is considered a local cache, whereas | |
| the http and gRPC caches are considered remote. | |
| If a combination of local disk cache and remote cache are used (combined cache), | |
| it's treated as a remote cache and disabled entirely unless <code>--incompatible_remote_results_ignore_disk</code> | |
| is set in which case the local components will be used. | |
| </li> | |
| <li><code>no-remote-exec</code> keyword results in the action or test never being | |
| executed remotely (but it may be cached remotely). | |
| </li> | |
| <li><code>no-remote</code> keyword prevents the action or test from being executed remotely or | |
| cached remotely. This is equivalent to using both | |
| <code>no-remote-cache</code> and <code>no-remote-exec</code>. | |
| </li> | |
| <li><code>no-remote-cache-upload</code> keyword disables upload part of remote caching of a spawn. | |
| it does not disable remote execution. | |
| </li> | |
| <li><code>local</code> keyword precludes the action or test from being remotely cached, | |
| remotely executed, or run inside the sandbox. | |
| For genrules and tests, marking the rule with the <code>local = True</code> | |
| attribute has the same effect. | |
| </li> | |
| <li><code>requires-network</code> keyword allows access to the external | |
| network from inside the sandbox. This tag only has an effect if sandboxing | |
| is enabled. | |
| </li> | |
| <li><code>block-network</code> keyword blocks access to the external | |
| network from inside the sandbox. In this case, only communication | |
| with localhost is allowed. This tag only has an effect if sandboxing is | |
| enabled. | |
| </li> | |
| <li><code>requires-fakeroot</code> runs the test or action as uid and gid 0 (i.e., the root | |
| user). This is only supported on Linux. This tag takes precedence over the | |
| <code class='flag'>--sandbox_fake_username</code> command-line option. | |
| </li> | |
| </ul> | |
| <p> | |
| <i>Tags</i> on tests are generally used to annotate a test's role in your | |
| debug and release process. Typically, tags are most useful for C++ and Python | |
| tests, which lack any runtime annotation ability. The use of tags and size | |
| elements gives flexibility in assembling suites of tests based around codebase | |
| check-in policy. | |
| </p> | |
| <p> | |
| Bazel modifies test running behavior if it finds the following keywords in the | |
| <code>tags</code> attribute of the test rule: | |
| </p> | |
| <ul> | |
| <li><code>exclusive</code> will force the test to be run in the | |
| "exclusive" mode, ensuring that no other tests are running at the | |
| same time. Such tests will be executed in serial fashion after all build | |
| activity and non-exclusive tests have been completed. Remote execution is | |
| disabled for such tests because Bazel doesn't have control over what's | |
| running on a remote machine. | |
| </li> | |
| <li><code>exclusive-if-local</code> will force the test to be run in the | |
| "exclusive" mode if it is executed locally, but will run the test in parallel if it's | |
| executed remotely. | |
| </li> | |
| <li><code>manual</code> keyword will exclude the target from expansion of target pattern wildcards | |
| (<code>...</code>, <code>:*</code>, <code>:all</code>, etc.) and <code>test_suite</code> rules | |
| which do not list the test explicitly when computing the set of top-level targets to build/run | |
| for the <code>build</code>, <code>test</code>, and <code>coverage</code> commands. It does not | |
| affect target wildcard or test suite expansion in other contexts, including the | |
| <code>query</code> command. Note that <code>manual</code> does not imply that a target should | |
| not be built/run automatically by continuous build/test systems. For example, it may be | |
| desirable to exclude a target from <code>bazel test ...</code> because it requires specific | |
| Bazel flags, but still have it included in properly-configured presubmit or continuous test | |
| runs. | |
| </li> | |
| <li><code>external</code> keyword will force test to be unconditionally | |
| executed (regardless of <code class='flag'>--cache_test_results</code> | |
| value). | |
| </li> | |
| </ul> | |
| See | |
| <a href="/versions/7.2.0/reference/test-encyclopedia#tag-conventions">Tag Conventions</a> | |
| in the Test Encyclopedia for more conventions on tags attached to test targets. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.target_compatible_with"><code>target_compatible_with</code></td> | |
| <td><p> | |
| List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code> | |
| </p> | |
| <p> | |
| A list of | |
| <code><a href="platform.html#constraint_value">constraint_value</a></code>s | |
| that must be present in the target platform for this target to be considered | |
| <em>compatible</em>. This is in addition to any constraints already set by the | |
| rule type. If the target platform does not satisfy all listed constraints then | |
| the target is considered <em>incompatible</em>. Incompatible targets are | |
| skipped for building and testing when the target pattern is expanded | |
| (e.g. <code>//...</code>, <code>:all</code>). When explicitly specified on the | |
| command line, incompatible targets cause Bazel to print an error and cause a | |
| build or test failure. | |
| </p> | |
| <p> | |
| Targets that transitively depend on incompatible targets are themselves | |
| considered incompatible. They are also skipped for building and testing. | |
| </p> | |
| <p> | |
| An empty list (which is the default) signifies that the target is compatible | |
| with all platforms. | |
| <p> | |
| <p> | |
| All rules other than <a href="workspace.html">Workspace Rules</a> support this | |
| attribute. | |
| For some rules this attribute has no effect. For example, specifying | |
| <code>target_compatible_with</code> for a | |
| <code><a href="c-cpp.html#cc_toolchain">cc_toolchain</a></code> is not useful. | |
| <p> | |
| <p> | |
| See the | |
| <a href="/versions/7.2.0/docs/platforms#skipping-incompatible-targets">Platforms</a> | |
| page for more information about incompatible target skipping. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.testonly"><code>testonly</code></td> | |
| <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; default is <code>False</code> | |
| except for test and test suite targets</p> | |
| <p> | |
| If <code>True</code>, only testonly targets (such as tests) can depend on this target. | |
| </p> | |
| <p> | |
| Equivalently, a rule that is not <code>testonly</code> is not allowed to | |
| depend on any rule that is <code>testonly</code>. | |
| </p> | |
| <p> | |
| Tests (<code>*_test</code> rules) | |
| and test suites (<a href="/versions/7.2.0/reference/be/general.html#test_suite">test_suite</a> rules) | |
| are <code>testonly</code> by default. | |
| </p> | |
| <p> | |
| This attribute is intended to mean that the target should not be | |
| contained in binaries that are released to production. | |
| </p> | |
| <p> | |
| Because testonly is enforced at build time, not run time, and propagates | |
| virally through the dependency tree, it should be applied judiciously. For | |
| example, stubs and fakes that | |
| are useful for unit tests may also be useful for integration tests | |
| involving the same binaries that will be released to production, and | |
| therefore should probably not be marked testonly. Conversely, rules that | |
| are dangerous to even link in, perhaps because they unconditionally | |
| override normal behavior, should definitely be marked testonly. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.toolchains"><code>toolchains</code></td> | |
| <td><p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; | |
| <a href="#configurable-attributes">nonconfigurable</a>; default is <code>[]</code></p> | |
| <p> | |
| The set of targets whose <a href="/versions/7.2.0/reference/be/make-variables">Make variables</a> this target is | |
| allowed to access. These targets are either instances of rules that provide | |
| <code>TemplateVariableInfo</code> or special targets for toolchain types built into Bazel. These | |
| include: | |
| <ul> | |
| <li><code>@bazel_tools//tools/cpp:current_cc_toolchain</code> | |
| <li><code>@bazel_tools//tools/jdk:current_java_runtime</code> | |
| </ul> | |
| <p> | |
| Note that this is distinct from the concept of | |
| <a href="/versions/7.2.0/docs/toolchains#toolchain-resolution">toolchain resolution</a> | |
| that is used by rule implementations for platform-dependent configuration. You cannot use this | |
| attribute to determine which specific <code>cc_toolchain</code> or <code>java_toolchain</code> a | |
| target will use. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="common.visibility"><code>visibility</code></td> | |
| <td><p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; | |
| <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code><a href="/versions/7.2.0/reference/be/functions.html#package.default_visibility">default_visibility</a></code> from | |
| <a href="/versions/7.2.0/reference/be/functions.html#package">package</a> if specified, or <code>"//visibility:private"</code> | |
| otherwise</p> | |
| <p> | |
| The <code>visibility</code> attribute on a target controls whether the target | |
| can be used in other packages. See the documentation for | |
| <a href="/versions/7.2.0/concepts/visibility">visibility</a>. | |
| </p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="common-attributes-tests">Attributes common to all test rules (*_test)</h2> | |
| <p>This section describes attributes that are common to all test rules.</p> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th>Attribute</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="test.args"><code>args</code></td> | |
| <td><p>List of strings; subject to | |
| <a href="/versions/7.2.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and | |
| <a href="/versions/7.2.0/reference/be/make-variables">"Make variable"</a> substitution, and | |
| <a href="#sh-tokenization">Bourne shell tokenization</a>; default is <code>[]</code></p> | |
| <p>Command line arguments that Bazel passes to the target when it is | |
| executed with <code>bazel test</code>. | |
| <p> | |
| These arguments are passed before any <code>--test_arg</code> values | |
| specified on the <code>bazel test</code> command line. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="test.env"><code>env</code></td> | |
| <td><p> | |
| Dictionary of strings; values are subject to | |
| <a href="/versions/7.2.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and | |
| <a href="/versions/7.2.0/reference/be/make-variables">"Make variable"</a> substitution; default is <code>[]</code> | |
| </p> | |
| <p> | |
| Specifies additional environment variables to set when the test is executed by | |
| <code>bazel test</code>. | |
| </p> | |
| <p> | |
| This attribute only applies to native rules, like <code>cc_test</code>, | |
| <code>py_test</code>, and <code>sh_test</code>. It does not apply to | |
| Starlark-defined test rules. For your own Starlark rules, you can add an "env" | |
| attribute and use it to populate a | |
| <a href="/versions/7.2.0/rules/lib/toplevel/testing#TestEnvironment">TestEnvironment</a> | |
| Provider. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="test.env_inherit"><code>env_inherit</code></td> | |
| <td><p>List of strings; default is <code>[]</code></p> | |
| <p>Specifies additional environment variables to inherit from the | |
| external environment when the test is executed by <code>bazel test</code>. | |
| </p> | |
| <p> | |
| This attribute only applies to native rules, like <code>cc_test</code>, <code>py_test</code>, | |
| and <code>sh_test</code>. It does not apply to Starlark-defined test rules. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="test.size"><code>size</code></td> | |
| <td><p>String <code>"enormous"</code>, <code>"large"</code>, <code>"medium"</code>, or | |
| <code>"small"</code>; <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code>"medium"</code></p> | |
| <p>Specifies a test target's "heaviness": how much time/resources it needs to run.</p> | |
| <p>Unit tests are considered "small", integration tests "medium", and end-to-end tests "large" or | |
| "enormous". Bazel uses the size to determine a default timeout, which can be overridden using the | |
| <code>timeout</code> attribute. The timeout is for all tests in the BUILD target, not for each | |
| individual test. When the test is run locally, the <code>size</code> is additionally used for | |
| scheduling purposes: Bazel tries to respect <code>--local_{ram,cpu}_resources</code> and not | |
| overwhelm the local machine by running lots of heavy tests at the same time.</p> | |
| <p>Test sizes correspond to the following default timeouts and assumed peak local resource | |
| usages:</p> | |
| <table style="width: 100%"> | |
| <tr> | |
| <th>Size</th> | |
| <th>RAM (in MB)</th> | |
| <th>CPU (in CPU cores)</th> | |
| <th>Default timeout</th> | |
| </tr> | |
| <tr> | |
| <td>small</td> | |
| <td>20</td> | |
| <td>1</td> | |
| <td>short (1 minute)</td> | |
| </tr> | |
| <tr> | |
| <td>medium</td> | |
| <td>100</td> | |
| <td>1</td> | |
| <td>moderate (5 minutes)</td> | |
| </tr> | |
| <tr> | |
| <td>large</td> | |
| <td>300</td> | |
| <td>1</td> | |
| <td>long (15 minutes)</td> | |
| </tr> | |
| <tr> | |
| <td>enormous</td> | |
| <td>800</td> | |
| <td>1</td> | |
| <td>eternal (60 minutes)</td> | |
| </tr> | |
| </table> | |
| <p>The environment variable <code> | |
| <a href="/versions/7.2.0/reference/test-encyclopedia#initial-conditions">TEST_SIZE</a> | |
| </code> will be set to the | |
| value of this attribute when spawning the test.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="test.timeout"><code>timeout</code></td> | |
| <td><p>String <code>"short"</code>, <code>"moderate"</code>, <code>"long"</code>, or | |
| <code>"eternal"</code>; <a href="#configurable-attributes">nonconfigurable</a>; default is derived | |
| from the test's <code>size</code> attribute</code></p> | |
| <p> | |
| How long the test is expected to run before returning. | |
| </p> | |
| <p> | |
| While a test's size attribute controls resource estimation, a test's | |
| timeout may be set independently. If not explicitly specified, the | |
| timeout is based on the <a href="#test.size">test's size</a>. The test | |
| timeout can be overridden with the <code>--test_timeout</code> flag, e.g. for | |
| running under certain conditions which are known to be slow. Test timeout values | |
| correspond to the following time periods: | |
| </p> | |
| <table style="width: 100%"> | |
| <tr> | |
| <th>Timeout Value</th> | |
| <th>Time Period</th> | |
| </tr> | |
| <tr> | |
| <td>short</td> | |
| <td>1 minute</td> | |
| </tr> | |
| <tr> | |
| <td>moderate</td> | |
| <td>5 minutes</td> | |
| </tr> | |
| <tr> | |
| <td>long</td> | |
| <td>15 minutes</td> | |
| </tr> | |
| <tr> | |
| <td>eternal</td> | |
| <td>60 minutes</td> | |
| </tr> | |
| </table> | |
| <p> | |
| For times other than the above, the test timeout can be overridden with the | |
| <code>--test_timeout</code> bazel flag, e.g. for manually running under | |
| conditions which are known to be slow. The <code>--test_timeout</code> values | |
| are in seconds. For example <code>--test_timeout=120</code> will set the test | |
| timeout to two minutes. | |
| </p> | |
| <p>The environment variable <code> | |
| <a href="/versions/7.2.0/reference/test-encyclopedia#initial-conditions">TEST_TIMEOUT</a> | |
| </code> will be set to the test timeout (in seconds) when spawning the test.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="test.flaky"><code>flaky</code></td> | |
| <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code>False</code></p> | |
| <p> | |
| Marks test as flaky. | |
| </p> | |
| <p> | |
| If set, executes the test up to three times, marking it as failed only if it | |
| fails each time. By default, this attribute is set to False and the test is | |
| executed only once. Note, that use of this attribute is generally discouraged - | |
| tests should pass reliably when their assertions are upheld. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="test.shard_count"><code>shard_count</code></td> | |
| <td><p>Non-negative integer less than or equal to 50; default is <code>-1</code></p> | |
| <p>Specifies the number of parallel shards | |
| to use to run the test.</p> | |
| <p>If set, this value will override any heuristics used to determine the number of | |
| parallel shards with which to run the test. Note that for some test | |
| rules, this parameter may be required to enable sharding | |
| in the first place. Also see <code>--test_sharding_strategy</code>.</p> | |
| <p>If test sharding is enabled, the environment variable <code> | |
| <a href="/versions/7.2.0/reference/test-encyclopedia#initial-conditions">TEST_TOTAL_SHARDS</a> | |
| </code> will be set to this value when spawning the test.</p> | |
| <p>Sharding requires the test runner to support the test sharding protocol. | |
| If it does not, then it will most likely run every test in every shard, which | |
| is not what you want.</p> | |
| <p>See | |
| <a href="/versions/7.2.0/reference/test-encyclopedia#test-sharding">Test Sharding</a> | |
| in the Test Encyclopedia for details on sharding.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="test.local"><code>local</code></td> | |
| <td><p>Boolean; <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code>False</code></p> | |
| <p>Forces the test to be run locally, without sandboxing.</p> | |
| <p>Setting this to True is equivalent to providing "local" as a tag | |
| (<code>tags=["local"]</code>).</p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="common-attributes-binaries">Attributes common to all binary rules (*_binary)</h2> | |
| <p>This section describes attributes that are common to all binary rules.</p> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th>Attribute</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="binary.args"><code>args</code></td> | |
| <td><p> | |
| List of strings; subject to | |
| <a href="/versions/7.2.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and | |
| <a href="/versions/7.2.0/reference/be/make-variables">"Make variable"</a> substitution, and | |
| <a href="#sh-tokenization">Bourne shell tokenization</a>; | |
| <a href="#configurable-attributes">nonconfigurable</a>; | |
| default is <code>[]</code> | |
| </p> | |
| <p> | |
| Command line arguments that Bazel will pass to the target when it is executed | |
| either by the <code>run</code> command or as a test. These arguments are | |
| passed before the ones that are specified on the <code>bazel run</code> or | |
| <code>bazel test</code> command line. | |
| </p> | |
| <p> | |
| <em class="harmful">NOTE: The arguments are not passed when you run the target | |
| outside of Bazel (for example, by manually executing the binary in | |
| <code>bazel-bin/</code>).</em> | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="binary.env"><code>env</code></td> | |
| <td><p>Dictionary of strings; values are subject to | |
| <a href="/versions/7.2.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and | |
| <a href="/versions/7.2.0/reference/be/make-variables">"Make variable"</a> substitution; default is <code>{}</code></p> | |
| <p>Specifies additional environment variables to set when the target is | |
| executed by <code>bazel run</code>. | |
| </p> | |
| <p> | |
| This attribute only applies to native rules, like <code>cc_binary</code>, <code>py_binary</code>, | |
| and <code>sh_binary</code>. It does not apply to Starlark-defined executable rules. | |
| </p> | |
| <p> | |
| <em class="harmful">NOTE: The environment variables are not set when you run the target | |
| outside of Bazel (for example, by manually executing the binary in | |
| <code>bazel-bin/</code>).</em> | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="binary.output_licenses"><code>output_licenses</code></td> | |
| <td><p>List of strings; default is <code>[]</code></p> | |
| <p> | |
| The licenses of the output files that this binary generates. | |
| This is part of a deprecated licensing API that Bazel no longer uses. Don't | |
| use this. | |
| </p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="configurable-attributes">Configurable attributes</h2> | |
| <p> | |
| Most attributes are "configurable", meaning that their values may change when | |
| the target is built in different ways. Specifically, configurable attributes | |
| may vary based on the flags passed to the Bazel command line, or what | |
| downstream dependency is requesting the target. This can be used, for | |
| instance, to customize the target for multiple platforms or compilation modes. | |
| </p> | |
| <p> | |
| The following example declares different sources for different target | |
| architectures. Running <code>bazel build :multiplatform_lib --cpu x86</code> | |
| will build the target using <code>x86_impl.cc</code>, while substituting | |
| <code>--cpu arm</code> will instead cause it to use <code>arm_impl.cc</code>. | |
| </p> | |
| <pre class="code"> | |
| cc_library( | |
| name = "multiplatform_lib", | |
| srcs = select({ | |
| ":x86_mode": ["x86_impl.cc"], | |
| ":arm_mode": ["arm_impl.cc"] | |
| }) | |
| ) | |
| config_setting( | |
| name = "x86_mode", | |
| values = { "cpu": "x86" } | |
| ) | |
| config_setting( | |
| name = "arm_mode", | |
| values = { "cpu": "arm" } | |
| ) | |
| </pre> | |
| <p> | |
| The <a href="/versions/7.2.0/reference/be/functions.html#select"><code>select()</code></a> function | |
| chooses among different alternative values for a configurable attribute based | |
| on which <a href="/versions/7.2.0/reference/be/general.html#config_setting"><code>config_setting</code></a> | |
| or <a href="/versions/7.2.0/reference/be/platforms-and-toolchains.html#constraint_value"><code>constraint_value</code></a> | |
| criteria the target's configuration satisfies. | |
| </p> | |
| <p> | |
| Bazel evaluates configurable attributes after processing macros and before | |
| processing rules (technically, between the | |
| <a href="https://bazel.build/versions/7.2.0/rules/concepts#evaluation-model"> | |
| loading and analysis phases</a>). | |
| Any processing before <code>select()</code> evaluation doesn't know which | |
| branch the <code>select()</code> chooses. Macros, for example, can't change | |
| their behavior based on the chosen branch, and <code>bazel query</code> can | |
| only make conservative guesses about a target's configurable dependencies. See | |
| <a href="https://bazel.build/versions/7.2.0/docs/configurable-attributes#faq"> | |
| this FAQ</a> | |
| for more on using <code>select()</code> with rules and macros. | |
| </p> | |
| <p> | |
| Attributes marked <code>nonconfigurable</code> in their documentation cannot | |
| use this feature. Usually an attribute is nonconfigurable because Bazel | |
| internally needs to know its value before it can determine how to resolve a | |
| <code>select()</code>. | |
| </p> | |
| <p> | |
| See <a href="https://bazel.build/versions/7.2.0/docs/configurable-attributes"> | |
| Configurable Build Attributes</a> for a detailed overview. | |
| </p> | |
| <h2 id="implicit-outputs">Implicit output targets</h2> | |
| <p> | |
| <i>Implicit outputs in C++ are deprecated. Please refrain from using it | |
| in other languages where possible. We don't have a deprecation path yet | |
| but they will eventually be deprecated too.</i> | |
| </p> | |
| <p>When you define a build rule in a BUILD file, you are explicitly | |
| declaring a new, named rule target in a package. Many build rule | |
| functions also <i>implicitly</i> entail one or more output file | |
| targets, whose contents and meaning are rule-specific. | |
| For example, when you explicitly declare a | |
| <code>java_binary(name='foo', ...)</code> rule, you are also | |
| <i>implicitly</i> declaring an output file | |
| target <code>foo_deploy.jar</code> as a member of the same package. | |
| (This particular target is a self-contained Java archive suitable | |
| for deployment.) | |
| </p> | |
| <p> | |
| Implicit output targets are first-class members of the global | |
| target graph. Just like other targets, they are built on demand, | |
| either when specified in the top-level built command, or when they | |
| are necessary prerequisites for other build targets. They can be | |
| referenced as dependencies in BUILD files, and can be observed in | |
| the output of analysis tools such as <code>bazel query</code>. | |
| </p> | |
| <p> | |
| For each kind of build rule, the rule's documentation contains a | |
| special section detailing the names and contents of any implicit | |
| outputs entailed by a declaration of that kind of rule. | |
| </p> | |
| <p> | |
| An important but somewhat subtle distinction between the | |
| two namespaces used by the build system: | |
| <a href="/versions/7.2.0/concepts/labels">labels</a> identify <em>targets</em>, | |
| which may be rules or files, and file targets may be divided into | |
| either source (or input) file targets and derived (or output) file | |
| targets. These are the things you can mention in BUILD files, | |
| build from the command-line, or examine using <code>bazel query</code>; | |
| this is the <em>target namespace</em>. Each file target corresponds | |
| to one actual file on disk (the "file system namespace"); each rule | |
| target may correspond to zero, one or more actual files on disk. | |
| There may be files on disk that have no corresponding target; for | |
| example, <code>.o</code> object files produced during C++ compilation | |
| cannot be referenced from within BUILD files or from the command line. | |
| In this way, the build tool may hide certain implementation details of | |
| how it does its job. This is explained more fully in | |
| the <a href="/versions/7.2.0/concepts/build-ref">BUILD Concept Reference</a>. | |
| </p> | |
| <!-- Generated footer --> | |
| </body> | |
| </html> |