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 |
A unique name for this target. |
srcs
|
It is common to use the result of a glob expression for
the value of the |
data
|
Targets named in the |
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 |
A unique name for this target. |
expression
|
:b in this attribute in the file a/BUILD will refer to the
target //:b .
|
opts
|
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
|
|
strict
|
|
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 |
A unique name for this target. |
tags
|
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
Note that a test's
If you need a |
tests
|
Any
If the |
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 itstests
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 |
A unique name for this target. |
actual
|
|
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_setting
s 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"]
(sovalues = { "copt": "a,b" }
matches the former but not the latter). But--ios_multi_cpus
(for Apple rules) does:-ios_multi_cpus=a,b
andios_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 commonconfig_setting
that defined in a canonical package. values
,define_values
, andconstraint_values
can be used in any combination in the sameconfig_setting
but at least one must be set for any givenconfig_setting
.
Arguments
Attributes | |
---|---|
name |
A unique name for this target. |
constraint_values
|
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 |
define_values
|
values but
specifically for the --define flag.
That means: config_setting( name = "a_and_b", values = { "define": "a=1", "define": "b=2", }) doesn't work because the same key ( config_setting( name = "a_and_b", define_values = { "a": "1", "b": "2", }) correctly matches
|
flag_values
|
values but
for
Starlark-defined flags.
|
values
|
This rule inherits the configuration of the configured target that
references it in a For convenience's sake, configuration values are specified as Bazel flags (without
the preceding 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.
This and |
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 asls $(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 |
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
|
This attributes is not suitable to list tools executed by the
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 |
outs
|
Output files must not cross package boundaries. Output filenames are interpreted as relative to the package.
If the |
cmd
|
The command may refer to
This is the fallback of
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_bash
|
This attribute has higher priority than |
cmd_bat
|
This attribute has higher priority than
|
cmd_ps
|
This attribute has higher priority than
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.
|
exec_tools
|
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
|
executable
|
Setting this flag to 1 means the output is an executable file and can be run using the
Declaring data dependencies for the generated executable is not supported. |
local
|
If set to 1, this option forces this
This is equivalent to providing 'local' as a tag ( |
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 |
output_licenses
|
common attributes
|
output_to_bindir
|
If set to 1, this option causes output files to be written into the |
tools
|
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
Any |