| Command |
deps = |
bazel build //myapp:mybinary --cpu=arm |
[":arm_lib"] |
bazel build //myapp:mybinary --c dbg --cpu=x86 |
[":x86_dev_lib"] |
bazel build //myapp:mybinary --cpu=ppc |
[":generic_lib"] |
bazel build //myapp:mybinary -c dbg --cpu=ppc |
[":generic_lib"] |
`select()` turns any attribute into a dictionary that maps _configuration
conditions_ to desired values. Configuration conditions are build labels that
reference [`config_setting`](be/general.html#config_setting) rules. Values are
any value the attribute can normally take.
Matches must be unambiguous: either exactly one condition must match or, if
multiple conditions match, one's `values` must be a strict superset of all
others' (for example, `values = {"cpu": "x86", "compilation_mode": "dbg"}` is an
unambiguous specialization of `values = {"cpu": "x86"}`). The built-in condition
[`//conditions:default`](#defaults) automatically matches when nothing else
does.
This example uses `deps`. But `select()` works just as well on `srcs`,
`resources`, `cmd`, or practically any other attribute. Only a small number of
attributes are *non-configurable*, and those are clearly [annotated]
(be/general.html#config_setting.values).
## Configuration Conditions
Each key in a configurable attribute is a label reference to a
[`config_setting`](be/general.html#config_setting) rule. This is just a
collection of expected command line flag settings. By encapsulating these in a
rule, it's easy to maintain "standard" conditions that can be referenced across
rules and BUILD files.
The core `config_setting` syntax is:
```sh
config_setting(
name = "meaningful_condition_name",
values = {
"flag1": "expected_value1",
"flag2": "expected_value2",
...
}
)
```
`flagN` is an arbitrary Bazel command line flag. `value` is the expected value
for that flag. A `config_setting` matches when *all* of its flags match.
`values` entries use the same parsing logic as at the actual command line. This
means:
* `values = { "compilation_mode": "opt" }` matches `bazel build -c opt ...`
* `values = { "java_header_compilation": "true" }` matches `bazel build
--java_header_compilation=1 ...`
* `values = { "java_header_compilation": "0" }` matches `bazel build
--nojava_header_compilation ...`
`config_setting` only works with flags that affect build rule output. For
example, [`--show_progress`](user-manual.html#flag--show_progress) isn't allowed
because this only affects how Bazel reports progress to the user.
`config_setting` semantics are intentionally simple. For example, there's no
direct support for `OR` chaining (although a
[Skylark convenience function](#or-chaining) provides this). Consider writing
Skylark macros for complicated flag logic.
## Defaults
The built-in condition `//conditions:default` matches when no other condition
matches.
Because of the "exactly one match" rule, a configurable attribute with no match
and no default condition triggers a `"no matching conditions"` error. This can
protect against silent failures from unexpected build flags:
```sh
//foo:
config_setting(
name = "foobar",
values = { "define": "foo=bar" }
)
cc_library(
name = "my_lib",
srcs = select({
":foobar": ["foobar_lib.cc"],
})
)
```
```sh
$ bazel build //foo:my_lib --define foo=baz
ERROR: Configurable attribute "srcs" doesn't match this configuration (would
a default condition help?).
Conditions checked:
//foo:foobar
```
`select()` can include a [`no_match_error`](#custom-error-messages) for custom
failure messages.
## Custom Keys
Since `config_setting` currently only supports built-in Bazel flags, the level
of custom conditioning it can support is limited. For example, there's no Bazel
flag for `IncludeSpecialProjectFeatureX`.
Plans for [truly custom flags]
(https://docs.google.com/document/d/1vc8v-kXjvgZOdQdnxPTaV0rrLxtP2XwnD2tAZlYJOqw/edit?usp=sharing)
are underway. In the meantime, [`--define`](user-manual.html#flag--define) is
the best approach for these purposes.
`--define` is a bit awkward to use and wasn't originally designed for this
purpose. We recommend using it sparingly until true custom flags are available.
For example, don't use `--define` to specify multiple variants of top-level
binary. Just use multiple rules instead.
To trigger an arbitrary condition with `--define`, write
```sh
config_setting(
name = "bar",
values = { "define": "foo=bar" }
)
config_setting(
name = "baz",
values = { "define": "foo=baz" }
)
```
and run `$ bazel build //my:target --define foo=baz`.
The `values` attribute can't contain multiple `define`s. This is
because each instance has the same dictionary key. To solve this, use
`define_values`:
```sh
config_setting(
name = "bar_and_baz",
define_values = {
"foo": "bar", # matches --define foo=bar
"baz": "bat", # matches --define baz=bat
}
)
```
When `define`s appear in both `values` and `define_values`, all must match for
the `config_setting` to match.
## Platforms
While the ability to specify multiple flags on the command line provides
flexibility, it can also be burdensome to individually set each `--cpu`,
`-crosstool_top`, etc. flag every time you want to build a target. [Platforms]
(https://docs.bazel.build/versions/master/platforms.html) allow you to
consolidate these into simple bundles.
```sh
sh_binary(
name = "my_rocks_rule",
srcs = select({
":basalt" : ["pyroxene.sh"],
":marble" : ["calcite.sh"],
"//conditions:default": ["feldspar.sh"]
})
)
config_setting(
name = "basalt",
constraint_values = [
":igneous",
":black"
]
)
config_setting(
name = "marble",
constraint_values = [
":white",
":metamorphic"
":smooth"
]
)
constraint_setting(name = "color")
constraint_value(name = "black", constraint_setting = "color")
constraint_value(name = "white", constraint_setting = "color")
constraint_setting(name = "texture")
constraint_value(name = "smooth", constraint_setting = "texture")
constraint_setting(name = "type")
constraint_value(name = "igneous", constraint_setting = "type")
constraint_value(name = "metamorphic", constraint_setting = "type")
platform(
name = "basalt_platform",
constraint_values = [
":black",
":igneous"]
)
platform(
name = "marble_platform",
constraint_values = [
":white",
":smooth"
":metamorphic"
]
)
```
The `platform` specified on the command line matches a `config_setting` that
contains the same set (or a superset) of `constraint_values` and triggers
that `config_setting` as a match in the `select()` statement.
For example, in order to set the `srcs` attribute of `my_rocks_rule` to
`calcite.sh`, simply run
```sh
bazel build my_app:my_rocks_rule --platforms=marble_platform
```
Without platforms, this might look something like
```sh
bazel build my_app:my_rocks_rule --define color=light --define texture=smooth --define type=metamorphic
```
Platforms are still under development. See the [documentation]
(https://docs.bazel.build/versions/master/platforms.html) and [roadmap]
(https://docs.google.com/document/d/1_clxJHyUylwYjmQ9jQfWr-eZeLLTUZL6onfvPV7CMoI/edit?usp=sharing)
for details.
## Short Keys
Since configuration keys are rule labels, their names can get long and unwieldy.
This can be mitigated with local variable definitions:
Before:
```sh
sh_binary(
name = "my_rule",
srcs = select({
"//my/project/my/team/configs:config1": ["my_rule_1.sh"],
"//my/project/my/team/configs:config2": ["my_rule_2.sh"],
})
)
```
After:
```sh
CONFIG1="//my/project/my/team/configs:config1"
CONFIG2="//my/project/my/team/configs:config2"
sh_binary(
name = "my_rule",
srcs = select({
CONFIG1: ["my_rule_1.sh"],
CONFIG2: ["my_rule_2.sh"],
})
)
```
For more complex expressions, use [Skylark macros](skylark/macros.md):
Before:
```sh
//foo/BUILD
genrule(
name = "my_rule",
srcs = [],
outs = ["my_rule.out"],
cmd = select({
"//my/project/my/team/configs/config1": "echo custom val: this > $@",
"//my/project/my/team/configs/config2": "echo custom val: that > $@",
"//conditions:default": "echo default output > $@"
})
)
```
After:
```sh
//foo/genrule_select.bzl:
def select_echo(input_dict):
echo_cmd = "echo %s > $@"
out_dict = {"//conditions:default": echo_cmd % "default output" }
for (key, val) in input_dict.items():
cmd = echo_cmd % ("custom val: " + val)
out_dict["//my/project/my/team/configs/config" + key] = cmd
return select(out_dict)
```
```sh
//foo/BUILD:
load("//foo:genrule_select.bzl", "select_echo")
genrule(
name = "my_rule",
srcs = [],
outs = ["my_rule.out"],
cmd = select_echo({
"1": "this",
"2": "that",
})
)
```
## Multiple Selects
`select` can appear multiple times in the same attribute:
```sh
sh_binary(
name = "my_rule",
srcs = ["always_include.sh"]
+ select({
":armeabi_mode": ["armeabi_src.sh"],
":x86_mode": ["x86_src.sh"],
})
+ select({
":opt_mode": ["opt_extras.sh"],
":dbg_mode": ["dbg_extras.sh"],
})
)
```
`select` cannot appear inside another `select` (i.e. *`AND` chaining*). If you
need to `AND` selects together, either use an intermediate rule:
```sh
sh_binary
name = "my_rule",
srcs = ["always_include.sh"],
deps = select({
":armeabi_mode": [":armeabi_lib"],
...
})
)
sh_library(
name = "armeabi_lib",
srcs = select({
":opt_mode": ["armeabi_with_opt.sh"],
...
})
)
```
or write a [Skylark macro](skylark/macros.md) to do the same thing
automatically.
This approach doesn't work for non-deps attributes (like
[genrule:cmd](be/general.html#genrule.cmd)). For these, extra `config_settings`
may be necessary:
```sh
config_setting(
name = "armeabi_and_opt",
values = {
"cpu": "armeabi",
"compilation_mode": "opt"
}
)
```
## OR Chaining
Consider the following:
```sh
sh_binary
name = "my_rule",
srcs = ["always_include.sh"],
deps = select({
":config1": [":standard_lib"],
":config2": [":standard_lib"],
":config3": [":standard_lib"],
":config4": [":special_lib"],
})
)
```
Most conditions evaluate to the same dep. But this syntax is verbose, hard to
maintain, and refactoring-unfriendly. It would be nice to not have to repeat
`[":standard_lib"]` over and over.
One option is to predefine the declaration as a BUILD variable:
```python
STANDARD_DEP = [":standard_lib"]
sh_binary
name = "my_rule",
srcs = ["always_include.sh"],
deps = select({
":config1": STANDARD_DEP,
":config2": STANDARD_DEP,
":config3": STANDARD_DEP,
":config4": [":special_lib"],
})
)
```
This makes it easier to manage the dependency. But it still adds unnecessary
duplication.
`select()` doesn't support native syntax for `OR`ed conditions. For this, use
the [Skylib](https://github.com/bazelbuild/bazel-skylib) utility [`selects`]
(https://github.com/bazelbuild/bazel-skylib/blob/master/lib/selects.bzl).
```sh
load("@bazel_skylib//:lib.bzl", "selects")
```
```sh
sh_binary
name = "my_rule",
srcs = ["always_include.sh"],
deps = selects.with_or({
(":config1", ":config2", ":config3"): [":standard_lib"],
":config4": [":special_lib"],
})
)
```
This automatically expands the `select` to the original syntax above.
For `AND` chaining, see [here](#multiple-selects).
## Custom Error Messages
By default, when no condition matches, the owning rule fails with the error:
```sh
ERROR: Configurable attribute "deps" doesn't match this configuration (would
a default condition help?).
Conditions checked:
//tools/cc_target_os:darwin
//tools/cc_target_os:android
```
This can be customized with [`no_match_error`](be/functions.html#select):
```sh
cc_library(
name = "my_lib",
deps = select({
"//tools/cc_target_os:android": [":android_deps"],
"//tools/cc_target_os:windows": [":windows_deps"],
}, no_match_error = "Please build with an Android or Windows toolchain"
)
)
```
```sh
$ bazel build //foo:my_lib
ERROR: Configurable attribute "deps" doesn't match this configuration: Please
build with an Android or Windows toolchain
```
##