Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add target documentation for wasm64-unknown-unknown
- Loading branch information
1 parent
e4b3496
commit 9d6f7f7
Showing
1 changed file
with
101 additions
and
0 deletions.
There are no files selected for viewing
101 changes: 101 additions & 0 deletions
101
src/doc/rustc/src/platform-support/wasm64-unknown-unknown.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,101 @@ | ||
# `wasm64-unknown-unknown` | ||
|
||
**Tier: 3** | ||
|
||
WebAssembly target which uses 64-bit memories, relying on the [memory64] | ||
WebAssembly proposal. | ||
|
||
[memory64]: https://github.com/webassembly/memory64 | ||
|
||
## Target maintainers | ||
|
||
- Alex Crichton, https://github.com/alexcrichton | ||
|
||
## Requirements | ||
|
||
This target is cross-compiled. The target supports `std` in the same manner as | ||
the `wasm32-unknown-unknown` target which is to say that it comes with the | ||
standard library but many I/O functions such as `std::fs` and `std::net` will | ||
simply return error. Additionally I/O operations like `println!` don't actually | ||
do anything and the prints aren't routed anywhere. This is the same as the | ||
`wasm32-unknown-unknown` target. This target comes by default with an allocator, | ||
currently [dlmalloc] which is [ported to rust][dlmalloc-rs]. | ||
|
||
[dlmalloc]: http://gee.cs.oswego.edu/dl/html/malloc.html | ||
[dlmalloc-rs]: https://github.com/alexcrichton/dlmalloc-rs | ||
|
||
The difference of this target with `wasm32-unknown-unknown` is that it's | ||
compiled for 64-bit memories instead of 32-bit memories. This means that `usize` | ||
is 8-bytes large as well as pointers. The tradeoff, though, is that the maximum | ||
memory size is now the full 64-bit address space instead of the 4GB as limited | ||
by the 32-bit address space for `wasm32-unknown-unknown`. | ||
|
||
This target is not a stable target. The [memory64] WebAssembly proposal is stil | ||
in-progress and not standardized. This means that there are not many engines | ||
which implement the `memory64` feature and if they do they're likely behind a | ||
flag, for example: | ||
|
||
* Nodejs - `--experimental-wasm-memory64` | ||
* Wasmtime - `--wasm-features memory64` | ||
|
||
Also note that at this time the `wasm64-unknown-unknown` target assumes the | ||
presence of other merged wasm proposals such as (with their LLVM feature flags): | ||
|
||
* [Bulk memory] - `+bulk-memory` | ||
* Mutable imported globals - `+mutable-globals` | ||
* [Sign-extending operations] - `+sign-ext` | ||
* [Non-trapping fp-to-int operations] - `+nontrapping-fptoint` | ||
|
||
[Bulk memory]: https://github.com/WebAssembly/spec/blob/main/proposals/bulk-memory-operations/Overview.md | ||
[Sign-extending operations]: https://github.com/WebAssembly/spec/blob/main/proposals/sign-extension-ops/Overview.md | ||
[Non-trapping fp-to-int operations]: https://github.com/WebAssembly/spec/blob/main/proposals/nontrapping-float-to-int-conversion/Overview.md | ||
|
||
The `wasm64-unknown-unknown` target intends to match the default Clang targets | ||
for its `"C"` ABI, which is likely to be the same as Clang's | ||
`wasm32-unknown-unknown` largely. | ||
|
||
> **Note**: due to the relatively early-days nature of this target when working | ||
> with this target you may encounter LLVM bugs. If an assertion hit or a bug is | ||
> found it's recommended to open an issue either with rust-lang/rust or ideally | ||
> with LLVM itself. | ||
This target does not support `panic=unwind` at this time. | ||
|
||
## Building the target | ||
|
||
You can build Rust with support for the target by adding it to the `target` | ||
list in `config.toml`, and the target also requires `lld` to be built to work. | ||
|
||
```toml | ||
[build] | ||
target = ["wasm64-unknown-unknown"] | ||
|
||
[rust] | ||
lld = true | ||
``` | ||
|
||
## Building Rust programs | ||
|
||
Rust does not yet ship pre-compiled artifacts for this target. To compile for | ||
this target, you will either need to build Rust with the target enabled (see | ||
"Building the target" above), or build your own copy of `std` by using | ||
`build-std` or similar. | ||
|
||
Note that the following `cfg` directives are set for `wasm64-unknown-unknown`: | ||
|
||
* `cfg(target_arch = "wasm64")` | ||
* `cfg(target_family = "wasm")` | ||
|
||
## Testing | ||
|
||
Currently testing is not well supported for `wasm64-unknown-unknown` and the | ||
Rust project doesn't run any tests for this target. Testing support sort of | ||
works but without `println!` it's not the most exciting tests to run. | ||
|
||
## Cross-compilation toolchains and C code | ||
|
||
Compiling Rust code with C code for `wasm64-unknown-unknown` is theoretically | ||
possible, but there are no known toolchains to do this at this time. At the time | ||
of this writing there is no known "libc" for wasm that works with | ||
`wasm64-unknown-unknown`, which means that mixing C & Rust with this target | ||
effectively cannot be done. |