@@ -40,9 +40,18 @@ If you are only targeting the web and need to access web APIs, the
4040## Requirements
4141
4242This target is cross-compiled. The Emscripten compiler toolchain (emsdk) must be
43- installed to link Rust-compiled code with Emscripten's libc and other C/C++
44- code. Please refer to < https://emscripten.org/docs/getting_started/downloads.html >
45- on how to get started with the emsdk.
43+ installed to link WASM binaries with ` emcc ` . Please refer to
44+ < https://emscripten.org/docs/getting_started/downloads.html > on how to get started
45+ with the emsdk.
46+
47+ You can also build the emsdk from source with:
48+
49+ ``` sh
50+ git clone https://github.com/emscripten-core/emsdk.git --depth 1
51+ ./emsdk/emsdk install 3.1.68
52+ ./emsdk/emsdk activate 3.1.68
53+ source ./emsdk/emsdk_env.sh
54+ ```
4655
4756## Building the target
4857
@@ -85,21 +94,38 @@ undefined behaviour. If you come across issues, you can rebuild the Rust standar
8594library with your local Emscripten version using
8695
8796``` sh
88- $ cargo +nightly -Zbuild-std build
97+ cargo +nightly -Zbuild-std build
8998```
9099
91100## Testing
92101
93- This target is not extensively tested in CI for the rust-lang/rust repository.
94- It's recommended to test the [ ` wasm32-wasip1 ` ] ( ./wasm32-wasip1.md ) target instead
95- for WebAssembly compatibility.
102+ This target is not extensively tested in CI for the rust-lang/rust repository. It
103+ can be tested locally, for example, with:
104+
105+ ``` sh
106+ ./x.py test --target wasm32-unknown-emscripten --skip src/tools/linkchecker
107+ ```
108+
109+ To run these tests, both ` emcc ` and ` node ` need to be in your ` $PATH ` . You can
110+ install ` node ` , for example, using ` nvm ` by following the instructions at
111+ < https://github.com/nvm-sh/nvm#install--update-script > .
112+
113+ Still, it's recommended to test the [ ` wasm32-wasip1 ` ] ( ./wasm32-wasip1.md ) target
114+ instead for WebAssembly compatibility.
96115
97116## Conditionally compiling code
98117
99118It's recommended to conditionally compile code for this target with:
100119
101120``` text
102- #[cfg(all(target_family = "wasm", target_os = "emscripten"))]
121+ #[cfg(target_os = "emscripten")]
122+ ```
123+
124+ It may sometimes be necessary to conditionally compile code for WASM targets
125+ which do * not* use emscripten, which can be achieved with:
126+
127+ ``` text
128+ #[cfg(all(target_family = "wasm", not(target_os = "emscripten)))]
103129```
104130
105131## Enabled WebAssembly features
@@ -108,7 +134,8 @@ WebAssembly is an evolving standard which adds new features such as new
108134instructions over time. This target's default set of supported WebAssembly
109135features will additionally change over time. The ` wasm32-unknown-emscripten ` target
110136inherits the default settings of LLVM which typically, but not necessarily, matches
111- the default settings of Emscripten as well.
137+ the default settings of Emscripten as well. At link time, ` emcc ` configures the
138+ linker to use Emscripten's settings.
112139
113140Please refer to the [ ` wasm32-unknown-unknown ` ] ( ./wasm32-unknown-unknown.md )
114141target's documentation on which WebAssembly features Rust enables by default, how
0 commit comments