cranelift/docs/stability-platform-support.md

Platform Support

The wasmtime project is a configurable and lightweight runtime for WebAssembly which has a number of ways it can be configured. Not all features are supported on all platforms, but it is intended that wasmtime can run in some capacity on almost all platforms! The matrix of what's being tested, what works, and what's supported where is evolving over time, and this document hopes to capture a snapshot of what the current state of the world looks like.

All features of wasmtime should work on the following platforms:

• Linux x86_64
• Linux aarch64
• macOS x86_64
• Windows x86_64

For more detailed information about supported platforms, please check out the sections below!

JIT compiler support

The JIT compiler, backed by Cranelift, supports the x86_64 and aarch64 architectures at this time. Support for at least ARM and x86 is planned as well.

Usage of the JIT compiler will require a host operating system which supports creating executable memory pages on-the-fly. In Rust terms this generally means that std needs to be supported on this platform.

Interpreter support

At this time wasmtime does not have a mode in which it simply interprets WebAssembly code. It is planned to add support for an interpreter, however, and this will have minimal system dependencies. It is planned that the system will need to support some form of dynamic memory allocation, but other than that not much else will be needed.

What about #[no_std]?

The wasmtime project does not currently use #[no_std] for its crates, but this is not because it won't support it! For information on building Wasmtime for a custom target see the minimal build documentation. Please open an issue on the wasmtime repository to request support for a specific platform.

This is a common question we are asked, however, so to provide some more context on why Wasmtime is the way it is, here's some responses to frequent points raised about #![no_std]:

• What if my platform doesn't have std? - For platforms without support for the Rust standard library the JIT compiler of Wasmtime often won't run on the platform as well. The JIT compiler requires mmap (or an equivalent), and presence of mmap often implies presence of a libc which means Rust's std library works.

  Cargo's -Z build-std feature feature is also intended to help easily build the standard library for all platforms. With this feature you can recompile the standard library (using Nightly Rust for now) with a custom target specification if necessary. Additionally the intention at this time is to get std building for all platforms, regardless of what the platform actually supports. This change is taking time to implement, but rust-lang/rust#74033 is an example of this support growing over time.

  We're also interested in running Wasmtime without a JIT compiler in the future, but that is not implemented at this time. Implementing this will require a lot more work than tagging crates #![no_std]. The Wasmtime developers are also very interested in supporting as many targets as possible, so if Wasmtime doesn't work on your platform yet we'd love to learn why and what we can do to support that platform, but the conversation here is typically more nuanced than simply making wasmtime compile without std.

• Doesn't #![no_std] have smaller binary sizes? - There's a lot of factors that affect binary size in Rust. Compilation options are a huge one but beyond that idioms and libraries linked matter quite a lot as well. Code is not inherently large when using std instead of core, it's just that often code using std has more dependencies (like std::thread) which requires code to bind. Code size improvements can be made to code using std and core equally, and switching to #![no_std] is not a silver bullet for compile sizes.

• The patch to switch to #![no_std] is small, why not accept it? - PRs to switch to #![no_std] are often relatively small or don't impact too many parts of the system. There's a lot more to developing a #![no_std] WebAssembly runtime than switching a few crates, however. Maintaining a #![no_std] library over time has a number of costs associated with it:

  • Rust has no stable way to diagnose no_std errors in an otherwise std build, which means that to support this feature it must be tested on CI with a no_std target. This is costly in terms of CI time, CI maintenance, and developers having to do extra builds to avoid CI errors. Note that this isn't more costly than any other platform supported by Wasmtime, but it's a cost nonetheless.

  • Idioms in #![no_std] are quite different than normal Rust code. You'll import from different crates (core instead of std) and data structures have to all be manually imported from alloc. These idioms are difficult to learn for newcomers to the project and are not well documented in the ecosystem. This cost of development and maintenance is not unique to Wasmtime but in general affects the #![no_std] ecosystem at large, unfortunately.

  • Currently Wasmtime does not have a target use case which requires #![no_std] support, so it's hard to justify these costs of development. We're very interested in supporting as many use cases and targets as possible, but the decision to support a target needs to take into account the costs associated so we can plan accordingly. Effectively we need to have a goal in mind instead of taking on the costs of #![no_std] blindly.

  • At this time it's not clear whether #![no_std] will be needed long-term, so eating short-term costs may not pay off in the long run. Features like Cargo's -Z build-std may mean that #![no_std] is less and less necessary over time.

• How can Wasmtime support #![no_std] if it uses X? - Wasmtime as-is today is not suitable for many #![no_std] contexts. For example it might use mmap for allocating JIT code memory, leverage threads for caching, or use thread locals when calling into JIT code. These features are difficult to support in their full fidelity on all platforms, but the Wasmtime developers are very much aware of this! Wasmtime is intended to be configurable where many of these features are compile-time or runtime options. For example caches can be disabled, JITs can be removed and replaced with interpreters, or users could provide a callback to allocate memory instead of using the OS. This is sort of a long-winded way of saying that Wasmtime on the surface may today look like it won't support #![no_std], but this is almost always simply a matter of time and development priorities rather than a fundamental reason why Wasmtime couldn't support #![no_std].

Note that at this time these guidelines apply not only to Wasmtime but also to some of its dependencies developed by the Bytecode Alliance such as the wasm-tools repository. These projects don't have the same runtime requirements as Wasmtime (e.g. wasmparser doesn't need mmap), but we're following the same guidelines above at this time. Patches to add #![no_std], while possibly small, incur many of the same costs and also have an unclear longevity as features like -Z build-std evolve.