Configurable attributes, commonly known as select(), is a Bazel feature that lets users toggle the values
of BUILD rule attributes at the command line.

This can be used, for example, for a multiplatform library that automatically
chooses the appropriate implementation for the architecture, or for a
feature-configurable binary that can be customized at build time.

This declares a cc_binary that “chooses” its deps based on the flags at the
command line. Specficially, deps becomes:

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() serves as a placeholder for a value that will be chosen based on
configuration conditions. These conditions are labels that refer to
config_setting targets. By using select()
in a configurable attribute, the attribute effectively takes on different values
when different conditions hold.

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 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; for
instance, config_setting’s own
values attribute is non-configurable.

Certain attributes, like the tools of a genrule, have the effect of changing
the build parameters (such as the cpu) for all targets that transitively appear
beneath them. This will affect how conditions are matched within those targets
but not within the attribute that causes the change. That is, a select in the
tools attribute of a genrule will work the same as a select in the srcs.

Configuration Conditions

Each key in a configurable attribute is a label reference to a
config_setting target. This is just a
collection of expected command line flag settings. By encapsulating these in a
target, it’s easy to maintain “standard” conditions that can be referenced
across targets and BUILD files.

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:

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
are underway. In the meantime, --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 targets instead.

When defines 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 one every time
you want to build a target.
Platforms
allow you to consolidate these into simple bundles.

# myapp/BUILDsh_binary(name="my_rocks",srcs=select({":basalt":["pyroxene.sh"],":marble":["calcite.sh"],"//conditions:default":["feldspar.sh"],}),)config_setting(name="basalt",constraint_values=[":black",":igneous",],)config_setting(name="marble",constraint_values=[":white",":metamorphic",],)# constraint_setting acts as an enum type, and constraint_value as an enum value.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 can be specified on the command line. It activates the
config_settings that contain a subset of the platform’s constraint_values,
allowing those config_settings to match in select() expressions.

For example, in order to set the srcs attribute of my_rocks to calcite.sh,
we can simply run

config_settingAliasing

If you’d like to OR conditions under a proper config_setting that any rule
can reference, you can use a selectable alias that
matches any of the desired conditions:

alias(name="config1_or_2_or_3",actual=select({# When the build matches :config1, this alias *becomes* :config1.# So it too matches by definition. The same applies for :config2# and :config3.":config1":":config1",":config2":":config2",":config3":":config3",# The default condition represents this alias "not matching" (i.e.# none of the conditions that we care about above match). In this# case, bind the alias to any of those conditions. By definition# it won't match."//conditions:default":":config2",# Arbitrarily chosen from above.}),)sh_binary(name="my_target",srcs=["always_include.sh"],deps=select({":config1_or_2_or_3":[":standard_lib"],":config4":[":special_lib"],}),)

Unlike selects.with_or, different rules can select on :config1_or_2_or_3
with different values.

Note that it’s an error for multiple conditions to match unless one is a
“specialization” of the other. See select()
documentation for details.

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

Macros can accept select() clauses and pass them through to native
rules. But they cannot directly manipulate them. For example, there’s no way
for a macro to convert

select({"foo":"val"},...)

to

select({"foo":"val_with_suffix"},...)

This is for two reasons.

First, macros that need to know which path a select will choose cannot work
because macros are evaluated in Bazel’s loading phase,
which occurs before flag values are known.
This is a core Bazel design restriction that’s unlikely to change any time soon.

Second, macros that just need to iterate over allselect paths, while
technically feasible, lack a coherent UI. Further design is necessary to change
this.

Bazel Query and Cquery

Bazel query operates over Bazel’s loading phase. This means it doesn’t know what command line
flags will be applied to a target since those flags aren’t evaluated until later
in the build (during the analysis phase). So
the query command can’t accurately determine which path a
configurable attribute will follow.

Bazel cquery has the advantage of being able to parse build
flags and operating post-analysis phase so it correctly resolves configurable
attributes. It doesn’t have full feature parity with query but supports most
major functionality and is actively being worked on.
Querying the following build file…

FAQ

Why doesn’t select() work in macros?

The key issue this question usually means is that select() doesn’t work in
macros. These are different than rules. See the
documentation on rules and macros
to understand the difference.
Here’s an end-to-end example:

Define a rule and macro:

# myproject/defs.bzl# Rule implementation: when an attribute is read, all select()s have already# been resolved. So it looks like a plain old attribute just like any other.def_impl(ctx):name=ctx.attr.nameallcaps=ctx.attr.my_config_string.upper()# This works fine on all values.print("My name is "+name+" with custom message: "+allcaps)# Rule declaration:my_custom_bazel_rule=rule(implementation=_impl,attrs={"my_config_string":attr.string()},)# Macro declaration:defmy_custom_bazel_macro(name,my_config_string):allcaps=my_config_string.upper()# This line won't work with select(s).print("My name is "+name+" with custom message: "+allcaps)

# Comment out sad_macro so it doesn't mess up the build.$ bazel build //myproject:all
DEBUG: /myworkspace/myproject/defs.bzl:5:3: My name is happy_macro with custom message: FIXED STRING.
DEBUG: /myworkspace/myproject/hi.bzl:15:3: My name is happy_rule with custom message: FIRST STRING.

This is impossible to change because by definition macros are evaluated before
Bazel reads the build’s command line flags. That means there isn’t enough
information to evaluate select()s.

This happens because macros don’t understand the contents of select().
So what they’re really evaluting is the select() object itself. According to
Pythonic design
standards, all objects aside from a very small number of exceptions
automatically return true.

Can I read select() like a dict?

Fine. Macros can’t evaluate select(s) because
macros are evaluated before Bazel knows what the command line flags are.

Can macros at least read the select()’s dictionary, say, to add an extra
suffix to each branch?

Conceptually this is possible. But this isn’t yet implemented and is not
currently prioritized.
What you can do today is prepare a straight dictionary, then feed it into a
select():

Why doesn’t select() work with bind()?

Workspace rules do not have a specific configuration, and aren’t evaluated in
the same way as BUILD rules. Therefore, a select() in a bind() can’t
actually evaluate to any specific branch.

Instead, you should use alias(), with a select() in
the actual attribute, to perform this type of run-time determination. This
works correctly, since alias() is a BUILD rule, and is evaluated with a
specific configuration.