General Rules

filegroup

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, output_licenses, restricted_to, tags, testonly, visibility)

Use filegroup to give a convenient name to a collection of targets. These can then be referenced from other rules.

Using filegroup is encouraged instead of referencing directories directly. The latter is unsound since the build system does not have full knowledge of all files below the directory, so it may not rebuild when these files change. When combined with glob, filegroup can ensure that all files are explicitly known to the build system.

Examples

To create a filegroup consisting of two source files, do

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

Or, use a glob to grovel a testdata directory:

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

To make use of these definitions, reference the filegroup with a label from any rule:

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

Arguments

Attributes
name

Name; required

A unique name for this target.

srcs

List of labels; optional

The list of targets that are members of the file group.

It is common to use the result of a glob expression for the value of the srcs attribute.

data

List of labels; optional

The list of files needed by this rule at runtime.

Targets named in the data attribute will be added to the runfiles of this filegroup rule. When the filegroup is referenced in the data attribute of another rule its runfiles will be added to the runfiles of the depending rule. See the data dependencies section and general documentation of data for more information about how to depend on and use data files.

output_group

String; optional

The output group from which to gather artifacts from sources. If this attribute is specified, artifacts from the specified output group of the dependencies will be exported instead of the default output group.

An "output group" is a category of output artifacts of a target, specified in that rule's implementation.

genquery

genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, testonly, visibility)

genquery() runs a query specified in the Bazel query language and dumps the result into a file.

In order to keep the build consistent, the query is allowed only to visit the transitive closure of the targets specified in the scope attribute. Queries violating this rule will fail during execution if strict is unspecified or true (if strict is false, the out of scope targets will simply be skipped with a warning). The easiest way to make sure this does not happen is to mention the same labels in the scope as in the query expression.

The only difference between the queries allowed here and on the command line is that queries containing wildcard target specifications (e.g. //pkg:* or //pkg:all) are not allowed here. The reasons for this are two-fold: first, because genquery has to specify a scope to prevent targets outside the transitive closure of the query to influence its output; and, second, because BUILD files do not support wildcard dependencies (e.g. deps=["//a/..."] is not allowed).

The genquery's output is ordered using --order_output=full in order to enforce deterministic output.

The name of the output file is the name of the rule.

Examples

This example writes the list of the labels in the transitive closure of the specified target to a file.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

Arguments

Attributes
name

Name; required

A unique name for this target.

expression

String; required

The query to be executed. In contrast to the command line and other places in BUILD files, labels here are resolved relative to the root directory of the workspace. For example, the label :b in this attribute in the file a/BUILD will refer to the target //:b.
opts

List of strings; optional

The options that are passed to the query engine. These correspond to the command line options that can be passed to bazel query. Some query options are not allowed here: --keep_going, --query_file, --universe_scope, --order_results and --order_output. Options not specified here will have their default values just like on the command line of bazel query.
scope

List of labels; required

The scope of the query. The query is not allowed to touch targets outside the transitive closure of these targets.
strict

Boolean; optional; default is True

If true, targets whose queries escape the transitive closure of their scopes will fail to build. If false, Bazel will print a warning and skip whatever query path led it outside of the scope, while completing the rest of the query.

test_suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, testonly, tests, visibility)

A test_suite defines a set of tests that are considered "useful" to humans. This allows projects to define sets of tests, such as "tests you must run before checkin", "our project's stress tests" or "all small tests."

Examples

A test suite to run all of the small tests in the current package.

test_suite(
    name = "small_tests",
    tags = ["small"],
)

A test suite that runs a specified set of tests:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

A test suite to run all tests in the current package which are not flaky.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

Arguments

Attributes
name

Name; required

A unique name for this target.

tags

List of strings; optional; nonconfigurable

List of text tags such as "small" or "database" or "-flaky". Tags may be any valid string.

Tags which begin with a "-" character are considered negative tags. The preceding "-" character is not considered part of the tag, so a suite tag of "-small" matches a test's "small" size. All other tags are considered positive tags.

Optionally, to make positive tags more explicit, tags may also begin with the "+" character, which will not be evaluated as part of the text of the tag. It merely makes the positive and negative distinction easier to read.

Only test rules that match all of the positive tags and none of the negative tags will be included in the test suite. Note that this does not mean that error checking for dependencies on tests that are filtered out is skipped; the dependencies on skipped tests still need to be legal (e.g. not blocked by visibility constraints).

The manual tag keyword is treated specially. It marks the test_suite target as "manual" so that it will be ignored by the wildcard expansion and automated testing facilities. It does not work as a filter on the set of tests in the suite. So when the manual tag is used on a test_suite, test rules do not have to be tagged as manual to be included in the test suite.

Note that a test's size is considered a tag for the purpose of filtering.

If you need a test_suite that contains tests with mutually exclusive tags (e.g. all small and medium tests), you'll have to create three test_suite rules: one for all small tests, one for all medium tests, and one that includes the previous two.

tests

List of labels; optional; nonconfigurable

A list of test suites and test targets of any language.

Any *_test is accepted here, independent of the language. No *_binary targets are accepted however, even if they happen to run a test. Filtering by the specified tags is only done for tests listed directly in this attribute. If this attribute contains test_suites, the tests inside those will not be filtered by this test_suite (they are considered to be filtered already).

If the tests attribute is unspecified or empty, the rule will default to including all test rules in the current BUILD file that are not tagged as manual. These rules are still subject to tag filtering.

alias

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, testonly, visibility)

The alias rule creates another name a rule can be referred to as.

Aliasing only works for "regular" targets. In particular, package_group and test_suite cannot be aliased.

The alias rule has its own visibility declaration. In all other respects, it behaves like the rule it references with some minor exceptions:

  • Tests are not run if their alias is mentioned on the command line. To define an alias that runs the referenced test, use a test_suite rule with a single target in its tests attribute.
  • When defining environment groups, the aliases to environment rules are not supported. They are not supported in the --target_environment command line option, either.

Examples

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

Arguments

Attributes
name

Name; required

A unique name for this target.

actual

Label; required

The target this alias refers to. It does not need to be a rule, it can also be an input file.

config_setting

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

Matches an expected configuration state (expressed as Bazel flags or platform constraints) for the purpose of triggering configurable attributes. See select for how to consume this rule and Configurable attributes for an overview of the general feature.

Examples

The following matches any Bazel invocation that specifies --compilation_mode=opt or -c opt (either explicitly at the command line or implicitly from .bazelrc files):

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

The following matches any Bazel invocation that builds for ARM and that applies the custom define FOO=bar (for instance, bazel build --cpu=arm --define FOO=bar ... ):

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

The following matches any Bazel invocation that builds for a platform that has an x86_64 architecture and glibc version 2.25, assuming the existence of a constraint_value with label //example:glibc_2_25. Note that a platform still matches if it defines additional constraint values beyond these two.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  
In all these cases, it's possible for the configuration to change within the build, for example if a target needs to be built for a different platform than its dep. This means that even when a config_setting doesn't match the top-level command-line flags, it may still match some build targets.

Notes

  • See select for what happens when multiple config_settings match the current configuration state.
  • For flags that support shorthand forms (e.g. --compilation_mode vs. -c), values definitions must use the full form. These automatically match invocations using either form.
  • If a flag takes multiple values (like --copt=-Da --copt=-Db or a list-typed Starlark flag), values = { "flag": "a" } matches if "a" is present anywhere in the actual list.

    values = { "myflag": "a,b" } works the same way: this matches --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b, and --myflag=c,b,a. Exact semantics vary between flags. For example, --copt doesn't support multiple values in the same instance: --copt=a,b produces ["a,b"] while --copt=a --copt=b produces ["a", "b"] (so values = { "copt": "a,b" } matches the former but not the latter). But --ios_multi_cpus (for Apple rules) does: -ios_multi_cpus=a,b and ios_multi_cpus=a --ios_multi_cpus=b both produce ["a", "b"]. Check flag definitions and test your conditions carefully to verify exact expectations.

  • If you need to define conditions that aren't modeled by built-in Bazel flags, use Starlark-defined flags. You can also use --define, but this offers weaker support and is not recommended. See here for more discussion.
  • Avoid repeating identical config_setting definitions in different packages. Instead, reference a common config_setting that defined in a canonical package.
  • values, define_values, and constraint_values can be used in any combination in the same config_setting but at least one must be set for any given config_setting.

Arguments

Attributes
name

Name; required

A unique name for this target.

constraint_values

List of labels; optional; nonconfigurable

The minimum set of constraint_values that the target platform must specify in order to match this config_setting. (The execution platform is not considered here.) Any additional constraint values that the platform has are ignored. See Configurable Build Attributes for details.

In the case where two config_settings both match in the same select, this attribute is not considered for the purpose of determining whether one of the config_settings is a specialization of the other. In other words, one config_setting cannot match a platform more strongly than another.

define_values

Dictionary: String -> String; optional; nonconfigurable

The same as values but specifically for the --define flag.

--define is special because its syntax (--define KEY=VAL) means KEY=VAL is a value from a Bazel flag perspective.

That means:

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

doesn't work because the same key (define) appears twice in the dictionary. This attribute solves that problem:

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

correctly matches bazel build //foo --define a=1 --define b=2.

--define can still appear in values with normal flag syntax, and can be mixed freely with this attribute as long as dictionary keys remain distinct.

flag_values

null; optional; nonconfigurable

The same as values but for Starlark-defined flags.
values

Dictionary: String -> String; optional; nonconfigurable

The set of configuration values that match this rule (expressed as Bazel flags)

This rule inherits the configuration of the configured target that references it in a select statement. It is considered to "match" a Bazel invocation if, for every entry in the dictionary, its configuration matches the entry's expected value. For example values = {"compilation_mode": "opt"} matches the invocations bazel build --compilation_mode=opt ... and bazel build -c opt ... on target-configured rules.

For convenience's sake, configuration values are specified as Bazel flags (without the preceding "--"). But keep in mind that the two are not the same. This is because targets can be built in multiple configurations within the same build. For example, a host configuration's "cpu" matches the value of --host_cpu, not --cpu. So different instances of the same config_setting may match the same invocation differently depending on the configuration of the rule using them.

If a flag is not explicitly set at the command line, its default value is used. If a key appears multiple times in the dictionary, only the last instance is used. If a key references a flag that can be set multiple times on the command line (e.g. bazel build --copt=foo --copt=bar --copt=baz ...), a match occurs if any of those settings match.

This and define_values cannot both be empty.

genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, testonly, toolchains, tools, visibility)

A genrule generates one or more files using a user-defined Bash command.

Genrules are generic build rules that you can use if there's no specific rule for the task. If for example you want to minify JavaScript files then you can use a genrule to do so. If however you need to compile C++ files, stick to the existing cc_* rules, because all the heavy lifting has already been done for you.

Do not use a genrule for running tests. There are special dispensations for tests and test results, including caching policies and environment variables. Tests generally need to be run after the build is complete and on the target architecture, whereas genrules are executed during the build and on the host architecture (the two may be different). If you need a general purpose testing rule, use sh_test.

Cross-compilation Considerations

See the user manual for more info about cross-compilation.

While genrules run during a build, their outputs are often used after the build, for deployment or testing. Consider the example of compiling C code for a microcontroller: the compiler accepts C source files and generates code that runs on a microcontroller. The generated code obviously cannot run on the CPU that was used for building it, but the C compiler (if compiled from source) itself has to.

The build system uses the host configuration to describe the machine(s) on which the build runs and the target configuration to describe the machine(s) on which the output of the build is supposed to run. It provides options to configure each of these and it segregates the corresponding files into separate directories to avoid conflicts.

For genrules, the build system ensures that dependencies are built appropriately: srcs are built (if necessary) for the target configuration, tools are built for the host configuration, and the output is considered to be for the target configuration. It also provides "Make" variables that genrule commands can pass to the corresponding tools.

It is intentional that genrule defines no deps attribute: other built-in rules use language-dependent meta information passed between the rules to automatically determine how to handle dependent rules, but this level of automation is not possible for genrules. Genrules work purely at the file and runfiles level.

Special Cases

Host-host compilation: in some cases, the build system needs to run genrules such that the output can also be executed during the build. If for example a genrule builds some custom compiler which is subsequently used by another genrule, the first one has to produce its output for the host configuration, because that's where the compiler will run in the other genrule. In this case, the build system does the right thing automatically: it builds the srcs and outs of the first genrule for the host configuration instead of the target configuration. See the user manual for more info.

JDK & C++ Tooling: to use a tool from the JDK or the C++ compiler suite, the build system provides a set of variables to use. See "Make" variable for details.

Genrule Environment

The genrule command is executed by a Bash shell that is configured to fail when a command or a pipeline fails, using set -e -o pipefail.

The build tool executes the Bash command in a sanitized process environment that defines only core variables such as PATH, PWD, TMPDIR, and a few others. To ensure that builds are reproducible, most variables defined in the user's shell environment are not passed though to the genrule's command. However, Bazel (but not Bazel) passes through the value of the user's PATH environment variable. Any change to the value of PATH will cause Bazel to re-execute the command on the next build.

A genrule command should not access the network except to connect processes that are children of the command itself, though this is not currently enforced.

The build system automatically deletes any existing output files, but creates any necessary parent directories before it runs a genrule. It also removes any output files in case of a failure.

General Advice

  • Do ensure that tools run by a genrule are deterministic and hermetic. They should not write timestamps to their output, and they should use stable ordering for sets and maps, as well as write only relative file paths to the output, no absolute paths. Not following this rule will lead to unexpected build behavior (Bazel not rebuilding a genrule you thought it would) and degrade cache performance.
  • Do use $(location) extensively, for outputs, tools and sources. Due to the segregation of output files for different configurations, genrules cannot rely on hard-coded and/or absolute paths.
  • Do write a common Starlark macro in case the same or very similar genrules are used in multiple places. If the genrule is complex, consider implementing it in a script or as a Starlark rule. This improves readability as well as testability.
  • Do make sure that the exit code correctly indicates success or failure of the genrule.
  • Do not write informational messages to stdout or stderr. While useful for debugging, this can easily become noise; a successful genrule should be silent. On the other hand, a failing genrule should emit good error messages.
  • $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x).
  • Avoid creating symlinks and directories. Bazel doesn't copy over the directory/symlink structure created by genrules and its dependency checking of directories is unsound.
  • When referencing the genrule in other rules, you can use either the genrule's label or the labels of individual output files. Sometimes the one approach is more readable, sometimes the other: referencing outputs by name in a consuming rule's srcs will avoid unintentionally picking up other outputs of the genrule, but can be tedious if the genrule produces many outputs.

Examples

This example generates foo.h. There are no sources, because the command doesn't take any input. The "binary" run by the command is a perl script in the same package as the genrule.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

The following example shows how to use a filegroup and the outputs of another genrule. Note that using $(SRCS) instead of explicit $(location) directives would also work; this example uses the latter for sake of demonstration.

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

Arguments

Attributes
name

Name; required

A unique name for this target.


You may refer to this rule by name in the srcs or deps section of other BUILD rules. If the rule generates source files, you should use the srcs attribute.
srcs

List of labels; optional

A list of inputs for this rule, such as source files to process.

This attributes is not suitable to list tools executed by the cmd; use the tools attribute for them instead.

The build system ensures these prerequisites are built before running the genrule command; they are built using the same configuration as the original build request. The names of the files of these prerequisites are available to the command as a space-separated list in $(SRCS); alternatively the path of an individual srcs target //x:y can be obtained using $(location //x:y), or using $< provided it's the only entry in //srcs.

outs

List of filenames; required; nonconfigurable

A list of files generated by this rule.

Output files must not cross package boundaries. Output filenames are interpreted as relative to the package.

If the executable flag is set, outs must contain exactly one label.

cmd

String; optional

The command to run. Subject to $(location) and "Make" variable substitution.
  1. First $(location) substitution is applied, replacing all occurrences of $(location label) and of $(locations label).
  2. Note that outs are not included in this substitution. Output files are always generated into a predictable location (available via $(@D), $@, $(OUTS) or $(RULEDIR) or $(location output_name); see below).

  3. Next, "Make" variables are expanded. Note that predefined variables $(JAVA), $(JAVAC) and $(JAVABASE) expand under the host configuration, so Java invocations that run as part of a build step can correctly load shared libraries and other dependencies.
  4. Finally, the resulting command is executed using the Bash shell. If its exit code is non-zero the command is considered to have failed.

The command may refer to *_binary targets; it should use a label for this. The following variables are available within the cmd sublanguage:

This is the fallback of cmd_bash, cmd_ps and cmd_bat, if none of them are applicable.

If the command line length exceeds the platform limit (64K on Linux/macOS, 8K on Windows), then genrule will write the command to a script and execute that script to work around. This applies to all cmd attributes (cmd, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; optional

The Bash command to run.

This attribute has higher priority than cmd. The command is expanded and runs in the exact same way as the cmd attribute.

cmd_bat

String; optional

The Batch command to run on Windows.

This attribute has higher priority than cmd and cmd_bash. The command runs in the similar way as the cmd attribute, with the following differences:

  • This attribute only applies on Windows.
  • The command runs with cmd.exe /c with the following default arguments:
    • /S - strip first and last quotes and execute everything else as is.
    • /E:ON - enable extended command set.
    • /V:ON - enable delayed variable expansion
    • /D - ignore AutoRun registry entries.
  • After $(location) and "Make" variable substitution, the paths will be expanded to Windows style paths (with backslash).
cmd_ps

String; optional

The Powershell command to run on Windows.

This attribute has higher priority than cmd, cmd_bash and cmd_bat. The command runs in the similar way as the cmd attribute, with the following differences:

  • This attribute only applies on Windows.
  • The command runs with powershell.exe /c.

To make Powershell easier to use and less error-prone, we run the following commands to set up the environment before executing Powershell command in genrule.

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - allow running unsigned scripts.
  • $errorActionPreference='Stop' - In case there are multiple commands separated by ;, the action exits immediately if a Powershell CmdLet fails, but this does NOT work for external command.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8' - change the default encoding from utf-16 to utf-8.
exec_tools

List of labels; optional

A list of tool dependencies for this rule. This behaves exactly like the tools attribute, except that these dependencies will be configured for the rule's execution platform instead of the host configuration. This means that dependencies in exec_tools are not subject to the same limitations as dependencies in tools. In particular, they are not required to use the host configuration for their own transitive dependencies. See tools for further details.

Note that eventually the host configuration will be replaced by the execution configuration. When that happens, this attribute will be deprecated in favor of tools. Until then, this attribute allows users to selectively migrate dependencies to the execution configuration.

executable

Boolean; optional; nonconfigurable; default is False

Declare output to be executable.

Setting this flag to 1 means the output is an executable file and can be run using the run command. The genrule must produce exactly one output in this case. If this attribute is set, run will try executing the file regardless of its content.

Declaring data dependencies for the generated executable is not supported.

local

Boolean; optional; default is False

If set to 1, this option forces this genrule to run using the "local" strategy, which means no remote execution, no sandboxing, no persistent workers.

This is equivalent to providing 'local' as a tag (tags=["local"]).

message

String; optional

A progress message.

A progress message that will be printed as this build step is executed. By default, the message is "Generating output" (or something equally bland) but you may provide a more specific one. Use this attribute instead of echo or other print statements in your cmd command, as this allows the build tool to control whether such progress messages are printed or not.

output_licenses

Licence type; optional

See common attributes
output_to_bindir

Boolean; optional; nonconfigurable; default is False

If set to 1, this option causes output files to be written into the bin directory instead of the genfiles directory.

tools

List of labels; optional

A list of tool dependencies for this rule. See the definition of dependencies for more information.

The build system ensures these prerequisites are built before running the genrule command; they are built using the host configuration, since these tools are executed as part of the build. The path of an individual tools target //x:y can be obtained using $(location //x:y).

Any *_binary or tool to be executed by cmd must appear in this list, not in srcs, to ensure they are built in the correct configuration.