1# Platform Support
2
3The `wasmtime` project is a configurable and lightweight runtime for WebAssembly
4which has a number of ways it can be configured. Not all features are supported
5on all platforms, but it is intended that `wasmtime` can run in some capacity on
6almost all platforms! The matrix of what's being tested, what works, and what's
7supported where is evolving over time, and this document hopes to capture a
8snapshot of what the current state of the world looks like.
9
10All features of `wasmtime` should work on the following platforms:
11
12* Linux x86\_64
13* Linux aarch64
14* macOS x86\_64
15* Windows x86\_64
16
17For more detailed information about supported platforms, please check out the
18sections below!
19
20## JIT compiler support
21
22The JIT compiler, backed by Cranelift, supports the x86\_64 and aarch64
23architectures at this time. Support for at least ARM and x86 is planned as well.
24
25Usage of the JIT compiler will require a host operating system which supports
26creating executable memory pages on-the-fly. In Rust terms this generally means
27that `std` needs to be supported on this platform.
28
29## Interpreter support
30
31At this time `wasmtime` does not have a mode in which it simply interprets
32WebAssembly code. It is planned to add support for an interpreter, however, and
33this will have minimal system dependencies. It is planned that the system will
34need to support some form of dynamic memory allocation, but other than that not
35much else will be needed.
36
37## What about `#[no_std]`?
38
39The `wasmtime` project does not currently use `#[no_std]` for its crates, but
40this is not because it won't support it! At this time we're still gathering use
41cases for for what `#[no_std]` might entail, so if you're interested in this
42we'd love to hear about your use case! Feel free to [open an
43issue](https://github.com/bytecodealliance/wasmtime/issues/new) on the
44`wasmtime` repository to discuss this.
45
46This is a common question we are asked, however, so to provide some more context
47on why Wasmtime is the way it is, here's some responses to frequent points
48raised about `#![no_std]`:
49
50* **What if my platform doesn't have `std`?** - For platforms without support
51  for the Rust standard library the JIT compiler of Wasmtime often won't run on
52  the platform as well. The JIT compiler requires `mmap` (or an equivalent), and
53  presence of `mmap` often implies presence of a libc which means Rust's `std`
54  library works.
55
56  Cargo's [`-Z build-std` feature][zbuild-std] feature is also intended to help
57  easily build the standard library for all platforms. With this feature you can
58  recompile the standard library (using Nightly Rust for now) with a [custom
59  target specification][custom-target] if necessary. Additionally the intention
60  at this time is to get `std` building for all platforms, regardless of what
61  the platform actually supports. This change is taking time to implement, but
62  [rust-lang/rust#74033] is an example of this support growing over time.
63
64  We're also interested in running Wasmtime without a JIT compiler in the
65  future, but that is not implemented at this time. Implementing this will
66  require a lot more work than tagging crates `#![no_std]`. The Wasmtime
67  developers are also very interested in supporting as many targets as possible,
68  so if Wasmtime doesn't work on your platform yet we'd love to learn why and
69  what we can do to support that platform, but the conversation here is
70  typically more nuanced than simply making `wasmtime` compile without `std`.
71
72* **Doesn't `#![no_std]` have smaller binary sizes?** - There's a lot of factors
73  that affect binary size in Rust. Compilation options are a huge one but beyond
74  that idioms and libraries linked matter quite a lot as well. Code is not
75  inherently large when using `std` instead of `core`, it's just that often code
76  using `std` has more dependencies (like `std::thread`) which requires code to
77  bind. Code size improvements can be made to code using `std` and `core`
78  equally, and switching to `#![no_std]` is not a silver bullet for compile
79  sizes.
80
81* **The patch to switch to `#![no_std]` is small, why not accept it?** - PRs to
82  switch to `#![no_std]` are often relatively small or don't impact too many
83  parts of the system. There's a lot more to developing a `#![no_std]`
84  WebAssembly runtime than switching a few crates, however. Maintaining a
85  `#![no_std]` library over time has a number of costs associated with it:
86
87  * Rust has no stable way to diagnose `no_std` errors in an otherwise `std`
88    build, which means that to supoprt this feature it must be tested on CI with
89    a `no_std` target. This is costly in terms of CI time, CI maintenance, and
90    developers having to do extra builds to avoid CI errors. Note that this
91    isn't *more* costly than any other platform supported by Wasmtime, but it's
92    a cost nonetheless.
93
94  * Idioms in `#![no_std]` are quite different than normal Rust code. You'll
95    import from different crates (`core` instead of `std`) and data structures
96    have to all be manually imported from `alloc`. These idioms are difficult to
97    learn for newcomers to the project and are not well documented in the
98    ecosystem. This cost of development and maintenance is not unique to
99    Wasmtime but in general affects the `#![no_std]` ecosystem at large,
100    unfortunately.
101
102  * Currently Wasmtime does not have a target use case which requires
103    `#![no_std]` support, so it's hard to justify these costs of development.
104    We're very interested in supporting as many use cases and targets as
105    possible, but the decision to support a target needs to take into account
106    the costs associated so we can plan accordingly. Effectively we need to have
107    a goal in mind instead of taking on the costs of `#![no_std]` blindly.
108
109  * At this time it's not clear whether `#![no_std]` will be needed long-term,
110    so eating short-term costs may not pay off in the long run. Features like
111    Cargo's [`-Z build-std`][zbuild-std] may mean that `#![no_std]` is less and
112    less necessary over time.
113
114* **How can Wasmtime support `#![no_std]` if it uses X?** - Wasmtime as-is today
115  is not suitable for many `#![no_std]` contexts. For example it might use
116  `mmap` for allocating JIT code memory, leverage threads for caching, or use
117  thread locals when calling into JIT code. These features are difficult to
118  support in their full fidelity on all platforms, but the Wasmtime developers
119  are very much aware of this! Wasmtime is intended to be configurable where
120  many of these features are compile-time or runtime options. For example caches
121  can be disabled, JITs can be removed and replaced with interpreters, or users
122  could provide a callback to allocate memory instead of using the OS.
123  This is sort of a long-winded way of saying that Wasmtime on the surface may
124  today look like it won't support `#![no_std]`, but this is almost always
125  simply a matter of time and development priorities rather than a fundamental
126  reason why Wasmtime *couldn't* support `#![no_std]`.
127
128Note that at this time these guidelines apply not only to Wasmtime but also to
129some of its dependencies developed by the Bytecode Alliance such as the
130[wasm-tools repository](https://github.com/bytecodealliance/wasm-tools). These
131projects don't have the same runtime requirements as Wasmtime (e.g. `wasmparser`
132doesn't need `mmap`), but we're following the same guidelines above at this
133time. Patches to add `#![no_std]`, while possibly small, incur many of the same
134costs and also have an unclear longevity as features like [`-Z
135build-std`][zbuild-std] evolve.
136
137[zbuild-std]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std
138[custom-target]: https://doc.rust-lang.org/rustc/targets/custom.html
139[rust-lang/rust#74033]: https://github.com/rust-lang/rust/pull/74033
140