Skip to content

Commit

Permalink
Clarify ABI incompatibility flags
Browse files Browse the repository at this point in the history
  • Loading branch information
juntyr authored Oct 15, 2024
1 parent 2fa03a1 commit fef9b29
Showing 1 changed file with 17 additions and 6 deletions.
23 changes: 17 additions & 6 deletions src/doc/rustc/src/platform-support/wasm32-unknown-emscripten.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,17 +96,23 @@ 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
that clearly indicates when breaking changes to the ABI can be made. Additionally,
Emscripten offers many different ABIs even for a single version of Emscripten
depending on the linker flags used, e.g. `-fexceptions` and `-sWASM_BIGINT`. If
the ABIs mismatch, your code may exhibit undefined behaviour.

To ensure that the ABIs of your Rust code, of the Rust standard library, and of
other code compiled for Emscripten all match, you should rebuild the Rust standard
library with your local Emscripten version and settings using:

```sh
cargo +nightly -Zbuild-std build
```

If you still want to use the pre-compiled `std` from rustup, you should ensure
that your local Emscripten matches the version used by Rust and be careful about
any `-C link-arg`s that you compiled your Rust code with.

## Testing

This target is not extensively tested in CI for the rust-lang/rust repository. It
Expand Down Expand Up @@ -156,3 +162,8 @@ Note that Rust code compiled for `wasm32-unknown-emscripten` currently enables
`-fexceptions` (JS exceptions) by default unless the Rust code is compiled with
`-Cpanic=abort`. `-fwasm-exceptions` (WASM exceptions) is not yet currently supported,
see <https://github.com/rust-lang/rust/issues/112195>.

Please refer to the [Emscripten ABI compatibility](#emscripten-abi-compatibility)
section to ensure that the features that are enabled do not cause an ABI mismatch
between your Rust code, the pre-compiled Rust standard library, and other code compiled
for Emscripten.

0 comments on commit fef9b29

Please sign in to comment.