…iscross

update `cfg_select!` documentation

tracking issue: rust-lang#115585

After rust-lang#143461, and with an eye on a soon(ish) stabilization, I think the docs need some work.

The existing text read more like a motivation for the feature existing to me, so I've tried to now be a bit more descriptive. Still, suggestions are very welcome.

I also added a test for an empty `select! {}` because it's just the sort of thing that might break.

r? `@traviscross`

Rollup of 16 pull requests

Successful merges:

 - #142301 (tests: Fix duplicated-path-in-error fail with musl)
 - #142936 (rustdoc-json: Structured attributes)
 - #143355 (wrapping shift: remove first bitmask and table)
 - #143630 (Drop `./x suggest`)
 - #143738 (Move several float tests to floats/mod.rs)
 - #143752 (Don't panic if WASI_SDK_PATH not set when detecting compiler)
 - #143820 (Fixed a core crate compilation failure when enabling the `optimize_for_size` feature on some targets)
 - #143837 (Adjust `run_make_support::symbols` helpers)
 - #143878 (Port `#[pointee]` to the new attribute parsing infrastructure)
 - #143907 (core: make `str::split_at_unchecked()` inline)
 - #143910 (Add experimental `backtrace-trace-only` std feature)
 - #143927 (Preserve constness in trait objects up to hir ty lowering)
 - #143935 (rustc_type_ir/walk: move docstring to `TypeWalker` itself)
 - #143938 (Update books)
 - #143941 (update `cfg_select!` documentation)
 - #143948 (Update mdbook to 0.4.52)

Failed merges:

 - #143926 (Remove deprecated fields in bootstrap)

r? `@ghost`
`@rustbot` modify labels: rollup

Rollup of 16 pull requests

Successful merges:

 - #142301 (tests: Fix duplicated-path-in-error fail with musl)
 - #142936 (rustdoc-json: Structured attributes)
 - #143355 (wrapping shift: remove first bitmask and table)
 - #143630 (Drop `./x suggest`)
 - #143738 (Move several float tests to floats/mod.rs)
 - #143752 (Don't panic if WASI_SDK_PATH not set when detecting compiler)
 - #143820 (Fixed a core crate compilation failure when enabling the `optimize_for_size` feature on some targets)
 - #143837 (Adjust `run_make_support::symbols` helpers)
 - #143878 (Port `#[pointee]` to the new attribute parsing infrastructure)
 - #143907 (core: make `str::split_at_unchecked()` inline)
 - #143910 (Add experimental `backtrace-trace-only` std feature)
 - #143927 (Preserve constness in trait objects up to hir ty lowering)
 - #143935 (rustc_type_ir/walk: move docstring to `TypeWalker` itself)
 - #143938 (Update books)
 - #143941 (update `cfg_select!` documentation)
 - #143948 (Update mdbook to 0.4.52)

Failed merges:

 - #143926 (Remove deprecated fields in bootstrap)

r? `@ghost`
`@rustbot` modify labels: rollup

Rollup of 13 pull requests

Successful merges:

 - #142301 (tests: Fix duplicated-path-in-error fail with musl)
 - #143630 (Drop `./x suggest`)
 - #143736 (Give all bytes of TypeId provenance)
 - #143752 (Don't panic if WASI_SDK_PATH not set when detecting compiler)
 - #143837 (Adjust `run_make_support::symbols` helpers)
 - #143878 (Port `#[pointee]` to the new attribute parsing infrastructure)
 - #143905 (Recover and suggest to use `;` to construct array type)
 - #143907 (core: make `str::split_at_unchecked()` inline)
 - #143910 (Add experimental `backtrace-trace-only` std feature)
 - #143927 (Preserve constness in trait objects up to hir ty lowering)
 - #143935 (rustc_type_ir/walk: move docstring to `TypeWalker` itself)
 - #143938 (Update books)
 - #143941 (update `cfg_select!` documentation)

Failed merges:

 - #143926 (Remove deprecated fields in bootstrap)

r? `@ghost`
`@rustbot` modify labels: rollup

Rollup merge of #143941 - folkertdev:cfg-select-docs, r=traviscross

update `cfg_select!` documentation

tracking issue: #115585

After #143461, and with an eye on a soon(ish) stabilization, I think the docs need some work.

The existing text read more like a motivation for the feature existing to me, so I've tried to now be a bit more descriptive. Still, suggestions are very welcome.

I also added a test for an empty `select! {}` because it's just the sort of thing that might break.

r? ``@traviscross``

…iscross

update `cfg_select!` documentation

tracking issue: rust-lang#115585

After rust-lang#143461, and with an eye on a soon(ish) stabilization, I think the docs need some work.

The existing text read more like a motivation for the feature existing to me, so I've tried to now be a bit more descriptive. Still, suggestions are very welcome.

I also added a test for an empty `select! {}` because it's just the sort of thing that might break.

r? ``@traviscross``

…iscross

update `cfg_select!` documentation

tracking issue: rust-lang#115585

After rust-lang#143461, and with an eye on a soon(ish) stabilization, I think the docs need some work.

The existing text read more like a motivation for the feature existing to me, so I've tried to now be a bit more descriptive. Still, suggestions are very welcome.

I also added a test for an empty `select! {}` because it's just the sort of thing that might break.

r? ``@traviscross``

Rollup merge of #149783 - folkertdev:stabilize-cfg-select, r=JonathanBrouwer

stabilize `cfg_select!`

*[View all comments](https://triagebot.infra.rust-lang.org/gh-comments/rust-lang/rust/pull/149783)*

tracking issue: #115585
closes #115585
reference PR:

- rust-lang/reference#2103

# Request for Stabilization

## Summary

The `cfg_select!` macro picks the expansion corresponding to the first `cfg` condition that evaluates to `true`. It simplifies complex conditional expressions.

```rust
cfg_select! {
    unix => {
        fn foo() { /* unix specific functionality */ }
    }
    target_pointer_width = "32" => {
        fn foo() { /* non-unix, 32-bit functionality */ }
    }
    _ => {
        fn foo() { /* fallback implementation */ }
    }
}

let is_unix_str = cfg_select! {
    unix => "unix",
    _ => "not unix",
};
println!("{is_unix_str}");
```
## Semantics

The expansion of a `cfg_select!` call is the right-hand side of the first `cfg` rule that evaluates to true.

This can be roughly expressed using this macro:
```rust
macro_rules! cfg_select {
    ({ $($tt:tt)* }) => {{
        $crate::cfg_select! { $($tt)* }
    }};
    (_ => { $($output:tt)* }) => {
        $($output)*
    };
    (
        $cfg:meta => $output:tt
        $($( $rest:tt )+)?
    ) => {
        #[cfg($cfg)]
        $crate::cfg_select! { _ => $output }
        $(
            #[cfg(not($cfg))]
            $crate::cfg_select! { $($rest)+ }
        )?
    }
}
```

The actual implementation uses a builtin macro so that `cfg_select!` can be used both in item and expression position.

## Documentation

reference PR:

- rust-lang/reference#2103

## Tests

The `cfg_select!` macro is already used extensively in the rust compiler codebase. It has several dedicated tests:

- [`tests/ui/check-cfg/cfg-select.rs`](https://github.com/rust-lang/rust/blob/main/tests/ui/check-cfg/cfg-select.rs)tests that warnings are emitted when an unexpected `cfg` condition is used.
- [`tests/ui/macros/cfg_select.rs`](https://github.com/rust-lang/rust/blob/main/tests/ui/macros/cfg_select.rs) tests that `cfg_select!` has the expected expansion, and tests that the expected syntax is accepted.
## History

- #115416
- #117162
- #133720
- #135625
- #137198
- #138993
- #138996
- #143461
- #143941
- #145233
- #148712
- #149380
- #149925

# Resolved questions

# Unresolved questions

The style team has decided on how to format `cfg_select!`, but this formatting has not yet been implemented. See #144323.

r? @traviscross

<!-- TRIAGEBOT_START -->

<!-- TRIAGEBOT_CONCERN-ISSUE_START -->

> [!NOTE]
> # Concerns (0 active)
>
> - ~~[allowing-comma-after-closing-brace](#149783 (comment) resolved in [this comment](#149783 (comment))
>
> *Managed by `@rustbot`—see [help](https://forge.rust-lang.org/triagebot/concern.html) for details.*

<!-- TRIAGEBOT_CONCERN-ISSUE_END -->
<!-- TRIAGEBOT_END -->