RFC: naming groups of configuration with `cfg_alias` #3804

tgross35 · 2025-04-23T23:44:34Z

This proposal introduces a way to name configuration predicates for easy reuse throughout a crate.

#![cfg_alias(
    x86_linux,
    all(any(target_arch = "x86", target_arch = "x86_64"), target_os = "linux")
)]

#[cfg(x86_linux)]
fn foo() { /* ... */ }
#[cfg(not(x86_linux))]
fn foo() { /* ... */ }

Previous discussion:

Rendered

tmandry · 2025-04-23T23:52:51Z

text/3804-cfg-alias.md

+- The syntax `cfg_alias(name, predicate)` was chosen for similarity with
+  `cfg_attr(predicate, attributes)`. Alternatives include:
+  - `cfg_alias(name = predicate)`


I prefer the = form. cfg_attr doesn't seem like a compelling precedent when the predicate goes first with cfg_attr and second with cfg_alias.

I also happen to think the cfg_attr syntax is hard to read, we should avoid replicating that :)

cfg_attr is definitely not very nice to read or write (though, I don't really know what would have been better here). Reading through it more, I am also starting to prefer = but one concern is that = in config is used for something like equality rather than assignment. Should there be any concern about that here?

I know that also came up in discussion at #3796

I have updated the syntax to use =

One other downside: with =, it looks a bit weird when aliasing a single = option

#![cfg_alias(alias = target_os = "linux")]

Ah, that is a negative. I'll retract my preference then. I'm not crazy about the comma but it's closest to what we have..

We could choose to require parens there.

text/3804-cfg-alias.md

tmandry · 2025-04-23T23:59:39Z

text/3804-cfg-alias.md

+
+[RFC3697]: https://github.com/rust-lang/rfcs/pull/3697
+
+# Rationale and alternatives


Inspired by the above, one alternative that comes to mind is declarative attribute macros that do the cfg matching for you. I think actually you have to declare two macros, one when the cfg you want is true and one when it is false, so that's a major drawback because it would require repeating the same clause twice.

However, attribute macros (possibly in combination with this feature) would allow a crate to "export" an alias.

Great point, I'll mention that. One other downside is that with a specific set of config tied to an attribute macro, it wouldn't be easily possible to combine with other config in all or any (could probably be done with the attribute macro's parameters).

Exporting would be quite convenient at times.

Good point that the macro approach doesn't compose all that well. I wish there was an obvious way to support exporting these.

For a more radical design, it might be possible to treat aliases as effectively a new kind of macro; something that shares the macro namespace but only expands within cfg. I think this would mean the new macro scoping can be used, so pub use some_alias can make an alias crate-public for another crate to import with use crate_with_alias::some_alias.

It sounds borderline too complex for an otherwise pretty simple feature, but being able to do that could be a nice help if public macros expand to code that contains #[cfg(...)].

With that, it would almost be possible to define the builtin cfg(windows)/cfg(unix) as something like cfg_alias(windows = target_os = "windows") in the prelude (not that we'd have any reason to actually do that).

I would expect some kind of way to export an alias. I'd be disappointed with a design that wouldn't permit it.

Anyway, your comment about macros made me think of something like...

// library #[macro_export] macro_rules! has_atomics { () => { any(target = a, target = b, .. ) } } // crate #[cfg(has_atomics!())] fn blah(){}

That has the advantage of not needing a new kind of attribute or new syntax to define an alias. It also makes it obvious when an alias is being used.

Moreover this syntax implies that you can pass arguments.

Let me give an example where this would be useful to me personally. The Python C api has different ABI guarantees. Take PyObject_Vectorcall for example. This function was added in Python 3.9, but only in 3.12 it was added to the Stable ABI.

That means I define the bindings as:

extern "C" { #[cfg(any(Py_3_9, all(Py_3_12, not(Py_LIMITED_API))))] pub fn PyObject_Vectorcall(..) -> ...

This would be a lot simpler if the syntax is macro-like:

macro_rules! limited { ($added_in:ident) => { all($added_in, not(Py_LIMITED_API)) } ($added_in:ident, $stable_in:ident) => { any($stable_in, all($added_in, not(Py_LIMITED_API))) } } #[cfg(limited!(Py_3_9, Py_3_12))] // ...

I do think @mejrs that this would be quite nice. I suspect it might be difficult to implement, though. Maybe what's needed is an experiment.

+1 for that.

text/3804-cfg-alias.md

…eck-cfg

oxalica · 2025-04-24T03:21:29Z

#![cfg_alias(some_alias = predicate)]

I'm against syntax cfg_alias(ident = predicate) and prefer cfg_alias(ident, predicate), because of consistency concerns:

We already have a very similar cfg_attr(predicate, meta) syntax. cfg_alias(ident, predicate) just flips it and identifier is also a valid meta. Using comma here is most natural and consistent design.
path(ident = meta) is a completely new syntax that does not exist anywhere, and contradicts the status quo that = always follows an expression, adding cognitive complexity for human. See current "meta" grammar in reference. Not sure if it will introduce actual implementation complexity.
As mentioned above, #![cfg_alias(name = target_os = "linux")] has two = with different meaning which is very confusing. Same situation can also occur when nesting cfg_alias inside other attributes or vice versa.

programmerjake · 2025-04-24T04:36:03Z

text/3804-cfg-alias.md

+```rust
+#![cfg_alias(todo = false)] // change `false` to `true` to enable WIP code
+
+#[cfg(todo)]


In #3804 (comment) I had meant more that you could use #[cfg(todo)] as an attribute you could add/delete from sections of code, rather than toggling todo's value. So it would be kinda like how todo!() always panics, rather than disappearing if you toggle some flag.

e.g.:

#[cfg(todo)] pub fn uses_some_api_that_isnt_finished() { api::cool_function_that_doesnt_exist_yet(); }

later, once that api is implemented, you can just delete the #[cfg(todo)] line to have your code no longer be skipped.

traviscross · 2025-04-24T20:12:36Z

text/3804-cfg-alias.md

+`predicate` can be anything that usually works within `#[cfg(...)]`, including
+`all`, `any`, and `not`.


I'd probably drop ", including..." here as it makes it more rather than less ambiguous. Alternatively, it'd be OK to say e.g. "including (but not limited to) combining operators such as all, any, and not.

traviscross · 2025-04-24T20:13:59Z

text/3804-cfg-alias.md

+```text
+CfgAliasAttribute:
+    cfg_alias(IDENTIFIER `=` ConfigurationPredicate)
+```


Have a look at the grammar syntax in the Reference. Probably best to just use that.

traviscross · 2025-04-24T20:30:10Z

text/3804-cfg-alias.md

+`cfg_alias` may also be used as a module-level attribute rather than
+crate-level:


Why module level? Once we eat the cost of making these scoped, I'm curious if there's a reason we shouldn't specify them for other scopes also.

In terms of how we specify the language, it actually makes the specification simpler to have fewer rather than more exceptions. (We can always of course still incrementally stabilize if there are reasons to do so.)

Of course, if we go with a different design, such as leaning into macros somehow, then we could sidestep this question.

traviscross · 2025-04-24T20:33:25Z

text/3804-cfg-alias.md

+- It may be possible to have `#[cfg_alias(...)]` work as an outer macro and only
+  apply to a specific scope. This likely is not worth the complexity.


Suggested change

- It may be possible to have `#[cfg_alias(...)]` work as an outer macro and only

apply to a specific scope. This likely is not worth the complexity.

Since this has now been added to the RFC, this alternative can be removed.

traviscross · 2025-04-24T20:36:31Z

text/3804-cfg-alias.md

+- Substitution vs. evaluation at define time (the question under the
+  reference-level explanation)


Suggested change

- Substitution vs. evaluation at define time (the question under the

reference-level explanation)

- Substitution vs. evaluation at define time (the question under the

reference-level explanation).

ogoffart · 2025-04-24T21:54:41Z

text/3804-cfg-alias.md

+- It may be possible to have `#[cfg_alias(...)]` work as an outer macro and only
+  apply to a specific scope. This likely is not worth the complexity.
+
+# Prior art


The cfg_aliases crate could be mentioned. https://crates.io/crates/cfg_aliases

kennytm · 2025-04-25T08:06:22Z

text/3804-cfg-alias.md

+The identifier is added to the `cfg` namespace. It must not conflict with:
+
+- Any builtin configuration names
+- Any configuration passed via `--cfg`


to clarify, if we passed --cfg 'foo="bar"', it means cfg_alias(foo, ...) will be also conflicting right?

joshtriplett · 2025-04-27T17:34:18Z

text/3804-cfg-alias.md

+    // Enabled/disabled based on `cfg(baz)`
+    #[cfg(foo)]
+    fn qux() { /* ... */ }
+}


Please add some details on hygiene. For instance, what happens if you write a cfg_alias on a macro_defining_a_fn!()? Does the macro "see" the alias set, ignoring hygiene? Or do you need to pass the identifier into the macro (e.g. macro_defining_a_fn!(the_alias), so that hygiene works? I would expect the latter.

cc @ehuss @eholk

joshtriplett · 2025-04-27T17:35:48Z

text/3804-cfg-alias.md

+
+- A `--cfg-alias` CLI option would provide a way for Cargo to interact with this
+  feature, such as defining config aliases in the workspace `Cargo.toml` for
+  reuse in multiple crates.


Suggested change

reuse in multiple crates.

reuse in multiple crates.

- We could add a visibility to the syntax, allowing a crate to export a cfg alias for use by other crates.

madsmtm · 2025-05-02T10:46:28Z

text/3804-cfg-alias.md

+_RFC question: "usable only after definition" is mentioned here to retain the
+ability to parse attributes in order, rather than going back and updating
+earlier attributes that may use the alias. Is this a reasonable limitation to
+keep?_


An alternative, which might be more consistent with allowing this attribute more generally at a module/item level:

The cfg alias is available in the inner scope of the item.

This would preclude using cfg aliases for crate-level attributes, unless we implement it in Cargo as well, but it would also avoid difficult concerns with ordering:

#[cfg_alias(some_alias = true)] // declare alias #[cfg_attr(some_alias, some_attribute)] // warning: unexpected_cfgs mod foo { #[cfg_attr(some_alias, some_attribute)] // works mod bar {} } #[cfg_attr(some_alias, some_attribute)] // warning: unexpected_cfgs mod xyz {}

madsmtm · 2025-05-02T10:48:59Z

text/3804-cfg-alias.md

+#endif
+```
+
+# Unresolved questions


If we decide that the complexity of allowing this at a module level is too high, that is, only allowing it as a crate attribute, then I would argue that the feature would be better suited to only being accessible in Cargo / --cfg-alias.

madsmtm · 2025-05-02T10:57:50Z

text/3804-cfg-alias.md

+- A `--cfg-alias` CLI option would provide a way for Cargo to interact with this
+  feature, such as defining config aliases in the workspace `Cargo.toml` for
+  reuse in multiple crates.


I strongly suspect that having this feature in Cargo will be desired, and that having it there would solve 90% of the use-case for this feature.

Implementation-wise, I also suspect that doing it would be possible and fairly simple in Cargo today by parsing the cfg itself (it already understands cfgs as part of dependency resolving), and then passing extra --cfgs / --check-cfgs to the compiler.

So maybe it would be valuable to implement (or at least stabilize) the ability for doing this in Cargo first, and only later consider making this an attribute in the language itself?

This gets into a weird gray area of Cargo.

Defining --cfgs is a rustc concept that is lower level than Cargo. In fact, there was a proposed [cfg] table for --check-cfg which as rejected for that reason. Instead, cfgs are either defined by the environment or by [features]. We do recognize there is a gap for more --cfg use cases and have done some brainstorming on "global features" but more work is needed.

Cargo does allow reading of cfg's through build script environment variables and through target.* tables.

Depending on how you look at it, a --cfg-alias is like --cfg and too low level for Cargo. As people want --cfgs to influence "global features", maybe there is something there that can be designed that can fill both needs. Or --cfg is a helper for #[cfg()]s and would fit similar to build scripts and target.* tables.

As pointed out, there is a build script to emulate cfgs: https://github.com/rust-lang/rfcs/pull/3804/files#r2059296180

With metabuild, we could go a step further in semi-native cargo support. This would allow something like

[[package.build]] dependency = "cfg_aliases" cfg = { wasm = 'target_arch = "wasm32"', android = 'target_os = "android"', surfman = 'all(unix, feature = "surfman", not(wasm))' }

(newlines in the inline table is me being hopeful that TOML 1.1 is finally unblocked)

epage · 2025-05-02T13:47:56Z

text/3804-cfg-alias.md

+Once an alias is defined, `name` can be used as if it had been passed via
+`--cfg`:
+
+```rust
+#[cfg(some_alias)]
+struct Foo { /* ... */ }
+
+#[cfg(not(some_alias))]
+struct Foo { /* ... */ }
+
+#[cfg(all(some_alias, target_os = "linux"))]
+fn bar() { /* ... */ }
+```


Could you add an example of an alias being used within an alias to make clear that that should work.

The example in https://crates.io/crates/cfg_aliases provides a good motivating case. Might also be good to pull ideas from that readme for the Summary section

epage · 2025-05-02T13:51:05Z

text/3804-cfg-alias.md

+The identifier is added to the `cfg` namespace. It must not conflict with:
+
+- Any builtin configuration names
+- Any configuration passed via `--cfg`
+- Any configuration passed with `--check-cfg`, since this indicates a possible
+  but omitted `--cfg` option
+- Other aliases that are in scope


Does this make the compatibility hazard worse than today? Code can work perfectly fine but will then break if a new builtin is added or somewhere else in the dependency tree defines a new cfg where the end-user would do RUSTFLAGS=--cfg=... (remember: RUSTFLAGS are generally global to the entire dependency tree)

Is that acceptable? Or can we mitigate this somehow?

I had almost left this same comment, nearly word for word, last week, and then I had thought to myself, "well, that's kind of already the case, isn't it? Someone could be doing RUSTFLAGS=--cfg=foo in CI, and then one of the deps could unrelatedly add a #[cfg(foo)] somewhere, and that would at best break, or at worst change behavior in some unexpected way."

Someone else had brought the issue up and I also discarded it but I wasn't aware of the erroring part of this at the time.

I feel I had come up with a case for why --cfg foo and cfg_alias(foo) are different but its unfortunately escaping me now that I have an opportunity to type it up.

I suspect that --cfg foo affecting a cfg_alias is more likely than a cfg. This comes from my suspicion that few crates likely define custom --cfgs while I suspect cfg_alias has a good reason to be prevalent due to the ergonomics of our existing #[cfg] expressions. So if someone is trying to modify one of the few --cfgs it is more likely to affect an unintended cfg_alias than cfg.

I wonder how https://internals.rust-lang.org/t/pre-rfc-mutually-excusive-global-features/19618 might change things. Unfortunately, that is too undeveloped to really say.

However, if we supported shadowing (#3804 (comment)) instead of erroring, it would remove any concerns over RUSTFLAGS=--cfg=foo specifying foo on crates that don't expect it.

joshlf · 2025-05-02T16:20:28Z

text/3804-cfg-alias.md

+
+When defined at a module level, aliases are added to the configuration namespace
+for everything within that module including later module-level configuration.
+There is no conflict with aliases that use the same name in other modules.


What about shadowing? IMO it should be supported like we do for any other scoped variable:

#[cfg_alias(foo = bar)] mod a { // Enabled/disabled based on `cfg(bar)` #[cfg(foo)] fn qux() { /* ... */ } #[cfg_alias(foo = baz)] mod b { // Enabled/disabled based on `cfg(baz)` #[cfg(foo)] fn qux() { /* ... */ } } }

Introduce an RFC for config aliases

304fefc

tgross35 mentioned this pull request Apr 23, 2025

Remove unstable cfg target(...) compact feature rust-lang/rust#130780

Open

cfg-alias: Update with the PR number

780ccd7

tmandry reviewed Apr 23, 2025

View reviewed changes

programmerjake reviewed Apr 24, 2025

View reviewed changes

text/3804-cfg-alias.md Outdated Show resolved Hide resolved

programmerjake reviewed Apr 24, 2025

View reviewed changes

text/3804-cfg-alias.md Show resolved Hide resolved

Update syntax to =, add another usecase to motivation, mention --ch…

47d8ed1

…eck-cfg

tgross35 force-pushed the cfg-alias branch from c85f01e to 47d8ed1 Compare April 24, 2025 00:56

tmandry mentioned this pull request Apr 24, 2025

Tracking issue for cfg_match rust-lang/rust#115585

Open

3 tasks

Discuss optionally allowing cfg_alias at module scope

a164189

tgross35 force-pushed the cfg-alias branch from f9f9edf to a164189 Compare April 24, 2025 01:31

ehuss added the T-lang Relevant to the language team, which will review and decide on the RFC. label Apr 24, 2025

programmerjake reviewed Apr 24, 2025

View reviewed changes

traviscross reviewed Apr 24, 2025

View reviewed changes

traviscross added the I-lang-radar Items that are on lang's radar and will need eventual work or consideration. label Apr 24, 2025

ogoffart reviewed Apr 24, 2025

View reviewed changes

kennytm reviewed Apr 25, 2025

View reviewed changes

joshtriplett reviewed Apr 27, 2025

View reviewed changes

madsmtm reviewed May 2, 2025

View reviewed changes

epage reviewed May 2, 2025

View reviewed changes

joshlf reviewed May 2, 2025

View reviewed changes


		[RFC3697]: https://github.com/rust-lang/rfcs/pull/3697

		# Rationale and alternatives

		`predicate` can be anything that usually works within `#[cfg(...)]`, including
		`all`, `any`, and `not`.

		`cfg_alias` may also be used as a module-level attribute rather than
		crate-level:

		- It may be possible to have `#[cfg_alias(...)]` work as an outer macro and only
		apply to a specific scope. This likely is not worth the complexity.

		- Substitution vs. evaluation at define time (the question under the
		reference-level explanation)

	reuse in multiple crates.
	reuse in multiple crates.
	- We could add a visibility to the syntax, allowing a crate to export a cfg alias for use by other crates.

RFC: naming groups of configuration with cfg_alias #3804

Are you sure you want to change the base?

RFC: naming groups of configuration with cfg_alias #3804

Conversation

tgross35 commented Apr 23, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tmandry Apr 23, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tmandry Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mejrs Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oxalica commented Apr 24, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traviscross Apr 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

madsmtm May 2, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RFC: naming groups of configuration with `cfg_alias` #3804

RFC: naming groups of configuration with `cfg_alias` #3804

tgross35 commented Apr 23, 2025 •

edited

Loading

tmandry Apr 23, 2025 •

edited

Loading

tmandry Apr 24, 2025 •

edited

Loading

mejrs Apr 24, 2025 •

edited

Loading

traviscross Apr 28, 2025 •

edited

Loading

madsmtm May 2, 2025 •

edited

Loading