General Rules

Rules

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

alias

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, 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.

Aliasing may be of help in large repositories where renaming a target would require making changes to lots of files. You can also use alias rule to store a select function call if you want to reuse that logic for multiple targets.

The alias rule has its own visibility declaration. In all other respects, it behaves like the rule it references (e.g. testonly on the alias is ignored; the testonly-ness of the referenced rule is used instead) 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

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 build 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 build that sets --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 build that targets ARM and 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 build that sets user-defined flag --//custom_flags:foo=1 (either explicitly at the command line or implicitly from .bazelrc files):

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

The following matches any build that targets a platform with 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",
      ]
  )
  

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

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

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

filegroup

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, 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

genquery

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

genquery() runs a query specified in the Blaze 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 lexicographically in order to enforce deterministic output, with the exception of --output=graph|minrank|maxrank or when somepath is used as the top-level function.

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

genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, 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. For example, you could run a Bash one-liner. 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.

Note that genrule requires a shell to interpret the command argument. It is also easy to reference arbitrary programs available on the PATH, however this makes the command non-hermetic and may not be reproducible. If you only need to run a single tool, consider using run_binary instead.

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

Exec-exec 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 exec 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 exec 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 Blaze) 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

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() extracts documentation for rules, functions (including macros), aspects, and providers defined or re-exported in a given .bzl or .scl file. The output of this rule is a ModuleInfo binary proto as defined in stardoc_output.proto in the Bazel source tree.

Implicit output targets

• name.binaryproto (the default output): A ModuleInfo binary proto.
• name.textproto (only built if explicitly requested): the text proto version of name.binaryproto.

Warning: the output format of this rule is not guaranteed to be stable. It is intended mainly for internal use by Stardoc.

Arguments

test_suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, 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." The blaze test command respects this sort of organization: For an invocation like blaze test //some/test:suite, Blaze first enumerates all test targets transitively included by the //some/test:suite target (we call this "test_suite expansion"), then Blaze builds and tests those targets.

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