src/doc/rustc/src/platform-support/wasm64-unknown-unknown.md

   1 # `wasm64-unknown-unknown`
   2
   3 **Tier: 3**
   4
   5 WebAssembly target which uses 64-bit memories, relying on the [memory64]
   6 WebAssembly proposal.
   7
   8 [memory64]: https://github.com/webassembly/memory64
   9
  10 ## Target maintainers
  11
  12 - Alex Crichton, https://github.com/alexcrichton
  13
  14 ## Requirements
  15
  16 This target is cross-compiled. The target supports `std` in the same manner as
  17 the `wasm32-unknown-unknown` target which is to say that it comes with the
  18 standard library but many I/O functions such as `std::fs` and `std::net` will
  19 simply return error. Additionally I/O operations like `println!` don't actually
  20 do anything and the prints aren't routed anywhere. This is the same as the
  21 `wasm32-unknown-unknown` target. This target comes by default with an allocator,
  22 currently [dlmalloc] which is [ported to rust][dlmalloc-rs].
  23
  24 [dlmalloc]: http://gee.cs.oswego.edu/dl/html/malloc.html
  25 [dlmalloc-rs]: https://github.com/alexcrichton/dlmalloc-rs
  26
  27 The difference of this target with `wasm32-unknown-unknown` is that it's
  28 compiled for 64-bit memories instead of 32-bit memories. This means that `usize`
  29 is 8-bytes large as well as pointers. The tradeoff, though, is that the maximum
  30 memory size is now the full 64-bit address space instead of the 4GB as limited
  31 by the 32-bit address space for `wasm32-unknown-unknown`.
  32
  33 This target is not a stable target. The [memory64] WebAssembly proposal is still
  34 in-progress and not standardized. This means that there are not many engines
  35 which implement the `memory64` feature and if they do they're likely behind a
  36 flag, for example:
  37
  38 * Nodejs - `--experimental-wasm-memory64`
  39 * Wasmtime - `--wasm-features memory64`
  40
  41 Also note that at this time the `wasm64-unknown-unknown` target assumes the
  42 presence of other merged wasm proposals such as (with their LLVM feature flags):
  43
  44 * [Bulk memory] - `+bulk-memory`
  45 * Mutable imported globals - `+mutable-globals`
  46 * [Sign-extending operations] - `+sign-ext`
  47 * [Non-trapping fp-to-int operations] - `+nontrapping-fptoint`
  48
  49 [Bulk memory]: https://github.com/WebAssembly/spec/blob/main/proposals/bulk-memory-operations/Overview.md
  50 [Sign-extending operations]: https://github.com/WebAssembly/spec/blob/main/proposals/sign-extension-ops/Overview.md
  51 [Non-trapping fp-to-int operations]: https://github.com/WebAssembly/spec/blob/main/proposals/nontrapping-float-to-int-conversion/Overview.md
  52
  53 The `wasm64-unknown-unknown` target intends to match the default Clang targets
  54 for its `"C"` ABI, which is likely to be the same as Clang's
  55 `wasm32-unknown-unknown` largely.
  56
  57 > **Note**: due to the relatively early-days nature of this target when working
  58 > with this target you may encounter LLVM bugs. If an assertion hit or a bug is
  59 > found it's recommended to open an issue either with rust-lang/rust or ideally
  60 > with LLVM itself.
  61
  62 This target does not support `panic=unwind` at this time.
  63
  64 ## Building the target
  65
  66 You can build Rust with support for the target by adding it to the `target`
  67 list in `config.toml`, and the target also requires `lld` to be built to work.
  68
  69 ```toml
  70 [build]
  71 target = ["wasm64-unknown-unknown"]
  72
  73 [rust]
  74 lld = true
  75 ```
  76
  77 ## Building Rust programs
  78
  79 Rust does not yet ship pre-compiled artifacts for this target. To compile for
  80 this target, you will either need to build Rust with the target enabled (see
  81 "Building the target" above), or build your own copy of `std` by using
  82 `build-std` or similar.
  83
  84 Note that the following `cfg` directives are set for `wasm64-unknown-unknown`:
  85
  86 * `cfg(target_arch = "wasm64")`
  87 * `cfg(target_family = "wasm")`
  88
  89 ## Testing
  90
  91 Currently testing is not well supported for `wasm64-unknown-unknown` and the
  92 Rust project doesn't run any tests for this target. Testing support sort of
  93 works but without `println!` it's not the most exciting tests to run.
  94
  95 ## Cross-compilation toolchains and C code
  96
  97 Compiling Rust code with C code for `wasm64-unknown-unknown` is theoretically
  98 possible, but there are no known toolchains to do this at this time. At the time
  99 of this writing there is no known "libc" for wasm that works with
 100 `wasm64-unknown-unknown`, which means that mixing C & Rust with this target
 101 effectively cannot be done.