Document WebAssembly target feature expectations

[alexcrichton]

This commit is a result of the discussion on #128475 and incorporates parts of #109807 as well. This is all done as a new page of documentation for the wasm32-unknown-unknown target which previously did not exist. This new page goes into details about the preexisting target and additionally documents the expectations for WebAssembly features and code generation.

The tl;dr is that LLVM will enable features over time after most engines have had support for awhile. Compiling without features requires -Ctarget-cpu=mvp to rustc plus -Zbuild-std to Cargo.

Closes #109807
Closes #119811
Closes #128475

EDIT: for the relnotes label please see this comment for recommended release notes.

[rustbot]

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

Some changes occurred in src/doc/rustc/src/platform-support

cc @Noratrieb

[alexcrichton]

If this is accepted then I will additionally comment on #127513 with a recommended rewording of the release notes to indicate that this does affect WebAssembly binaries.

[bb010g]

A wording nit & spelling nits.

[workingjubilee]

@alexcrichton Is it possible to get an rmake test for the workarounds here, or landing a test in rust-lang/cargo?

[alexcrichton]

I was looking into that yeah and was hoping I could combine -Clto somehow to get a test in-tree, but the conclusion ended up being that it didn't have the right behavior of rewriting target features per function that I thought was happening. That means that such a test requires -Zbuild-std which while there is one test in tree that does this that test looks relatively complicated and specialized so I was wary to try to copy it.

I can look into adding a test in Cargo, yeah, but it feels like an odd location for such a test given that the regressions, if any, would likely come from this repo instead of Cargo. One option would be to refactor the existing Zbuild-std test in this repo, but I'm also not sure if folks are keen on expanding that due to the amount of time such a test would take compiling the standard library.

[jieyouxu]

I was looking into that yeah and was hoping I could combine -Clto somehow to get a test in-tree, but the conclusion ended up being that it didn't have the right behavior of rewriting target features per function that I thought was happening. That means that such a test requires -Zbuild-std which while there is one test in tree that does this that test looks relatively complicated and specialized so I was wary to try to copy it.

Yeah, unfortunately the compiler-builtins test takes a really long time to build the stdlib again, since it relies on very specific configurations. I don't have a good solution for this either, if it requires building yet another customized version of std.

[alexcrichton]

ping @GuillaumeGomez would you be able to review this? Or should I try to get a different sign-off?

[GuillaumeGomez]

I'm often assigned for such PRs but I have nothing to do with this part. Please pick someone else. ^^'

[danielhjacobs]

Is the minimum supported Safari version for this target version 15: https://caniuse.com/wasm-reference-types?

Plus minimum supported Chrome/Edge version 96,

[danielhjacobs]

I really just wish Rust hadn't enabled extra target features by default when it's so easy to enable extra target features and so hard to disable them. Why can't that be down to the crates to enable?

[daxpedda]

Just for clarification: Rust didn't enable those features by default, LLVM did.
But please see this blog post for full context.

[workingjubilee]

Please open a new issue or a discussion on Zulip if you wish to continue this.