Skip to content

Commit 98f1d03

Browse files
graydongraydon
committed
Address review comments on wasm32v1-none target
1 parent e47102f commit 98f1d03

File tree

6 files changed

+128
-52
lines changed

6 files changed

+128
-52
lines changed

‎compiler/rustc_target/src/spec/targets/wasm32v1_none.rs

+15-52
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,25 @@
1-
//! A "bare wasm" target representing a WebAssembly output that makes zero
2-
//! assumptions about its environment, similar to wasm32-unknown-unknown, but
3-
//! that also specifies an _upper_ bound on the set of wasm proposals that are
4-
//! supported.
5-
//!
6-
//! It is implemented as a variant on LLVM's wasm32-unknown-unknown target, with
7-
//! the additional flags `-Ctarget-cpu=mvp` and `-Ctarget-feature=+mutable-globals`.
8-
//!
9-
//! This target exists to resolve a tension in Rustc's choice of WebAssembly
10-
//! proposals to support. Since most WebAssembly users are in fact _on the web_
11-
//! and web browsers are frequently updated with support for the latest
12-
//! features, it is reasonable for Rustc to generate wasm code that exploits new
13-
//! WebAssembly proposals as they gain browser support. At least by default. And
14-
//! this is what the wasm32-unknown-unknown target does, which means that the
15-
//! _exact_ WebAssembly features that Rustc generates will change over time.
16-
//!
17-
//! But a different set of users -- smaller but nonetheless worth supporting --
18-
//! are using WebAssembly in implementations that either don't get updated very
19-
//! often, or need to prioritize stability, implementation simplicity or
20-
//! security over feature support. This target is for them, and it promises that
21-
//! the wasm code it generates will not go beyond the proposals/features of the
22-
//! W3C WebAssembly core 1.0 spec, which (as far as I can tell) is approximately
23-
//! "the wasm MVP plus mutable globals". Mutable globals was proposed in 2018
24-
//! and made it in.
25-
//!
26-
//! See https://www.w3.org/TR/wasm-core-1/
27-
//!
28-
//! Notably this feature-set _excludes_:
29-
//!
30-
//! - sign-extension operators
31-
//! - non-trapping / saturating float-to-int conversions
32-
//! - multi-value
33-
//! - reference types
34-
//! - bulk memory operations
35-
//! - SIMD
36-
//!
37-
//! These are all listed as additions in the core 2.0 spec. Also they were all
38-
//! proposed after 2020, and core 1.0 shipped in 2019. It also excludes even
39-
//! later proposals such as:
40-
//!
41-
//! - exception handling
42-
//! - tail calls
43-
//! - extended consts
44-
//! - function references
45-
//! - multi-memory
46-
//! - component model
47-
//! - gc
48-
//! - threads
49-
//! - relaxed SIMD
50-
//! - custom annotations
51-
//! - branch hinting
52-
//!
1+
//! A "bare wasm" target representing a WebAssembly output that does not import
2+
//! anything from its environment and also specifies an _upper_ bound on the set
3+
//! of WebAssembly proposals that are supported.
4+
//!
5+
//! It's equivalent to the `wasm32-unknown-unknown` target with the additional
6+
//! flags `-Ctarget-cpu=mvp` and `-Ctarget-feature=+mutable-globals`. This
7+
//! enables just the features specified in <https://www.w3.org/TR/wasm-core-1/>
8+
//!
9+
//! This is a _separate target_ because using `wasm32-unknown-unknown` with
10+
//! those target flags doesn't automatically rebuild libcore / liballoc with
11+
//! them, and in order to get those libraries rebuilt you need to use the
12+
//! nightly Rust feature `-Zbuild-std`. This target is for people who want to
13+
//! use stable Rust, and target a stable set pf WebAssembly features.
5314
5415
use crate::spec::{Cc, LinkerFlavor, Target, base};
5516

5617
pub(crate) fn target() -> Target {
5718
let mut options = base::wasm::options();
5819
options.os = "none".into();
5920

21+
// WebAssembly 1.0 shipped in 2019 and included exactly one proposal
22+
// after the initial "MVP" feature set: "mutable-globals".
6023
options.cpu = "mvp".into();
6124
options.features = "+mutable-globals".into();
6225

‎src/ci/docker/host-x86_64/dist-various-2/Dockerfile

+1
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,7 @@ ENV TARGETS=$TARGETS,wasm32-wasi
118118
ENV TARGETS=$TARGETS,wasm32-wasip1
119119
ENV TARGETS=$TARGETS,wasm32-wasip1-threads
120120
ENV TARGETS=$TARGETS,wasm32-wasip2
121+
ENV TARGETS=$TARGETS,wasm32v1-none
121122
ENV TARGETS=$TARGETS,sparcv9-sun-solaris
122123
ENV TARGETS=$TARGETS,x86_64-pc-solaris
123124
ENV TARGETS=$TARGETS,x86_64-unknown-linux-gnux32

‎src/doc/rustc/src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@
8686
- [wasm32-wasip2](platform-support/wasm32-wasip2.md)
8787
- [wasm32-unknown-emscripten](platform-support/wasm32-unknown-emscripten.md)
8888
- [wasm32-unknown-unknown](platform-support/wasm32-unknown-unknown.md)
89+
- [wasm32v1-none](platform-support/wasm32v1-none.md)
8990
- [wasm64-unknown-unknown](platform-support/wasm64-unknown-unknown.md)
9091
- [\*-win7-windows-msvc](platform-support/win7-windows-msvc.md)
9192
- [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)

‎src/doc/rustc/src/platform-support.md

+1
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@ target | std | notes
195195
`wasm32-wasi` | ✓ | WebAssembly with WASI (undergoing a [rename to `wasm32-wasip1`][wasi-rename])
196196
[`wasm32-wasip1`](platform-support/wasm32-wasip1.md) | ✓ | WebAssembly with WASI
197197
[`wasm32-wasip1-threads`](platform-support/wasm32-wasip1-threads.md) | ✓ | WebAssembly with WASI Preview 1 and threads
198+
[`wasm32v1-none`](platform-support/wasm32v1-none.md) | * | WebAssembly limited to 1.0 features and no imports
198199
[`x86_64-apple-ios`](platform-support/apple-ios.md) | ✓ | 64-bit x86 iOS
199200
[`x86_64-apple-ios-macabi`](platform-support/apple-ios-macabi.md) | ✓ | Mac Catalyst on x86_64
200201
[`x86_64-fortanix-unknown-sgx`](platform-support/x86_64-fortanix-unknown-sgx.md) | ✓ | [Fortanix ABI] for 64-bit Intel SGX

‎src/doc/rustc/src/platform-support/wasm32v1-none.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# `wasm32v1-none`
2+
3+
**Tier: 2**
4+
5+
The `wasm32v1-none` target is a WebAssembly compilation target that:
6+
7+
- Imports nothing from its host environment
8+
- Enables no proposals / features past the [W3C WebAssembly Core 1.0 spec]
9+
10+
[W3C WebAssembly Core 1.0 spec]: https://www.w3.org/TR/wasm-core-1/
11+
12+
The target is very similar to [`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md) and similarly uses LLVM's `wasm32-unknown-unknown` backend target. It contains only three minor differences:
13+
14+
* Setting the `target-cpu` to `mvp` rather than the default `generic`. Requesting `mvp` disables _all_ WebAssembly proposals / LLVM target feature flags.
15+
* Enabling the [Import/Export of Mutable Globals] proposal (i.e. the `+mutable-globals` LLVM target feature flag)
16+
* Not compiling the `std` library at all, rather than compiling it with stubs.
17+
18+
[Import/Export of Mutable Globals]: https://github.com/WebAssembly/mutable-global
19+
20+
## Target maintainers
21+
22+
- Alex Crichton, https://github.com/alexcrichton
23+
- Graydon Hoare, https://github.com/graydon
24+
25+
## Requirements
26+
27+
This target is cross-compiled. It does not support `std`, only `core` and `alloc`. Since it imports nothing from its environment, any `std` parts that use OS facilities would be stubbed out with functions-that-fail anyways, and the experience of working with the stub `std` in the `wasm32-unknown-unknown` target was deemed not something worth repeating here.
28+
29+
Everything else about this target's requirements, building, usage and testing is the same as what's described in the [`wasm32-unknown-unknown` document](./wasm32-unknown-unknown.md), just using the target string `wasm32v1-none` in place of `wasm32-unknown-unknown`.
30+
31+
## Conditionally compiling code
32+
33+
It's recommended to conditionally compile code for this target with:
34+
35+
```text
36+
#[cfg(all(target_family = "wasm", target_os = "none"))]
37+
```
38+
39+
Note that there is no way to tell via `#[cfg]` whether code will be running on
40+
the web or not.
41+
42+
## Enabled WebAssembly features
43+
44+
As noted above, _no WebAssembly proposals past 1.0_ are enabled on this target by default. Indeed, the entire point of this target is to have a way to compile for a stable "no post-1.0 proposals" subset of WebAssembly _on stable Rust_.
45+
46+
The [W3C WebAssembly Core 1.0 spec] was adopted as a W3C recommendation in December 2019, and includes exactly one "post-MVP" proposal: the [Import/Export of Mutable Globals] proposal.
47+
48+
All subsequent proposals are _disabled_ on this target by default, though they can be individually enabled by passing LLVM target-feature flags.
49+
50+
For reference sake, the set of proposals that LLVM supports at the time of writing, that this target _does not enable by default_, are listed here along with their LLVM target-feature flags:
51+
52+
* Post-1.0 proposals (integrated into the WebAssembly core 2.0 spec):
53+
* [Bulk memory] - `+bulk-memory`
54+
* [Sign-extending operations] - `+sign-ext`
55+
* [Non-trapping fp-to-int operations] - `+nontrapping-fptoint`
56+
* [Multi-value] - `+multivalue`
57+
* [Reference Types] - `+reference-types`
58+
* [Fixed-width SIMD] - `+simd128`
59+
* Post-2.0 proposals:
60+
* [Threads] (supported by atomics) - `+atomics`
61+
* [Exception handling] - `+exception-handling`
62+
* [Extended Constant Expressions] - `+extended-const`
63+
* [Half Precision] - `+half-precision`
64+
* [Multiple memories]- `+multimemory`
65+
* [Relaxed SIMD] - `+relaxed-simd`
66+
* [Tail call] - `+tail-call`
67+
68+
[Bulk memory]: https://github.com/WebAssembly/spec/blob/main/proposals/bulk-memory-operations/Overview.md
69+
[Sign-extending operations]: https://github.com/WebAssembly/spec/blob/main/proposals/sign-extension-ops/Overview.md
70+
[Non-trapping fp-to-int operations]: https://github.com/WebAssembly/spec/blob/main/proposals/nontrapping-float-to-int-conversion/Overview.md
71+
[Multi-value]: https://github.com/WebAssembly/spec/blob/main/proposals/multi-value/Overview.md
72+
[Reference Types]: https://github.com/WebAssembly/spec/blob/main/proposals/reference-types/Overview.md
73+
[Fixed-width SIMD]: https://github.com/WebAssembly/spec/blob/main/proposals/simd/SIMD.md
74+
[Threads]: https://github.com/webassembly/threads
75+
[Exception handling]: https://github.com/WebAssembly/exception-handling
76+
[Extended Constant Expressions]: https://github.com/WebAssembly/extended-const
77+
[Half Precision]: https://github.com/WebAssembly/half-precision
78+
[Multiple memories]: https://github.com/WebAssembly/multi-memory
79+
[Relaxed SIMD]: https://github.com/WebAssembly/relaxed-simd
80+
[Tail call]: https://github.com/WebAssembly/tail-call
81+
82+
Additional proposals in the future are, of course, also not enabled by default.
83+
84+
## Rationale relative to wasm32-unknown-unknown
85+
86+
As noted in the [`wasm32-unknown-unknown` document](./wasm32-unknown-unknown.md), it is possible to compile with `-target wasm32-unknown-unknown` and disable all WebAssembly proposals "by hand", by passing `-Ctarget-cpu=mvp`. Furthermore one can enable proposals one by one by passing LLVM target feature flags, such as `-Ctarget-feature=+mutable-globals`.
87+
88+
Is it therefore reasonable to wonder what the difference is between building with this:
89+
90+
```sh
91+
$ rustc -target wasm32-unknown-unknown -Ctarget-cpu=mvp -Ctarget-feature=+mutable-globals
92+
```
93+
94+
and building with this:
95+
96+
```sh
97+
$ rustc -target wasm32v1-none
98+
```
99+
100+
The difference is in how the `core` and `alloc` crates are compiled for distribution with the toolchain, and whether it works on _stable_ Rust toolchains or requires _nightly_ ones. Again referring back to the [`wasm32-unknown-unknown` document](./wasm32-unknown-unknown.md), note that to disable all post-MVP proposals on that target one _actually_ has to compile with this:
101+
102+
```sh
103+
$ export RUSTFLAGS="-Ctarget-cpu=mvp -Ctarget-feature=+mutable-globals"
104+
$ cargo +nightly build -Zbuild-std=panic_abort,std -target wasm32-unknown-unknown
105+
```
106+
107+
Which not only rebuilds `std`, `core` and `alloc` (which is somewhat costly and annoying) but more importantly requires the use of nightly Rust toolchains (for the `-Zbuild-std` flag). This is very undesirable for the target audience, which consists of people targeting WebAssembly implementations that prioritize stability, simplicity and/or security over feature support.
108+
109+
This `wasm32v1-none` target exists as an alternative option that works on stable Rust toolchains, without rebuilding the stdlib.

‎src/tools/build-manifest/src/main.rs

+1
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@ static TARGETS: &[&str] = &[
161161
"wasm32-wasip1",
162162
"wasm32-wasip1-threads",
163163
"wasm32-wasip2",
164+
"wasm32v1-none",
164165
"x86_64-apple-darwin",
165166
"x86_64-apple-ios",
166167
"x86_64-apple-ios-macabi",

0 commit comments

Comments
 (0)