More review comments on wasm32v1-none target · rust-lang/rust@b0f0282 (original) (raw)

2 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -132,10 +132,20 @@ As of the time of this writing the proposals that are enabled by default (the
132 132
133 133 If you're compiling WebAssembly code for an engine that does not support a
134 134 feature in LLVM's default feature set then the feature must be disabled at
135 -compile time. Note, though, that enabled features may be used in the standard
136 -library or precompiled libraries shipped via rustup. This means that not only
137 -does your own code need to be compiled with the correct set of flags but the
138 -Rust standard library additionally must be recompiled.
135 +compile time. There are two approaches to choose from:
136 +
137 +- If you are targeting a feature set no smaller than the W3C WebAssembly Core
138 + 1.0 recommendation -- which is equivalent to the WebAssembly MVP plus the
139 +`mutable-globals` feature -- and you are building `no_std`, then you can
140 + simply use the [`wasm32v1-none` target](./wasm32v1-none.md) instead of
141 +`wasm32-unknown-unknown`, which uses only those minimal features and
142 + includes a core and alloc library built with only those minimal features.
143 +
144 +- Otherwise -- if you need std, or if you need to target the ultra-minimal
145 + "MVP" feature set, excluding `mutable-globals` -- you will need to manually
146 + specify `-Ctarget-cpu=mvp` and also rebuild the stdlib using that target to
147 + ensure no features are used in the stdlib. This in turn requires use of a
148 + nightly compiler.
139 149
140 150 Compiling all code for the initial release of WebAssembly looks like:
141 151
@@ -150,9 +160,9 @@ then used to recompile the standard library in addition to your own code. This
150 160 will produce a binary that uses only the original WebAssembly features by
151 161 default and no proposals since its inception.
152 162
153 -To enable individual features it can be done with `-Ctarget-feature=+foo`.
154 -Available features for Rust code itself are documented in the [reference] and
155 -can also be found through:
163 +To enable individual features on either this target or `wasm32v1-none`, pass
164 +arguments of the form `-Ctarget-feature=+foo`. Available features for Rust code
165 +itself are documented in the [reference] and can also be found through:
156 166
157 167 ```sh
158 168 $ rustc -Ctarget-feature=help --target wasm32-unknown-unknown
Original file line number Diff line number Diff line change
@@ -83,25 +83,25 @@ Additional proposals in the future are, of course, also not enabled by default.
83 83
84 84 ## Rationale relative to wasm32-unknown-unknown
85 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`.
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 87
88 88 Is it therefore reasonable to wonder what the difference is between building with this:
89 89
90 90 ```sh
91 -$ rustc -target wasm32-unknown-unknown -Ctarget-cpu=mvp -Ctarget-feature=+mutable-globals
91 +$ rustc --target wasm32-unknown-unknown -Ctarget-cpu=mvp -Ctarget-feature=+mutable-globals
92 92 ```
93 93
94 94 and building with this:
95 95
96 96 ```sh
97 -$ rustc -target wasm32v1-none
97 +$ rustc --target wasm32v1-none
98 98 ```
99 99
100 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 101
102 102 ```sh
103 103 $ export RUSTFLAGS="-Ctarget-cpu=mvp -Ctarget-feature=+mutable-globals"
104 -$ cargo +nightly build -Zbuild-std=panic_abort,std -target wasm32-unknown-unknown
104 +$ cargo +nightly build -Zbuild-std=panic_abort,std --target wasm32-unknown-unknown
105 105 ```
106 106
107 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.