From 6cbeb125699ecc402d7cc09f30eff8ff6d4ad6be Mon Sep 17 00:00:00 2001
From: Folkert de Vries <folkert@folkertdev.nl>
Date: Mon, 8 Dec 2025 21:16:20 +0100
Subject: [PATCH 1/2] `cfg_select!` macro

---
 src/conditional-compilation.md | 37 ++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md
index a2deb89bd3..da74488b4d 100644
--- a/src/conditional-compilation.md
+++ b/src/conditional-compilation.md
@@ -31,7 +31,7 @@ r[cfg.general]
 *Conditionally compiled source code* is source code that is compiled only under certain conditions.
 
 r[cfg.attributes-macro]
-Source code can be made conditionally compiled using the [`cfg`] and [`cfg_attr`] [attributes] and the built-in [`cfg` macro].
+Source code can be made conditionally compiled using the [`cfg`] and [`cfg_attr`] [attributes] and the built-in [`cfg!`] and [`cfg_select!`] [macros].
 
 r[cfg.conditional]
 Whether to compile can depend on the target architecture of the compiled crate, arbitrary values passed to the compiler, and other things further described below.
@@ -466,11 +466,43 @@ let machine_kind = if cfg!(unix) {
 println!("I'm running on a {} machine!", machine_kind);
 ```
 
+r[cfg.cfg_select]
+### The `cfg_select` macro
+
+The built-in `cfg_select` macro expands to the right-hand side of the first configuration predicate that evaluates to `true`.
+
+For example:
+
+```rust
+cfg_select! {
+    unix => {
+        fn foo() { /* unix specific functionality */ }
+    }
+    target_pointer_width = "32" => {
+        fn foo() { /* non-unix, 32-bit functionality */ }
+    }
+    _ => {
+        fn foo() { /* fallback implementation */ }
+    }
+}
+```
+The `cfg_select` macro can also be used in expression position:
+
+```rust
+let is_unix_str = cfg_select! {
+    unix => "unix",
+    _ => "not unix",
+};
+```
+
+A `_` can be used to write a configuration predicate that always evaluates to `true`.
+
 [Testing]: attributes/testing.md
 [`--cfg`]: ../rustc/command-line-arguments.html#--cfg-configure-the-compilation-environment
 [`--test`]: ../rustc/command-line-arguments.html#--test-build-a-test-harness
 [`cfg`]: #the-cfg-attribute
-[`cfg` macro]: #the-cfg-macro
+[`cfg!`]: #the-cfg-macro
+[`cfg_select!`]: #the-cfg_select-macro
 [`cfg_attr`]: #the-cfg_attr-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
@@ -479,4 +511,5 @@ println!("I'm running on a {} machine!", machine_kind);
 [attributes]: attributes.md
 [cargo-feature]: ../cargo/reference/features.html
 [crate type]: linkage.md
+[macros]: macros.md
 [static C runtime]: linkage.md#static-and-dynamic-c-runtimes

From 646c92799974ad911dea8e65e5645e3f6d5363fa Mon Sep 17 00:00:00 2001
From: Folkert de Vries <folkert@folkertdev.nl>
Date: Wed, 17 Dec 2025 17:58:37 +0100
Subject: [PATCH 2/2] more detail

---
 src/conditional-compilation.md | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md
index da74488b4d..c280b0ba42 100644
--- a/src/conditional-compilation.md
+++ b/src/conditional-compilation.md
@@ -469,7 +469,21 @@ println!("I'm running on a {} machine!", machine_kind);
 r[cfg.cfg_select]
 ### The `cfg_select` macro
 
-The built-in `cfg_select` macro expands to the right-hand side of the first configuration predicate that evaluates to `true`.
+r[cfg.cfg_select.syntax]
+```grammar,configuration
+CfgSelect ->
+    cfg_select! `{` CfgSelectBranch* `}`
+
+CfgSelectConfigurationPredicate ->
+    ConfigurationPredicate | `_`
+
+CfgSelectBranch ->
+    CfgSelectConfigurationPredicate `=>` `{` TokenTree `}`
+  | CfgSelectConfigurationPredicate `=>` TokenTree `,`
+```
+
+r[cfg.cfg_select.general]
+The built-in `cfg_select` macro expands to the `TokenTree` on the right-hand side of the first configuration predicate that evaluates to `true`.
 
 For example:
 
@@ -495,8 +509,26 @@ let is_unix_str = cfg_select! {
 };
 ```
 
+r[cfg.cfg_select.wildcard]
 A `_` can be used to write a configuration predicate that always evaluates to `true`.
 
+r[cfg.cfg_select.fallthrough]
+If none of the predicates evaluates to `true`, a compiler error is emitted.
+
+r[cfg.cfg_select.positions]
+The `cfg_select!` macro is accepted in the following macro expansion positions
+
+- items
+- statements
+- expression
+- impl items
+- trait impl items
+- trait items
+- foreign items
+
+r[cfg.cfg_select.well-formed]
+Each right-hand side must syntactically be valid expansion for the position that the macro is invoked in.
+
 [Testing]: attributes/testing.md
 [`--cfg`]: ../rustc/command-line-arguments.html#--cfg-configure-the-compilation-environment
 [`--test`]: ../rustc/command-line-arguments.html#--test-build-a-test-harness