|
| 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. |
0 commit comments