Create wasm32-unknown-emscripten.md

Author: juntyr

src/doc/rustc/src/platform-support/wasm32-unknown-emscripten.md

@@ -0,0 +1,98 @@
+# `wasm32-unknown-emscipten`
+
+**Tier: 2**
+
+The `wasm32-unknown-emscripten` target is a WebAssembly compilation target which
+uses the Emscripten compiler toolchain. Unlike the
+[`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md) target, which only has
+partial support for the Rust standard library, `wasm32-unknown-emscripten`
+integrates with JavaScipt on the web to provide a more featureful standard library.
+This target is often used when compiling for the web, accessing web APIs, or
+interoperating with C and C++ code.
+
+One existing user of this target (please feel free to edit and expand this list
+too) is the [`pyodide` project](https://github.com/pyodide/pyodide) which provides
+a Python runtime in WebAssembly using Emscripten and compiles Python extension
+modules written in Rust to the `wasm32-unknown-emscripten` target.
+
+## Target maintainers
+
+When this target was added to the compiler, platform-specific documentation here
+was not maintained at that time. This means that the list below is not
+exhaustive, and there are more interested parties in this target. That being
+said, those interested in maintaining this target are:
+
+- TODO
+
+## Requirements
+
+This target is cross-compiled. The Emscripten compiler toolchain must be
+installed to link Rust-compiled code with Emscripten's libc and other C/C++
+code.
+
+## Building the target
+
+Building this target can be done by:
+
+* Configure the `wasm32-unknown-emscripten` target to get built.
+* Configure LLD to be built.
+* Ensure the `WebAssembly` target backend is not disabled in LLVM.
+
+These are all controlled through `config.toml` options. It should be possible
+to build this target on any platform.
+
+## Building Rust programs
+
+Rust programs can be compiled by adding this target via rustup:
+
+```sh
+$ rustup target add wasm32-unknown-emscripten
+```
+
+and then compiling with the target:
+
+```sh
+$ rustc foo.rs --target wasm32-unknown-emscripten
+$ file foo.wasm
+```
+
+## Cross-compilation
+
+This target can be cross-compiled from any host.
+
+## Emscripten ABI Compatibility
+
+The Emscripten compiler toolchain does not follow a semantic versioning scheme
+that clearly indicates when breaking changes to the ABI can be made. If you are
+using the pre-compiled `std` from rustup, it may be compiled with a different
+Emscripten version than the local Emscripten you have installed. If a breaking
+change to the ABI was made in between the two versions, your code will exhibit
+undefined behaviour. If you come across issues, you can rebuild the Rust standard
+library with your local Emscripten version using
+
+```sh
+$ cargo +nightly -Zbuild-std build
+```
+
+## Testing
+
+This target is not extensively tested in CI for the rust-lang/rust repository.
+It's recommended to test the `wasm32-wasip1` target instead for WebAssembly
+compatibility.
+
+## Conditionally compiling code
+
+It's recommended to conditionally compile code for this target with:
+
+```text
+#[cfg(all(target_family = "wasm", target_os = "emscripten"))]
+```
+
+Note that there is no way to tell via `#[cfg]` whether code will be running on
+the web or not.
+
+## Enabled WebAssembly features
+
+WebAssembly is an evolving standard which adds new features such as new
+instructions over time. The `wasm32-unknown-emscripten` target inherits the
+default settings of Emscripten.