Document #[cfg(version(...))]

[est31]

Document #[cfg(version(...))] as it is to be stabilized.

Tracking issue: rust-lang/rust#64796
RFC: rust-lang/rfcs#2523
Stabilization PR: rust-lang/rust#141137
Earlier documentation PR filed for the first attempt: #981

[ehuss]

Can you make sure to not wrap lines when adding new content?

[ehuss]

It seems a little confusing to have both this and cfg.predicate.version. I'm wondering if it would make sense to extend the "option" grammar to include version(...), and just remove cfg.predicate.version? Then version() would just be another option shown in the list here.

And the section header should probably be third level, and match the style of the other options.

Suggested change

	r[cfg.version]
	## The `version()` predicate
	r[cfg.version]
	### `version()`

[ehuss]

Usually the reference focuses on the language and not specifics about the compiler or specific implementations. The text here seems a little confusing in that regard. I would probably just strike this content.

Suggested change

	of the language the compiler targets. Usually the compiler version and
	language version match. So compiler version `1.50.0` targets language
	`1.50.0`.
	of the language the compiler targets.

[madsmtm]

Though it might be beneficial to discuss a bit how this would work in alternative implementations like mrustc / gccrs? Though maybe "the language the compiler targets" is enough for that, unsure how I'd state it differently.

[ehuss]

Suggested change

	follow either the `"a.b.c"` scheme or the `"a.b"` scheme, where `a,b,c` are
	follow either the `"a.b.c"` scheme or the `"a.b"` scheme, where `a`, `b`, and `c` are

[madsmtm]

Question: Does this detail matter in the reference? Isn't it enough to say "these should be integers", and leave the range to the compiler implementation?

[ehuss]

@traviscross and I discussed this a little bit and felt like this probably should be specified? For example, if you say cfg(version("1.81.65535")), that will be true, but cfg(version("1.81.65536")) will be false. Since the magnitude of what gets parsed seems to matter, it might be good to be clear about that.

This is a bit extreme, though. Even if an implementation used u8, it's still 19 years before 1.256 (assuming we stick with 6 week releases), and seems silly for someone to put an unnecessarily large number there.

[est31]

hmm yeah good point. For future compatibility we will warn on unknown version literal formats, which includes 1.81.65536. We should probably word it in a way that the unknown formats are not guaranteed to evaluate to false.

[ehuss]

Shouldn't this be:

Suggested change

	`version` `(` `"` ConfigurationVersionLiteral `"` `)`
	`version` `(` ( STRING_LITERAL | RAW_STRING_LITERAL ) `)`

and assuming it is, I would just delete the other grammar productions and describe the format of the string in cfg.predicate.version in plain English. Or, we can keep ConfigurationVersionLiteral if you want, but the text will still need to be updated to say that the string needs to conform to the format described by ConfigurationVersionLiteral.

[est31]

yeah I think STRING_LITERAL | RAW_STRING_LITERAL is fine.

This works

#[cfg(version(r"1.0"))] fn foo() {}

foo();

note that syntactically, we don't require string literals here, i.e. this doesn't give an error:

#[cfg(any())]
#[cfg(version(hello(world)))] fn foo() {}

#[cfg(any())]
#[cfg(version(123))] fn foo() {}

probably the same for all cfg syntaxes.

[ehuss]

Can we merge cfg.version into this section so that it isn't described in two places?

[ehuss]

@traviscross and I discussed this a little bit and felt like this probably should be specified? For example, if you say cfg(version("1.81.65535")), that will be true, but cfg(version("1.81.65536")) will be false. Since the magnitude of what gets parsed seems to matter, it might be good to be clear about that.

This is a bit extreme, though. Even if an implementation used u8, it's still 19 years before 1.256 (assuming we stick with 6 week releases), and seems silly for someone to put an unnecessarily large number there.