Add new simpler and more explicit syntax for check-cfg

[Urgau]

Old proposition (before the MCP)

This PR adds a new simpler and more explicit syntax for check-cfg. It consist of two new form:

• exhaustive(names, values)
• configure(name, "value1", "value2", ... "valueN")

The preview forms names(...) and values(...) have implicit meaning that are not strait-forward. In particular values(foo)&values(bar) and names(foo, bar) are not equivalent which has created some confusions.

Also the names() and values() form are not clear either and again created some confusions where peoples believed that values()&values(foo) could be reduced to just values(foo).

To fix that the two new forms are made to be explicit and simpler. See the table of correspondence:

• names() -> exhaustive(names)
• values() -> exhaustive(values)
• names(foo) -> exhaustive(names)&configure(foo)
• values(foo) -> configure(foo)
• values(feat, "foo", "bar") -> configure(feat, "foo", "bar")
• values(foo)&values(bar) -> configure(foo, bar)
• names()&values()&values(my_cfg) -> exhaustive(names, values)&configure(my_cfg)

Another benefits of the new syntax is that it allow for further options (like conditional checking for --cfg, currently always on) without syntax change.

The two previous forms are deprecated and will be removed once cargo and beta rustc have the necessary support.

This PR is the first part of the implementation of MCP636 - Simplify and improve explicitness of the check-cfg syntax.

New cfg form

It introduces the new cfg form and deprecate the other two:

rustc --check-cfg 'cfg(name1, ..., nameN, values("value1", "value2", ... "valueN"))'

Default built-in names and values

It also changes the default for the built-in names and values checking.

• Built-in values checking would always be activated as long as a --check-cfg argument is present
• Built-in names checking would always be activated as long as a --check-cfg argument is present unless if any cfg(any()) arg is passed

Note: depends on #111068 but is reviewable (last two commits)!

Resolve rust-lang/compiler-team#636

r? @petrochenkov

[rustbot]

Error: Parsing relabel command in comment failed: ...'-on-author' | error: a label delta at >| ' (for the'...

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[petrochenkov]

Blocked on #111068.

[petrochenkov]

How can exhaustive(values) be a single flag?
Isn't value checking enabled and disabled per-name?
I.e. we can check values for name foo, and not check values for name bar.
Or does it only affect cfgs built into the compiler?

[petrochenkov]

Does --check-cfg exhaustive(names, values) basically mean --check-cfg builtin(names, values)?
What does --check-cfg exhaustive(values) mean without names?

UPD: Looks like --check-cfg exhaustive(values) does mean --check-cfg builtin(values), but --check-cfg exhaustive(names) does not.

[petrochenkov]

With this new design we cannot specify a name as known, while keeping its list of values unknown, right?

Previously names(foo) didn't restrict the set of values for foo, but exhaustive(names) & configure(foo) does restrict it to "no values".

[Urgau]

How can exhaustive(values) be a single flag? Isn't value checking enabled and disabled per-name? I.e. we can check values for name foo, and not check values for name bar. Or does it only affect cfgs built into the compiler?

exhaustive(values) works in the same way as values(), it adds (nearly) all the builtin cfgs with their expected values into the expected list. That means that all the builtin cfgs will lint if there is an unexpected value and that's it.
It doesn't change anything for non-builtin cfgs.

Remember that we can only lint on values for which we have an entry for, if we don't have one then it's not a value problem but a name problem and this is gated under exhaustive(names).

Does --check-cfg exhaustive(names, values) basically mean --check-cfg builtin(names, values)?

Not exactly, for values yes, it's an append of the builtin values. But for names it's not only appending the list of builtin names but also enabling the checking of all names; otherwise we wouldn't be able to check names since we would always trigger on builtin names.

What does --check-cfg exhaustive(values) mean without names?

Enable checking of the builtin values without triggering on potentially unexpected cfg.

[Urgau]

With this new design we cannot specify a name as known, while keeping its list of values unknown, right?

Yes, this is the only "regression" of the new design, but I've yet to found a example where this would be useful. The only place where it is useful is in the compiler for feature and target_feature where getting the expected values is non trivial.

If a consumer of rustc doesn't know the expected values of a config, how would a actual user know which one to use? Or even how does the consumer of rustc know which one to set via --cfg?

Previously names(foo) didn't restrict the set of values for foo, but exhaustive(names) & configure(foo) does restrict it to "no values".

Btw, no need for exhaustive(names) here, doing configure(foo) no matter if exhaustive(names) is set, set the expected values to none.

@rustbot ready

[petrochenkov]

So what we really need to cover all cases without regressions (without any syntax beautifications) is:

• --check-cfg builtin-values - will be commonly used if we expect full checking to be typically used.
• --check-cfg custom-values(noval, oneval, "val1", twovals, "val1", "val2") - will be commonly used if we expect full checking to be typically used.
• --check-cfg exhaustive-names(foo, bar) - doesn't put value restrictions on foo and bar, --check-cfg exhaustive-names() without arguments will be commonly used if we expect full checking to be typically used, the form with arguments - not so commonly.

[petrochenkov]

In that case we probably need some short syntax for the commonly used combination --check-cfg builtin-values --check-cfg exhaustive-names() --check-cfg custom-values(noval, oneval, "val1", twovals, "val1", "val2") + some additional rarely used options for opting out of exhaustiveness and adding names without value requirements.

[Urgau]

So what we really need to cover all cases without regressions (without any syntax beautifications) is:

• --check-cfg builtin-values - will be commonly used if we expect full checking to be typically used.

• --check-cfg custom-values(noval, oneval, "val1", twovals, "val1", "val2") - will be commonly used if we expect full checking to be typically used.

Agree for these two.

• --check-cfg exhaustive-names(foo, bar) - doesn't put value restrictions on foo and bar,

As I said, I don't think this is useful for users, as users knows all the possible values. Otherwise they couldn't possible use cfgs in any meaningful way.

--check-cfg exhaustive-names() without arguments will be commonly used if we expect full checking to be typically used, the form with arguments - not so commonly.

👍 (but note that there isn't currently any plan to enable this by default in cargo)

In that case we probably need some short syntax for the commonly used combination --check-cfg builtin-values --check-cfg exhaustive-names() --check-cfg custom-values(noval, oneval, "val1", twovals, "val1", "val2") + some additional rarely used options for opting out of exhaustiveness and adding names without value requirements.

If cargo were to enable all things, it would be with my syntax exhaustive(names, values)&configure(feature, ...) set by cargo + users defined (but cannot really do anything about them).

[petrochenkov]

@bors r+

[bors]

📌 Commit fc78d78 has been approved by petrochenkov

It is now in the queue for this repository.

[WaffleLapkin]

@Urgau is the syntax in the OP still up to date? (I don't immediately get what the syntax means, specifically the values(...) so I'm asking to make sure) And is this feature gated? Or is it insta-stable?

[Urgau]

Urgau is the syntax in the OP still up to date? (I don't immediately get what the syntax means, specifically the values(...) so I'm asking to make sure)

Yes, the PR description, the commit message and the MCP are all up to date.
Regarding values(...) (I assume you mean in cfg(...) and not the old syntax), it's a designator to separate the names previously given and the values associated with them. In other words, it's like a key=value pair, where both the names (key) and the values are de-duplicated.

For more information, I would highly suggest reading the check-cfg section of the rustc unstable book.

And is this feature gated? Or is it insta-stable?

It's a pre-existing unstable feature, so yes it's gated.

[WaffleLapkin]

(Sorry for commenting on details after MCP was accepted and PR approved...) For me it looks weird that values() is it's own thing. From the syntax it looks like an element just like feature names, not a thing on a different level. I'd expect something more like name = ["value", "value2"] or name("value", "value2"), rather than name, values("value", value2), again, because name and values here don't live on the same level, they are not elements of the same list.

Also the documentation seems to have a configure in an example, which looks like a mistake?

Anyway, thanks for answering my questions.

[Urgau]

values(...) being it's "own" thing is on purpose, cf. https://hackmd.io/@wesleywiser/rJlumbfep:

2. I think we should specifically denote the values. Perhaps cfg(feature, values(foo, bar)). No values would be spelled cfg(feature) or cfg(feature, values()). This makes it easer to extend the constraints we can express in the future (for example cfg(target_pointer_width, one_of(16, 32, 64))).

btw, if you wish to continue discussing it let's do that on Zulip

---

Also the documentation seems to have a configure in an example, which looks like a mistake?

Yes, missed-it.