Documentation

Edit

Common definitions

This section defines various terms and concepts that are common to many functions or build rules below.

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

List of features. Default is the empty list.

Features on a rule modify the features currently enabled on the package level via the features attribute.
For example, if the features ['a', 'b'] are enabled on the package level, and a rule features attribute contains ['-a', 'c'], the features enabled for the rule will be 'b' and 'c'.

licenses

List of strings; optional

A list of license-type strings to be used for this particular build rule. Overrides the BUILD-file scope defaults defined by the licenses() directive.

data

List of labels; optional

The list of files needed by this rule at runtime.

Targets named in the 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.

visibility

List of labels; optional; default default_visibility from package if specified, else 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 and //visibility:private 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).

If the default visibility for the package is not specified, the rule is private.

Example:

File //frobber/bin/BUILD:

# 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 //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",
    ],
)
compatible_with

List of labels; optional

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

List of strings; optional

A list of distribution-method strings to be used for this particular build rule. Overrides the BUILD-file scope defaults defined by the distribs() directive.

deps

List of labels; optional

A list of dependencies of this rule.

The precise semantics of what it means for this rule to depend on another using 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.

deprecation

String; optional

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 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.

restricted_to

List of labels; optional

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 compatible_with for details.

tags

List of arbitrary text tags. Tags may be any valid string; default is the empty list.

Tags can be used on any rule. Tags on test and test_suite rules are useful for categorizing the tests. Tags on non-test rules are used to control sandboxed execution of genrules and Skylark actions, and for parsing by humans and/or external tools.

Bazel modifies the behavior of its sandboxing code if it finds the following keywords in the tags attribute of any test rule or genrule, or the keys of execution_requirements for any Skylark action.

  • local keyword results in the action or test never being run remotely or inside the sandbox. For genrules and tests, marking the rule with the local = 1 attribute has the same effect.
  • block-network keyword blocks access to the external network from inside the sandbox. In this case, only communication with localhost is allowed.

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 tags attribute of the test rule:

  • exclusive keyword 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. They will also always run locally and thus without sandboxing.
  • manual keyword will force the test target to not be included in target pattern wildcards (..., :*, :all, etc); the test target will be neither built nor run. It will also be ignored by the test_suite rules that do not mention this test explicitly. The only way to build or run such a test is to specify it via an explicit target pattern on the command line.
  • external keyword will force test to be unconditionally executed (regardless of --cache_test_results value).
testonly

Boolean; optional; default 0 except as noted

If 1, only testonly targets (such as tests) can depend on this target.

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.

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

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization

Add these arguments to the --test_arg when executed by bazel test.

These arguments are passed before the --test_arg values specified on the bazel test command line.

size

String "enormous", "large" "medium" or "small", default is "medium"; optional

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" attribute) and the amount of resources that have to be acquired for the test to run. The mapping of test size to resource is currently:

size RAM (in MB) CPU (in CPU cores) I/O (fraction)
small 20 0.9 0
medium 100 0.9 0.1
large 300 0.8 0.1
enormous 800 0.7 0.4
timeout

String "eternal", "long", "moderate", or "short" with the default derived from a test's size attribute)

How long the test is normally 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 (with "small" ⇒ "short", "medium" ⇒ "moderate", etc...). By default, "short" means 1 minute, "moderate" 5 minutes, and "long" 15 minutes (this can be overridden with --test_timeout, e.g. for running under certain configurations which are known to be slow).

flaky

Boolean; optional

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

Boolean; optional

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 (tags=["local"]).

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 --test_sharding_strategy.

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

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization

Command line arguments that bazel will pass to the target when it is executed either by the run command or as a test. These arguments are passed before the ones that are specified on the bazel run or bazel test 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

List of strings; optional

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 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.

(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 can be "configured" so their values depend on the flags passed at the command line. This can be used, for example, to declare platform-dependent srcs or custom compiler flags depending on the compilation mode.

Example

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" }
)

An attribute is made configurable by assigning it to a select. This makes its value depend on which config_setting matches the build. For example, bazel build :multiplatform_lib --cpu=arm sets multiplatform_lib's srcs to ["arm_impl.cc"], while bazel build :multiplatform_lib --cpu=x86 sets srcs to ["x86_impl.cc"].

See the definitions of select and config_setting for more details. Attributes marked nonconfigurable in their documentation cannot use this feature (usually because Bazel has to know their values before flags have been parsed).

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.