Tracking issue for cfg_match

[c410-f3r]

Provides a native way to easily manage multiple conditional flags without having to rewrite each clause multiple times.

Public API

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

Steps / History

• Implementation (Add the cfg_match! macro #115416)
• Final comment period
• Stabilization PR

Unresolved Questions

• What should the final syntax be? A match-like syntax feels more natural in the sense that each macro fragment resembles an arm.
• Should the macro be supported directly by a language feature?
• What should the feature name be? cfg_match conflicts with the already existing cfg_match crate.
• How can we support usage in both expression-position and item position?
• Support trailing commas to have similar grammar as match statements.

References

• https://crates.io/crates/cfg-match
• https://crates.io/crates/cfg-if
• Tracking issue for cfg_if #59442
• https://internals.rust-lang.org/t/is-cfg-if-going-to-be-pulled-into-std/13316

[madsmtm]

I think it needs to be considered how this will interact with doc_auto_cfg?

Also, if this is intended to be match-like, then it seems weird to me that you can omit a fallback implementation? Unless of course all the possible combinations are statically known to be accounted for (which is hard, I know).

[CAD97]

Modulo (auto) doc(cfg), this implementation is more complex than it needs to be, since it's only supporting items.

simpler impl

#[macro_export]
macro_rules! cfg_match {
    {
        cfg($cfg:meta) => { $($cfg_items:item)* }
        $(cfg($rest_cfg:meta) => { $($rest_cfg_items:item)* })*
        $(_ => { $($fallthrough_items:item)* })?
    } => {
        #[cfg($cfg)]
        $crate::cfg_match! {
            _ => {
                $($cfg_items)*
                // validate the inactive cfgs as well
                #[cfg(any($($rest_cfg),*))]
                const _: () = ();
            }
        }
        #[cfg(not($cfg))]
        $crate::cfg_match! {
            $(cfg($rest_cfg) => { $($rest_cfg_items)* })*
            $(_ => { $($fallthrough_items)* })?
        }
    };
    {
        $(_ => { $($items:item)* })?
    } => {
        $($($items)*)?
    };
}

No internal matching arms necessary; just a normal inductive definition over the input syntax. The one tricky difference is that without the extra #[cfg] const item in the positive arm, later cfg predicates wouldn't be validated where they would be with the current implementation which always builds the full #[cfg(all(yes, not(any(...))))] matrix out.

This can be rather simply adapted to expression position by matching a block and using break with value.

---

It's unfortunate though that implemented without compiler support cfg_match! is effectively limited to either supporting item position or expression position. Supporting both needn't block supporting only item position (the more necessary position, since expression context can use if cfg!() else if chains most of the time), but it'd be nice to ensure there's a path forward for a compiler enhanced version which can expand differently between item and expression position, so the macro can be made to just work on both.

[madsmtm]

Something else to consider: This should be able to detect invalid cfgs like the following (ideally regardless of whether the cfg is currently enabled or not):

match_cfg! {
    cfg(unix) => {}
    cfg(unix) => {} // Ooops, specified same `cfg` twice
    _ => {}
}

[thomcc]

I would prefer if it could support both items and expressions. It being part of the stdlib means that implementing it in the compiler would be completely reasonable, and would also make a lint that warns on redundant cfg arms pretty doable.

[jhpratt]

For detecting duplicates, it's important to note that this is more difficult than it seems at first. rustdoc has been dealing with this for doc(cfg).

[CAD97]

I tested the current (1.74.0-nightly (e6aabe8b3 2023-09-26)) behavior of doc_auto_cfg: items defined in cfg_match! do not receive a portability info box. Theoretically cfg dependencies could be tracked through macro expansion, but that's not done currently; cfg dependencies are only recorded on items.

Fixing this is actually fairly simple once you understand why this is: instead of expanding to #[cfg($cfg)] identity! { $($items)* }, splat the cfg directly onto each item with $(#[cfg($cfg)] $items)*. The match_cfg crate does this; the cfg_if crate doesn't. A quick scan through the library directory didn't reveal any places where splatting cfg through cfg_if! would change documentation.

I want to additionally point out that doc_auto_cfg fundamentally can only see what items are defined on the current cfg and mark them as only available on whatever cfg this specific implementation is gated to. If you want to expose a portable API, either define a single portable public version of the API (and use private cfg gates to implement it) or use doc(cfg()) to explicitly tell rustdoc what gate it should display as.

So what I personally think the macro definition wants to be:

in item position

#[macro_export]
macro_rules! cfg_match {
    // base case without wildcard arm
    () => {};

    // base case with wildcard arm (items)
    (_ => { $($wild_item:item)* }) => {
        $($wild_item)*
    };

    // process first arm (items; propagate cfg)
    (
        cfg($this_cfg:meta) => { $($this_item:item)* }
        $(cfg($rest_cfg:meta) => { $($rest_item:item)* })*
        $(_ => { $($wild_item:item)* })?
    ) => {
        $(#[cfg($this_cfg)] $this_item)*
        $crate::cfg_match! {
            $(cfg($rest_cfg) => { $(#[cfg(not($this_cfg))] $rest_item)* })*
            $(_ => { $(#[cfg(not($this_cfg))] $wild_item)* })?
        }
    };
}

in expression position

#[macro_export]
macro_rules! cfg_match {
    // base case without wildcard arm
    () => {};

    // base case with wildcard arm (expression block)
    (_ => $wild:block) => {
        $wild
    };

    // process first arm (expression block)
    (
        cfg($this_cfg:meta) => $this:block
        $(cfg($rest_cfg:meta) => $rest:block)*
        $(_ => $wild:block)?
    ) => {
        {
            #[cfg($this_cfg)]
            $crate::cfg_match! {
                _ => $this
            }
            #[cfg(not($this_cfg))]
            $crate::cfg_match! {
                $(cfg($rest_cfg) => $rest)*
                $(_ => $wild)?
            }
        }
    };
}

in statement position

#[macro_export]
macro_rules! cfg_match {
    // base case without wildcard arm
    () => {};

    // base case with wildcard arm
    (_ => { $($wild:tt)* }) => {
        $($wild)*
    };

    // process first arm
    (
        cfg($this_cfg:meta) => { $($this:tt)* }
        $(cfg($rest_cfg:meta) => { $($rest:tt)* })*
        $(_ => { $($wild:tt)* })?
    ) => {
        #[cfg($this_cfg)]
        $crate::cfg_match! {
            _ => { $($this)* }
        }
        #[cfg(not($this_cfg))]
        $crate::cfg_match! {
            $(cfg($rest_cfg) => { $($rest)* })*
            $(_ => { $($wild)* })?
        }
    };
}

This technically is the most flexible spelling just passing through tt sequences; it works perfectly for items and statements (modulo preserving doc_auto_cfg) and can even be used for expressions if wrapped inside an outer block (e.g. { cfg_match! { ... } }).

---

There's also the further question of how much syntax checking is expected for inactive arms. The current implementation that matches everything as $($:item)* does full syntax validation, but a naive implementation forwarding tokens context-antagonistically as $($:tt)* can easily cfg out tokens without ever placing them in a syntax-validated position -- in fact the above statement macro form does this.

A far too overly clever implementation:

#[macro_export]
macro_rules! cfg_match {
    // base case (wildcard arm)
    () => {};

    // base case (no wildcard arm)
    (_ => { $($wild:tt)* }) => {
        $($wild)*
    };

    // Note: macro patterns matching $:stmt need to come before those matching
    // $:item, as otherwise statements will match as the $:item pattern instead
    // even when not valid as items (and obviously thus cause a syntax error).

    // apply cfg to wildcard arm (expression position)
    (_ => #[cfg($cfg:meta)] { $wild:expr }) => {
        { #[cfg($cfg)] { $wild } }
    };

    // apply cfg to wildcard arm (statement position)
    (_ => #[cfg($cfg:meta)] { $wild_stmt:stmt; $($wild:tt)* }) => {
        #[cfg($cfg)]
        $crate::cfg_match! {
            _ => { $wild_stmt; $($wild)* }
        }

        // We only parse the first statement in the macro pattern, so we need to
        // emit the captured syntax even when the cfg is inactive such that any
        // syntax errors still get reported. We do the macro capture this way as
        // if we match as statements, minor typos try to parse as items instead.
        #[cfg(any())]
        const _: () = { wild_stmt; $($wild)* };
    };

    // apply cfg to wildcard arm (item position)
    (_ => #[cfg($cfg:meta)] { $($wild:item)* }) => {
        $(#[cfg($cfg)] $wild)*
    };

    // merge multiple cfg into a single cfg(all()) predicate
    (_ => $(#[cfg($cfg:meta)])+ { $($wild:tt)* }) => {
        $crate::cfg_match! {
            _ => #[cfg(all($($cfg),+))] { $($wild)* }
        }
    };

    // split off first arm (empty)
    (
        cfg($this_cfg_arm:meta) => $(#[cfg($this_cfg_pre:meta)])* { /* empty */ }
        $(cfg($rest_cfg_arm:meta) => $(#[cfg($rest_cfg_pre:meta)])* { $($rest:tt)* })*
        $(_ => $(#[cfg($wild_cfg_pre:meta)])* { $($wild:tt)* })?
    ) => {
        $crate::cfg_match! {
            $(cfg($rest_cfg_arm) => $(#[cfg($rest_cfg_pre)])* #[cfg(not($this_cfg_arm))] { $($rest)* })*
            $(_ => $(#[cfg($wild_cfg_pre)])* #[cfg(not($this_cfg_arm))] { $($wild)* })?
        }
    };

    // split off first arm (expression position)
    (
        cfg($this_cfg_arm:meta) => $(#[cfg($this_cfg_pre:meta)])* { $this:expr }
        $(cfg($rest_cfg_arm:meta) => $(#[cfg($rest_cfg_pre:meta)])* { $rest:expr })*
        $(_ => $(#[cfg($wild_cfg_pre:meta)])* { $wild:expr })?
    ) => {{
        $crate::cfg_match! {
            _ => $(#[cfg($this_cfg_pre)])* #[cfg($this_cfg_arm)] { $this }
        }
        $crate::cfg_match! {
            $(cfg($rest_cfg_arm) => $(#[cfg($rest_cfg_pre)])* #[cfg(not($this_cfg_arm))] { $rest })*
            $(_ => $(#[cfg($wild_cfg_pre)])* #[cfg(not($this_cfg_arm))] { $wild })?
        }
    }};

    // split off first arm (statement position)
    (
        cfg($this_cfg_arm:meta) => $(#[cfg($this_cfg_pre:meta)])* { $this_stmt:stmt; $($this:tt)* }
        $(cfg($rest_cfg_arm:meta) => $(#[cfg($rest_cfg_pre:meta)])* { $($rest:tt)* })*
        $(_ => $(#[cfg($wild_cfg_pre:meta)])* { $($wild:tt)* })?
    ) => {
        $crate::cfg_match! {
            _ => $(#[cfg($this_cfg_pre)])* #[cfg($this_cfg_arm)] { $this_stmt; $($this)* }
        }
        // Ensure all arms infer statement position by prefixing a statement. We
        // only match the first arm in the macro pattern because otherwise minor
        // typos unhelpfully cause all arms to parse as item definitions instead
        // and thus reporting an error nowhere near the actual problem, or even
        // more amusingly, accidentally providing automatic semicolon insertion.
        $crate::cfg_match! {
            $(cfg($rest_cfg_arm) => $(#[cfg($rest_cfg_pre)])* #[cfg(not($this_cfg_arm))] { {}; $($rest)* })*
            $(_ => $(#[cfg($wild_cfg_pre)])* #[cfg(not($this_cfg_arm))] { {}; $($wild)* })?
        }
    };

    // split off first arm (item position)
    (
        cfg($this_cfg_arm:meta) => $(#[cfg($this_cfg_pre:meta)])* { $($this:item)* }
        $(cfg($rest_cfg_arm:meta) => $(#[cfg($rest_cfg_pre:meta)])* { $($rest:item)* })*
        $(_ => $(#[cfg($wild_cfg_pre:meta)])* { $($wild:item)* })?
    ) => {
        $crate::cfg_match! {
            _ => $(#[cfg($this_cfg_pre)])* #[cfg($this_cfg_arm)] { $($this)* }
        }
        // Items just match as item in the macro pattern. The error messages
        // would be improved if we could pass through tokens without eagerly
        // matching them as items, but we need to parse the items in the macro
        // so that we can apply the cfg attributes to every item in the arm.
        $crate::cfg_match! {
            $(cfg($rest_cfg_arm) => $(#[cfg($rest_cfg_pre)])* #[cfg(not($this_cfg_arm))] { $($rest)* })*
            $(_ => $(#[cfg($wild_cfg_pre)])* #[cfg(not($this_cfg_arm))] { $($wild)* })?
        }
    };
}

This does almost always behave as desired by using the arm bodies to try to guess how to expand, but is unreasonably complicated by attempting to do so and as a result causes some very poor errors for reasonable syntax errors.

[c410-f3r]

Well, since #115416 (comment) I have been working in transposing cfg_match to a builtin in order to easily allow single elements in an arm without brackets. Such thing will also permit any other feature that is being discussed here AFAICT.

It is worth noting that the current implementation mimics cfg_if and allows the expansion of token trees because cfgs are applied to macro calls as @CAD97 previously commented.

cfg_match! {
    cfg(unix) => { fn foo() -> i32 { 1 } },
    _ => { fn foo() -> i32 { 2 } },
}

# Expands to ->

#[cfg(all(unix, not(any())))]
cfg_match! { @__identity fn foo() -> i32 { 1 } }

#[cfg(all(not(any(unix))))]
cfg_match! { @__identity fn foo() -> i32 { 2 } }

That said, changing the strategy to apply cfg on each element inside a block will trigger stmt_expr_attributes (https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=4cf4facc19b052053cca655b2b42f782) for expressions and conceivably/possibly/maybe/perhaps, a large set of elements along a large set of cfgs could affect compilation times. But, it seems to be the correct approach due to doc_auto_cfg.

[petrochenkov]

FWIW, #[cfg(TRUE)] not being removed from items during expansion is a bug, and reliance of rustdoc on that bug is very unfortunate.

What we need to do is to keep expansion backtraces for cfgs like we do for all other macros.
In that case it won't be important whether a cfg is placed directly on an item, or somewhere higher in the expansion tree (like on a macro producing that item), it will be available from the macro backtrace anyway.

[Nemo157]

I just found out about this today, and my first impression is that semantically this isn't really a "match", given the equivalent way to write a similar runtime match would be:

match () {
    () if unix => { ... }
    () if target_pointer_width.contains("32") => { ... }
    _ => { ... }
}

A more similar construct in my mind are the select! family of macros, std::select!, crossbeam::select!, futures::select!, tokio::select!. The primary difference between those macros and this one is that in this one all the patterns are boolean valued so don't need a pattern, just the <expr> => { <arm> },.

All that is to say that cfg_select! seems like a better name to me.

[tmandry]

This is very adjacent to a core language feature, and procedurally I think extending that feature with a macro in core should involve lang input.

@rustbot label I-lang-nominated

Personally I am very much in favor of improving the usability of cfg. We should consider whether the use cases of this macro are better addressed with language features, as in the discussions happening in rust-lang/rfcs#3796 and rust-lang/rfcs#3804, or how those RFCs would interact with this macro if both were accepted.

If we do accept this macro and it accepts novel syntax for matching against cfgs (like using | to match against different values), we should consider whether that is something we ought to accept in the language too.

[joshtriplett]

@tmandry To the best of my understanding, cfg_match! as currently implemented does not add any novel cfg syntax. I would expect that if and when we add extensions to the cfg syntax, we'll add the same extensions to cfg_match!, but I don't anticipate us adding cfg_match! extensions that aren't in cfg.

[scottmcm]

nitpick: arguably this is cfg_cond! if it accepts foo == "32" like that -- it's not cfg_match! { pointer_width { "32" => ..., "64" => ... } }.

But I'm happy to let libs-api argue about that :)

---

Abstractly I agree that this is a helpful thing that would be nice to have, in at least some form.

[joshtriplett]

@scottmcm and others in the lang meeting made the point that while we can't necessarily enforce exhaustiveness, we might want to consider the possibility of having an implicit _ => compile_error!(...) or _ => compile_warning!(...), such that you have to write _ => {} if you really want it to expand to nothing in that case.

I don't know if we want to do that by default, or if we want that to be a lint of some kind, but either way, it's worth considering. @rust-lang/libs-api

[traviscross]

Based on having discussed this, and based on other recent related discussions such as the ones @tmandry mentions, I'm feeling more strongly than I did in the past that if we want to include match in the name, it should do what it can to simulate exhaustiveness, and so I'd prefer to see it give a compiler error if it reaches a case that is not covered by an arm. That will, in practice I think, give the code that people write with this more of the "flavor" of a match, increasing language cohesiveness.

[ChrisDenton]

Note: libs-api's previous decision on the naming is here: #137198

[traviscross]

@rustbot labels +I-libs-api-nominated

Nominating for libs-api to consider feedback from lang discussion.

[tmandry]

To the best of my understanding, cfg_match! as currently implemented does not add any novel cfg syntax. I would expect that if and when we add extensions to the cfg syntax, we'll add the same extensions to cfg_match!, but I don't anticipate us adding cfg_match! extensions that aren't in cfg.

Sounds good then.

we might want to consider the possibility of having an implicit _ => compile_error!(...) or _ => compile_warning!(...), such that you have to write _ => {} if you really want it to expand to nothing in that case.

if we want to include match in the name, it should do what it can to simulate exhaustiveness, and so I'd prefer to see it give a compiler error if it reaches a case that is not covered by an arm. That will, in practice I think, give the code that people write with this more of the "flavor" of a match, increasing language cohesiveness.

I'm somewhat persuaded by these. If there were a strong reason not to do this it would be okay not to, though I might also quibble with the name in that case. But it feels like a nice way to tie things together, while guarding against unplanned config combinations with an explicit error message.

[folkertdev]

I don't see this mentioned yet: I expect this to work (e.g. concat! does work in that position)

#![feature(cfg_match)]

fn main() {
    println!(cfg_match! {{
        unix => { "foo" }
        _ => { "bar" }
    }});
}

I believe given the current grammar https://doc.rust-lang.org/src/core/macros/mod.rs.html#330, the { ... } on the right-hand side of the => is required.

But I believe that, in expression contexts at least, that expands to a Expr::Block. In the case of some builtin macros like format!, that hits this error branch:

rust/compiler/rustc_builtin_macros/src/util.rs

Line 129 in 5fe04cb

_ => Ok((cx.dcx().struct_span_err(expr.span, err_msg), false)),

The quick fix is to accept a block containing a string literal, I guess? I don't think there is a better solution when using macro_rules! but the extra Expr::Block wrapper is inelegant.

[alice-i-cecile]

FYI, Bevy has added its own version of this in bevyengine/bevy#18822, primarily to rein in virality of std feature flags. The PR description and comments are worth a read there, and I'd be happy to connect you with our contributors if you want user feedback on designs.

[traviscross]

On the libs-api call today, this was discussed at some length. Here's where it landed:

• We want to name this cfg_select!.
• If an uncovered case is actually encountered, a compiler error is emitted.
• We don't want to stabilize the cfg_select! {{ .. }} (double braces) expression-position syntax.
• We don't want to stabilize it yet in expression position at all, unless it's wrapped in outer braces, e.g. { cfg_select! { .. } }.

On the name, the more we talked about it, the more we continued to develop cold feet about calling this a kind of match. The reasons are essentially those that have been discussed in this thread; they just kept adding up. At the end of the day, it's not doing "matching", as Rust means it, it's evaluating a list of conditions, in order, and picking the first arm where the condition evaluates as true.

We committed to and engaged in a thorough syntactic bikeshed to pick a better name. The two candidates that came out of that as plausible -- with general support and few objections -- were cfg_cond and cfg_select.

The downside of cond is that, while it suggests "conditional" and is used in other languages with the semantic here, it would be new and novel jargon for many Rust programmers. The upside is that, by being new, it would have no baggage in terms of alternate common meanings in our ecosystem.

The upside of select is that it is more familiar, due to existing use in our ecosystem, and it reads as a verb. The downside is that it does carry the baggage of alternate meanings from use in the ecosystem, such as Tokio's select!, where the macro has a different syntax and polls the future on each arm.

In the end, we leaned in favor of the name with more existing familiarity and that could be read as a verb, and went with cfg_select.

Not including match in the name removes the objections of a lang nature to this not being exhaustive. However, based on general Rust principles of trying to push errors to the earliest possible point, many of us still felt that giving an error if an uncovered case is encountered remains a virtue. Often, an uncovered case would end up simply leading to an error or undesired behavior later. So on that basis, we'd like the cfg_select! macro to emit code that produces a compiler error upon reaching an uncovered case.

Currently, the macro supports an expression-position syntax that requires the use of double braces such as cfg_select! {{ .. }}. People thought this was weird and nobody wanted to stabilize this, so this needs to be removed.

More generally, we felt that there were a number of open questions we should address regarding the behavior of this macro in expression position.

One, while we were OK with always requiring the arm body to be braced in item position, we were still discussing the merits of allowing unbraced arm bodies in expression position.

Two, currently, the macro always returns a block, and this creates problems for use in places such as operand position for inline assembly, as discussed in #140279, #140367 (comment), and #115585 (comment). The way the macro returns the body is observable -- e.g., in Rust 2024, blocks have different behavior with respect to temporary lifetimes -- and so we should make sure the behavior is what we want prior to stabilizing in a way this could be observed. Probably this macro will need to become a built-in compiler macro.

Some were fine with simply blocking on that implementation work being done. Another option, though, is that we discussed that we'd be OK with stabilizing this only in item position and in expression position when wrapped in outer braces such as { cfg_select! { .. } }.

Thanks to everyone in this thread for the many useful bits of analysis and feedback that were helpful in arriving at this point after some back and forth.

The plan is to cancel the current proposed FCP and to then restart it (with lang) with the proposal as detailed in this comment once updates have been made to the implementation.

[Amanieu]

@rfcbot cancel

[rfcbot]

@Amanieu proposal cancelled.