Codegen metadata documentation is not exhaustive

[alepez]

Location

https://doc.rust-lang.org/rustc/codegen-options/index.html#metadata

Summary

Current rustc -Cmetadata argument documentation:

This option allows you to control the metadata used for symbol mangling. This takes a space-separated list of strings. Mangled symbols will incorporate a hash of the metadata. This may be used, for example, to differentiate symbols between two different versions of the same crate being linked.

I feel it is not evident what is the expected behavior. I'm not talking about how the metadata is used to differentiate symbols, but what are the expected arguments.

Other non-documented rules, which are clear by looking at the code in charge
of generating a stable crate id (compiler/rustc_span/src/def_id.rs)

Metadata is a list of values. The order of such values does not matter.
So one two and two one are equivalent

Metadata values can be added with a single -Cmetadata option, which takes
a value of space-separated values.

Metadata values can also be added by multiple -Cmetadata options.

Every distinct -C metadata value is only incorporated once

A single metadata "ab" has a different meaning than two separated "a" "b"

So these are equivalent:

-Cmetadata=one -Cmetadata=two
-Cmetadata="one two"
-Cmetadata="two one"
-Cmetadata="one two one"

But these are not:

-Cmetadata="onetwo"
-Cmetadata="one,two"