From ed0f7d07821c9ee01882f54d6d75be110435034d Mon Sep 17 00:00:00 2001 From: Greg Estren Date: Wed, 17 Jul 2019 13:07:25 -0700 Subject: [PATCH] Update configurable attribute docs with the new config_setting_group Note that the new hyperlinks to `config_setting_group` depend on https://github.com/bazelbuild/bazel-skylib/pull/170, which updates the corresponding Skylib docs. Closes #8909. PiperOrigin-RevId: 258626689 --- site/docs/configurable-attributes.md | 124 ++++++++++++++++----------- 1 file changed, 75 insertions(+), 49 deletions(-) diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md index 9c7103bc7e7eae..e51a1f6f4c9461 100644 --- a/site/docs/configurable-attributes.md +++ b/site/docs/configurable-attributes.md @@ -15,7 +15,8 @@ title: Configurable Build Attributes * [Multiple Selects](#multiple-selects) * [OR Chaining](#or-chaining) * [selects.with_or](#selects-with-or) - * [config_setting Aliasing](#config-setting-aliasing) + * [selects.config_setting_group](#selects-config-setting-or-group) +* [AND Chaining](#and-chaining) * [Custom Error Messages](#custom-error-messages) * [Rules Compatibility](#rules) * [Bazel Query and Cquery](#query) @@ -426,8 +427,8 @@ sh_binary( ) ``` -`select` cannot appear inside another `select` (i.e. *`AND` chaining*). If you -need to `AND` selects together, either use an intermediate target: +`select` cannot appear inside another `select`. If you need to nest `selects` +use an intermediate target: ```python sh_binary( @@ -448,23 +449,11 @@ sh_library( ) ``` -or write a [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: - -```python -config_setting( - name = "armeabi_and_opt", - values = { - "cpu": "armeabi", - "compilation_mode": "opt", - }, -) -``` +Note that this approach doesn't work for non-deps attributes (like +[genrule:cmd](be/general.html#genrule.cmd)). +If you just need a `select` to match when multiple conditions match, see [AND +chaining](#and-chaining). ## OR Chaining @@ -507,14 +496,15 @@ sh_binary( 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 -one of the following: +For more direct support, use one of the following: ### `selects.with_or` -The [Skylib](https://github.com/bazelbuild/bazel-skylib) utility -[`selects`](https://github.com/bazelbuild/bazel-skylib/blob/master/lib/selects.bzl) -defines a Starlark macro that emulates `OR` behavior: +The +[with_or](https://github.com/bazelbuild/bazel-skylib/blob/master/docs/selects_doc.md#selectswith_or) +macro in [Skylib](https://github.com/bazelbuild/bazel-skylib)'s +[`selects`](https://github.com/bazelbuild/bazel-skylib/blob/master/docs/selects_doc.md) +module supports `OR`ing conditions directly inside a `select`: ```python load("@bazel_skylib//:lib.bzl", "selects") @@ -531,50 +521,86 @@ sh_binary( ) ``` -This automatically expands the `select` to the original syntax above. +### `selects.config_setting_group` -### `config_setting` Aliasing -If you'd like to `OR` conditions under a proper `config_setting` that any rule -can reference, you can use a `select`able [alias](be/general.html#alias) that -matches any of the desired conditions: +The +[config_setting_group](https://github.com/bazelbuild/bazel-skylib/blob/master/docs/selects_doc.md#selectsconfig_setting_group) +macro in [Skylib](https://github.com/bazelbuild/bazel-skylib)'s +[`selects`](https://github.com/bazelbuild/bazel-skylib/blob/master/docs/selects_doc.md) +module supports `OR`ing multiple `config_setting`s: ```python -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. - }), -) +load("@bazel_skylib//:lib.bzl", "selects") +``` + +```python +config_setting( + name = "config1", + values = {"cpu": "arm"}, +) +config_setting( + name = "config2", + values = {"compilation_mode": "dbg"}, +) +selects.config_setting_group( + name = "config1_or_2", + match_any = [":config1", ":config2"], +) sh_binary( name = "my_target", srcs = ["always_include.sh"], deps = select({ - ":config1_or_2_or_3": [":standard_lib"], - ":config4": [":special_lib"], + ":config1_or_2": [":standard_lib"], + "//conditions:default": [":other_lib"], }), ) ``` -Unlike `selects.with_or`, different rules can `select` on `:config1_or_2_or_3` +Unlike `selects.with_or`, different rules can `select` on `:config1_or_2` with different values. Note that it's an error for multiple conditions to match unless one is a "specialization" of the other. See [select()](be/functions.html#select) documentation for details. -For `AND` chaining, see [here](#multiple-selects). +## And Chaining + +If you need a `select` path to match when multiple conditions match, use the +[Skylib](https://github.com/bazelbuild/bazel-skylib) macro +[config_setting_group](https://github.com/bazelbuild/bazel-skylib/blob/master/docs/selects_doc.md#selectsconfig_setting_group): + +```python +load("@bazel_skylib//:lib.bzl", "selects") +``` + +```python +config_setting( + name = "config1", + values = {"cpu": "arm"}, +) +config_setting( + name = "config2", + values = {"compilation_mode": "dbg"}, +) +selects.config_setting_group( + name = "config1_and_2", + match_all = [":config1", ":config2"], +) +sh_binary( + name = "my_target", + srcs = ["always_include.sh"], + deps = select({ + ":config1_and_2": [":standard_lib"], + "//conditions:default": [":other_lib"], + }), +) +``` + +Unlike OR chaining, existing `config_setting`s can't be `AND`ed together +directly inside a `select`: you have to explicitly declare the +`config_setting_group`. ## Custom Error Messages