Common definitions
This section defines various terms and concepts that are common to many functions or build rules below.
Contents
Bourne shell tokenization
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.
Those attributes that are subject to this tokenization are explicitly indicated as such in their definitions in this document.
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
cc_library.copts and java_library.javacopts.
Together these substitutions allow a
single string variable to expand into a configuration-specific list
of option words.
Label expansion
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 //mypkg:target, and that label is a
declared prerequisite of the current rule, it is expanded into the
pathname of the file represented by the target //mypkg:target.
Example attributes include genrule.cmd and
cc_binary.linkopts. 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.
Attributes common to all build rules
This section describes attributes that are common to all build rules.
Please note that it is an error to list the same label twice in a list of
labels attribute.
| Attribute | Description |
|---|---|
features |
Features on a rule modify the features currently enabled on
the package level via the features attribute. |
licenses |
A list of license-type strings to be used for this particular build rule.
Overrides the |
data |
The list of files needed by this rule at runtime.
Targets named in the
Almost all rules permit a |
visibility |
The There are five forms (and one temporary form) a visibility label can take:
The visibility specifications of
If a rule does not specify the visibility attribute,
the If the default visibility for the package is not specified, the rule is private. Example:
File
# This rule is visible to everyone
cc_binary(
name = "executable",
visibility = ["//visibility:public"],
deps = [":library"],
)
# This rule is visible only to rules declared in the same package
cc_library(
name = "library",
visibility = ["//visibility:private"],
)
# This rule is visible to rules in package //object and //noun
cc_library(
name = "subject",
visibility = [
"//noun:__pkg__",
"//object:__pkg__",
],
)
# See package group "//frobber:friends" (below) for who can
# access this rule.
cc_library(
name = thingy,
visibility = ["//frobber:friends"],
)
File
# This is the package group declaration to which rule
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
name = "friends",
packages = [
"//fribber/...",
"//frobber",
],
)
|
compatible_with |
The list of environments this rule can be built for, in addition to default-supported environments. This is part of Bazel's soft-launched constraint system, which lets users declare which rules can and cannot depend on each other. For example, externally deployable binaries shouldn't depend on libraries with company-secret code. See ConstraintSemantics for details. |
distribs |
A list of distribution-method strings to be used for this particular build rule.
Overrides the |
toolchains |
The set of toolchains this rule has access to. Targets listed here are the set of toolchains whose Make variables the rule is allowed to access. These rules are either rules that provide theTemplateVariableInfo provider or special targets for toolchain types built into
Bazel. These include:
|
deps |
A list of dependencies of this rule.
The precise semantics of what it means for this rule to depend on
another using
Most often, a
Almost all rules permit a |
deprecation |
An explanatory warning message associated with this rule. Typically this is used to notify users that a rule 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.
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 Intra-package dependencies are exempt from this warning, so that, for example, building the tests of a deprecated rule does not encounter a warning. If a deprecated rule depends on another deprecated rule, no warning message is issued. Once people have stopped using it, the package can be removed. |
restricted_to |
The list of environments this rule can be built for, instead of default-supported environments.
This is part of Bazel's soft-launched constraint system. See
|
tags |
Tags can be used on any rule. Tags on test and
Bazel modifies the behavior of its sandboxing code if it finds the following
keywords in the
Tags 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.
Bazel modifies test running behavior if it finds the following keywords in the
|
testonly |
If True, only testonly targets (such as tests) can depend on this target.
Equivalently, a rule that is not
Tests ( This attribute is intended to mean that the target should not be contained in binaries that are released to production. 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. |
Attributes common to all test rules (*_test)
This section describes attributes that are common to all test rules.
| Attribute | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Add these arguments to the
These arguments are passed before the |
||||||||||||||||||||
size |
How "heavy" the test is. A classification of the test's "heaviness": how much time/resources it needs to run. Unittests 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
|
||||||||||||||||||||
timeout |
How long the test is expected to run before returning.
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 test's size. The test
timeout can be overridden with the
--test_timeout bazel flag, e.g. for manually running under
conditions which are known to be slow. The --test_timeout values
are in seconds. For example --test_timeout=120 will set the test
timeout to two minutes.
|
||||||||||||||||||||
flaky |
Marks test as flaky. If set, executes the test up to 3 times before being declared as failed. By default this attribute is set to 0 and test is considered to be stable. Note, that use of this attribute is generally discouraged - we do prefer all tests to be stable. |
||||||||||||||||||||
local |
Forces the test to be run locally, without sandboxing. By default this attribute is set to 0 and the default testing strategy is
used. This is equivalent to providing "local" as a tag
( |
||||||||||||||||||||
shard_count |
Non-negative integer less than or equal to 50; optional Specifies the number of parallel shards to use to run the test. 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 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. |
Attributes common to all binary rules (*_binary)
This section describes attributes that are common to all binary rules.
| Attribute | Description |
|---|---|
args |
Command line arguments that bazel will pass to the target when it is executed
either by the
NOTE: The arguments are not passed when you run the target
outside of bazel (for example, by manually executing the binary in
Most binary rules permit an |
output_licenses |
The licenses of the output files that this binary generates.
Describes the licenses of the output of the binary generated by
the rule. When a binary is referenced in a host attribute (for
example, the (For more about the distinction between host and target configurations, see Build configurations in the Bazel manual.) WARNING: in some cases (specifically, in genrules) the build tool cannot guarantee that the binary referenced by this attribute is actually used as a tool, and is not, for example, copied to the output. In these cases, it is the responsibility of the user to make sure that this is true. |
Configurable attributes
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.
The following example declares different sources for different target
architectures. Running bazel build :multiplatform_lib --cpu x86
will build the target using x86_impl.cc, while substituting
--cpu arm will instead cause it to use arm_impl.cc.
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" }
)
The select() function
chooses among different alternative values for a configurable attribute based
on which
config_setting criteria is satisfied in the current
configuration.
Configurable attributes are evaluated after the processing of macros and
before the processing of rules (technically, between the
loading and analysis phases.
Any processing that Bazel does before the select() is evaluated
will not know which branch will be chosen. In particular, macros can't change
their behavior based on the chosen branch, and bazel query can
only make conservative guesses about the configurable dependencies of a
target. Conversely, when authoring a new type of rule, you do not need to
worry about the ambiguity of configurable attributes because all
select() expressions have already been replaced by their resolved
values. See
this FAQ
for more on using select() with rules and macros.
Attributes marked nonconfigurable 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 choose the
select() branch.
See Configurable Build Attributes for more information.
Implicit output targets
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 implicitly entail one or more output file
targets, whose contents and meaning are rule-specific.
For example, when you explicitly declare a
java_binary(name='foo', ...) rule, you are also
implicitly declaring an output file
target foo_deploy.jar as a member of the same package.
(This particular target is a self-contained Java archive suitable
for deployment.)
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 bazel query.
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.
An important but somewhat subtle distinction between the
two namespaces used by the build system:
labels identify targets,
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 bazel query;
this is the target namespace. 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, .o 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 BUILD Concept Reference.