From e0e589658463beb9605030b4820dcc97e6a36f48 Mon Sep 17 00:00:00 2001
From: John Cater <jcater@google.com>
Date: Thu, 26 May 2022 08:52:08 -0700
Subject: [PATCH] Add Select FAQ entry on using platforms with select.

In response to #15575.

Closes #15580.

PiperOrigin-RevId: 451171955
Change-Id: Id231ded1529d50e69ba5ec5563fe16a4cd83121d
---
 site/en/docs/configurable-attributes.md | 84 +++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/site/en/docs/configurable-attributes.md b/site/en/docs/configurable-attributes.md
index 288ec8515c8e7f..3b636c5a9f80bf 100644
--- a/site/en/docs/configurable-attributes.md
+++ b/site/en/docs/configurable-attributes.md
@@ -999,4 +999,88 @@ Caution: To prevent restarting the Bazel server, invoke `bazel config` with the
 same command line flags as the `bazel cquery`. The `config` command relies on
 the configuration nodes from the still-running server of the previous command.
 
+### Why doesn't `select()` work with platforms? {:#faq-select-platforms}
+
+Bazel doesn't support configurable attributes checking whether a given platform
+is the target platform because the semantics are unclear.
+
+For example:
+
+```py
+platform(
+    name = "x86_linux_platform",
+    constraint_values = [
+        "@platforms//cpu:x86",
+        "@platforms//os:linux",
+    ],
+)
+
+cc_library(
+    name = "lib",
+    srcs = [...],
+    linkopts = select({
+        ":x86_linux_platform": ["--enable_x86_optimizations"],
+        "//conditions:default": [],
+    }),
+)
+```
+
+In this `BUILD` file, which `select()` should be used if the target platform has both the
+`@platforms//cpu:x86` and `@platforms//os:linux` constraints, but is **not** the
+`:x86_linux_platform` defined here? The author of the `BUILD` file and the user
+who defined the separate platform may have different ideas.
+
+#### What should I do instead?
+
+Instead, define a `config_setting` that matches **any** platform with
+these constraints:
+
+```py
+config_setting(
+    name = "is_x86_linux",
+    constraint_values = [
+        "@platforms//cpu:x86",
+        "@platforms//os:linux",
+    ],
+)
+
+cc_library(
+    name = "lib",
+    srcs = [...],
+    linkopts = select({
+        ":is_x86_linux": ["--enable_x86_optimizations"],
+        "//conditions:default": [],
+    }),
+)
+```
+
+This process defines specific semantics, making it clearer to users what
+platforms meet the desired conditions.
+
+#### What if I really, really want to `select` on the platform?
+
+If your build requirements specifically require checking the platform, you
+can flip the value of the `--platforms` flag in a `config_setting`:
+
+```py
+config_setting(
+    name = "is_specific_x86_linux_platform",
+    values = {
+        "platforms": ["//package:x86_linux_platform"],
+    },
+)
+
+cc_library(
+    name = "lib",
+    srcs = [...],
+    linkopts = select({
+        ":is_specific_x86_linux_platform": ["--enable_x86_optimizations"],
+        "//conditions:default": [],
+    }),
+)
+```
+
+The Bazel team doesn't endorse doing this; it overly constrains your build and
+confuses users when the expected condition does not match.
+
 [BuildSettings]: /rules/config#user-defined-build-settings