This section defines various terms and concepts that are common to many functions or build rules below.
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, such as the copts
attribute
of cc_library
, or the javacopts
attribute of
java_library
. Together these substitutions allow a
single string variable to expand into a configuration-specific list
of option words.
Some string attributes of a very few rules are subject to label
expansion: if those strings contain a valid build 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 the cmd
attribute of
genrule, and the linkopts
attribute
of cc_library
. 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.
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.
deps
:
A list of dependencies of this rule.
(List of labels; optional)deps
are specific to the kind of this rule,
and the rule-specific documentation below goes into more detail.
At a minimum, though, the targets named via deps
will
appear in the *.runfiles
area of this rule, if it has
one.
Most often, a deps
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 java_library
rule may depend on C++ code in
a cc_library
rule, by declaring the latter in
the deps
attribute. See the definition
of dependencies for more
information.
Almost all rules permit a deps
attribute, but where
this attribute is not allowed, this fact is documented under the
specific rule.
data
:
The list of files needed by this rule at runtime.
(List of labels; optional)data
attribute will appear in
the *.runfiles
area of this rule, if it has one. This
may include data files needed by a binary or library, or other
programs needed by it. See the
data dependencies section for more
information about how to depend on and use data files.
Almost all rules permit a data
attribute, but where
this attribute is not allowed, this fact is documented under the
specific rule.
deprecation
:
(String; optional)
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 deprecation
attribute is
depended upon by another rule.
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 or marked as
obsolete
.
distribs
:
(List of strings; optional)BUILD
-file scope defaults defined by the
distribs()
directive.licenses
:
(List of strings; optional)BUILD
-file scope defaults defined by the
licenses()
directive.obsolete
:
(Boolean; optional; default 0)
As a transition, one can first mark a package as in
deprecation
.
This attribute is useful when you want to prevent a target from being used but are yet not ready to delete the sources.
testonly
:
(Boolean; optional; default 0 except as noted)Equivalently, a rule that is not testonly
is not allowed to
depend on any rule that is testonly
.
Tests (*_test
rules)
and test suites (test_suite rules)
are testonly
by default.
By virtue of
default_testonly
,
targets under javatests
are testonly
by default.
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.
visibility
:
(List of labels; optional; default private)The visibility
attribute on a rule controls whether
the rule can be used by other packages. Rules are always visible to
other rules declared in the same package.
There are five forms (and one temporary form) a visibility label can take:
['//visibility:public']
: Anyone can use this rule.['//visibility:private']
: Only rules in this package
can use this rule. Rules in javatests/foo/bar
can always use rules in java/foo/bar
.
['//some/package:__pkg__', '//other/package:__pkg__']
:
Only rules in some/package
and other/package
(defined in some/package/BUILD
and
other/package/BUILD
) have access to this rule. Note that
sub-packages do not have access to the rule; for example,
//some/package/foo:bar
or
//other/package/testing:bla
wouldn't have access.
__pkg__
is a special target and must be used verbatim.
It represents all of the rules in the package.
['//project:__subpackages__', '//other:__subpackages__']
:
Only rules in packages project
or other
or
in one of their sub-packages have access to this rule. For example,
//project:rule
, //project/library:lib
or
//other/testing/internal:munge
are allowed to depend on
this rule (but not //independent:evil
)
['//some/package:my_package_group']
:
A package group is
a named set of package names. Package groups can also grant access rights
to entire subtrees, e.g.//myproj/...
.
The visibility specifications of //visibility:public
,
//visibility:private
and
//visibility:legacy_public
can not be combined with any other visibility specifications.
A visibility specification may contain a combination of package labels
(i.e. //foo:__pkg__) and package_groups.
If a rule does not specify the visibility attribute,
the default_visibility
attribute of the package
statement in the BUILD file containing the rule is used
(except exports_files and
cc_public_library, which always default to
public).
Example:
File //frobber/bin/BUILD
:
# This rule is visible to everyone java_binary( name = "executable", visibility = ["//visibility:public"], deps = [":library"], ) # This rule is visible only to rules declared in the same package java_library( name = "library", visibility = ["//visibility:private"], ) # This rule is visible to rules in package //object and //noun java_library( name = "subject", visibility = [ "//noun:__pkg__", "//object:__pkg__", ], ) # See package group //frobber:friends (below) for who can access this rule. java_library( name = "thingy", visibility = ["//frobber:friends"], )
File //frobber/BUILD
:
# 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", ], )
This section describes attributes that are common to all test rules.
args
:
Add these arguments to the --test_arg
when executed by bazel test
.
(List of strings; optional; subject to
"Make variable" substitution and
Bourne shell tokenization)--test_arg
values
specified on the bazel test
command line.flaky
:
Marks test as flaky. (Boolean; optional)local
:
Forces the test to be run locally. (Boolean; optional)tags=["local"]
).shard_count
:
Specifies the number of parallel shards
to use to run the test. (Non-negative integer less than or equal to 50;
optional)size
:
How "heavy" the test is
(String "enormous", "large" "medium" or "small",
default is "medium")timeout
:
How long the test is
normally expected to run before returning.
(String "eternal", "long", "moderate", or "short"
with the default derived from a test's size attribute)This section describes attributes that are common to all binary rules.
args
:
Add these arguments to the target when executed by
bazel run
.
(List of strings; optional; subject to
"Make variable" substitution and
Bourne shell tokenization)bazel run
command line.
Most binary rules permit an args
attribute, but where
this attribute is not allowed, this fact is documented under the
specific rule.
output_licenses
:
The licenses of the output files that this binary generates.
(List of strings; optional)tools
attribute of
a genrule
), this license declaration is used rather
than the union of the licenses of its transitive closure. This
argument is useful when a binary is used as a tool during the
build of a rule, and it is not desirable for its license to leak
into the license of that rule. If this attribute is missing, the
license computation proceeds as if the host dependency was a
regular dependency.
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.
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 build
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.
Please note an important but somewhat subtle distinction between the
two namespaces used by the build system. Build
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.