Google Git
Sign in
bazel / bazel / 65799ee08819525e83520e1e60b66a8ba38448f2 / . / docs / versions / 7.5.0 / reference / be / common-definitions.mdx
blob: 1b03c33ef6ea7fa2ccbd3317f2ab46c2047d60c1 [file] [log] [blame]
<html devsite>
<head>
<meta name="project_path" value="/_project.yaml">
<meta name="book_path" value="/versions/7.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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
&quot;exclusive&quot; 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
&quot;exclusive&quot; 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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.0/concepts/labels">labels</a>;
<a href="#configurable-attributes">nonconfigurable</a>;
default is <code><a href="/versions/7.5.0/reference/be/functions.html#package.default_visibility">default_visibility</a></code> from
<a href="/versions/7.5.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.5.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.5.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and
<a href="/versions/7.5.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.5.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and
<a href="/versions/7.5.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.5.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.5.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.5.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.5.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.5.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.5.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and
<a href="/versions/7.5.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.5.0/reference/be/make-variables#predefined_label_variables">$(location)</a> and
<a href="/versions/7.5.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.5.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.5.0/reference/be/general.html#config_setting"><code>config_setting</code></a>
or <a href="/versions/7.5.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.5.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.5.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.5.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.5.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.5.0/concepts/build-ref">BUILD Concept Reference</a>.
</p>
<!-- Generated footer -->
</body>
</html>