stabilize cfg_select!

[folkertdev]

tracking issue: #115585
closes #115585
reference PR:

• cfg_select! macro 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.

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:

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:

• cfg_select! macro 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.rstests that warnings are emitted when an unexpected cfg condition is used.
• tests/ui/macros/cfg_select.rs tests that cfg_select! has the expected expansion, and tests that the expected syntax is accepted.

History

• Add the cfg_match! macro #115416
• Remove cfg_match from the prelude #117162
• [cfg_match] Adjust syntax #133720
• [cfg_match] Document the use of expressions. #135625
• Rename cfg_match! to cfg_select! #137198
• Make cfg_match! a semitransparent macro #138993
• Use cfg_match! in core #138996
• make cfg_select a builtin macro #143461
• update cfg_select! documentation #143941
• cfg_select: Support unbraced expressions #145233
• Port cfg_select! to the new attribute parsing system #148712
• Run eval_config_entry on all branches so we always emit lints #149380

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

[ehuss]

Happy to see this move forward!

Is there a detailed description of how this macro works? For example:

• What is the grammar that it accepts?
• How does it expand? For example, it seems like if the RHS uses braces, the braces are implicitly removed.
• Am I correct that whether or not this fails to compile depends on the current cfg's for the current target/environment? That is, there is essentially an implicit _ => {compile_error!()} as the last rule?
• Is it correct that this did not suffer the same fate as assert_matches because the name cfg_select is not in use by any known libraries? (Just curious, cfg_select has already been in the prelude for a while and nobody complained.)
• Is there a reason the unreachable predicate warning isn't a lint? (The main reason I ask is because this prevents -D warnings from catching it.)
• Am I correct that the RHS is not parsed unless it is the arm that is selected? That is, the right hand side can contain any token tree?

[rustbot]

Some changes occurred in compiler/rustc_codegen_cranelift

cc @bjorn3

The Miri subtree was changed

cc @rust-lang/miri

[folkertdev]

Is there a detailed description of how this macro works? For example:

Not yet, I think.

What is the grammar that it accepts?

In item positions the body should consist of zero or more

('_' | ConfugurationPredicate) => { TokenTree }

In expression position we additionally accept

('_' | ConfugurationPredicate) => Expr,

How does it expand? For example, it seems like if the RHS uses braces, the braces are implicitly removed.

That is correct, one level of braces is removed if braces are used.

Am I correct that whether or not this fails to compile depends on the current cfg's for the current target/environment? That is, there is essentially an implicit _ => {compile_error!()} as the last rule?

Yes if none of the conditions evaluate to true you'll get a compile error (note: earlier iterations did not have this default behavior)

Is it correct that this did not suffer the same fate as assert_matches because the name cfg_select is not in use by any known libraries? (Just curious, cfg_select has already been in the prelude for a while and nobody complained.)

The ecosystem mostly uses cfg_if. But I'll defer to T-libs-api on whether this is exported from all the right places.

Is there a reason the unreachable predicate warning isn't a lint? (The main reason I ask is because this prevents -D warnings from catching it.)

I don't think there is a reason. We could make it a lint (or add it to an existing one?)

Am I correct that the RHS is not parsed unless it is the arm that is selected? That is, the right hand side can contain any token tree?

Yes, the rhs can be any token tree.

[traviscross]

Is there a reason the unreachable predicate warning isn't a lint? (The main reason I ask is because this prevents -D warnings from catching it.)

I don't think there is a reason. We could make it a lint (or add it to an existing one?)

For my part, it seems worth doing this. Then we can stabilize this lint along with this FCP. Perhaps a new lint named unreachable_cfgs would be correct. The name is by analogy to unexpected_cfgs and unreachable_patterns.

(In the alternate, if we did want "predicate" in the name, I'd suggest unreachable_cfg_predicates.)