1# Platform Support 2 3This page is intended to give a high-level overview of Wasmtime's platform 4support along with some aspirations of Wasmtime. For more details see the 5documentation on [tiers of stability](./stability-tiers.md) which has specific 6information about what's supported in Wasmtime on a per-matrix-combination 7basis. 8 9Wasmtime strives to support hardware that anyone wants to run WebAssembly on. 10Wasmtime is intended to work out-of-the-box on most platforms by having 11platform-specific defaults for the runtime. For example the native Cranelift 12backend is enabled by default if supported, but otherwise the Pulley 13interpreter backend is used if it's not supported. 14 15## Compiler Support 16 17Cranelift supports x86\_64, aarch64, s390x, and riscv64. No 32-bit platform is 18currently supported. Building a new backend for Cranelift is a relatively large 19undertaking which maintainers are willing to help with but it's recommended to 20reach out to Cranelift maintainers first to discuss this. 21 22Winch supports x86\_64. The aarch64 backend is in development. Winch is built on 23Cranelift's support for emitting instructions so Winch's possible backend list 24is currently limited to what Cranelift supports. 25 26Usage of the Cranelift or Winch requires a host operating system which supports 27creating executable memory pages on-the-fly. Support for statically linking in a 28single precompiled module is not supported at this time. 29 30Both Cranelift and Winch can be used either in AOT or JIT mode. In AOT mode one 31process precompiles a module/component and then loads it into another process. 32In JIT mode this is all done within the same process. 33 34Neither Cranelift nor Winch support tiering at this time in the sense of having 35a WebAssembly module start from a Winch compilation and automatically switch to 36a Cranelift compilation. Modules are either entirely compiled with Winch or 37Cranelift. 38 39## Interpreter support 40 41The `wasmtime` crate provides an implementation of a [WebAssembly interpreter 42named "Pulley"](./examples-pulley.md) which is a portable implementation of 43executing WebAssembly code. Pulley uses a custom bytecode which is created from 44input WebAssembly similarly to how native architectures are supported. Pulley's 45bytecode is created via a Cranelift backend for Pulley, so compile times for 46the interpreter are expected to be similar to natively compiled code. 47 48The main advantage of Pulley is that the bytecode can be executed on any 49platform with the same pointer-width and endianness. For example to execute 50Pulley on a 32-bit ARM platform you'd use the target `pulley32`. Similarly if 51you wanted to run Pulley on x86\_64 you'd use the target `pulley64` for 52Wasmtime. 53 54Pulley's platform requirements are no greater than that of Wasmtime itself, 55meaning that the goal is that if you can compile Wasmtime for a Rust target then 56Pulley can run on that target. 57 58Finally, note that while Pulley is optimized to be an efficient interpreter it 59will never be as fast as native Cranelift backends. A performance penalty should 60be expected when using Pulley. 61 62## OS Support 63 64Wasmtime with Pulley should work out-of-the-box on any Rust target, but for 65optimal runtime performance of WebAssembly OS integration is required. In the 66same way that Pulley is slower than a native Cranelift backend Wasmtime will be 67slower on Rust targets it has no OS support for. Wasmtime will for example use 68virtual memory when possible to implement WebAssembly linear memories to 69efficiently allocate/grow/deallocate. 70 71OS support at this time primarily includes Windows, macOS, and Linux. Other 72OSes such as iOS, Android, and Illumos are supported but less well tested. 73PRs to the Wasmtime repository are welcome for new OSes for better native 74platform support of a runtime environment. 75 76## Support for `#![no_std]` 77 78The `wasmtime` crate supports being build on no\_std platforms in Rust, but 79only for a subset of its compile-time Cargo features. Currently supported 80Cargo features are: 81 82* `runtime` 83* `gc` 84* `component-model` 85* `pulley` 86* `async` 87* `debug` 88* `debug-builtins` 89* `demangle` 90* `anyhow` 91 92This notably does not include the `default` feature which means that when 93depending on Wasmtime you'll need to specify `default-features = false`. This 94also notably does not include Cranelift or Winch at this time meaning that 95no\_std platforms must be used in AOT mode where the module is precompiled 96elsewhere. 97 98Wasmtime's support for no\_std requires the embedder to implement the equivalent 99of a C header file to indicate how to perform basic OS operations such as 100allocating virtual memory. This API can be found as `wasmtime-platform.h` in 101Wasmtime's release artifacts or at 102`examples/min-platform/embedding/wasmtime-platform.h` in the source tree. Note 103that this API is not guaranteed to be stable at this time, it'll need to be 104updated when Wasmtime is updated. 105 106Wasmtime's runtime will use the symbols defined in this file meaning that if 107they're not defined then a link-time error will be generated. Embedders are 108required to implement these functions in accordance with their documentation to 109enable Wasmtime to run on custom platforms. 110 111Note that many functions in this header file are gated behind off-by-default 112`#ifdef` directives indicating that Wasmtime doesn't require them by default. 113The `wasmtime` crate features `custom-{virtual-memory,native-signals}` can be 114used to enable usage of these APIs if desired. 115