Skip to content

Commit d4c50b5

Browse files
yoshuawuytsyoshuawuyts
authored
Merge pull request #1302 from rust-lang/updates-to-rusts-wasi-targets
Blog post: Changes to Rust's WASI targets
2 parents ef9c480 + 861355e commit d4c50b5

File tree

1 file changed

+120
-0
lines changed

1 file changed

+120
-0
lines changed

‎posts/2024-04-09-updates-to-rusts-wasi-targets.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
layout: post
3+
title: Changes to Rust's WASI targets
4+
author: Yosh Wuyts
5+
---
6+
7+
[WASI 0.2 was recently
8+
stabilized](https://bytecodealliance.org/articles/WASI-0.2), and Rust has begun
9+
implementing first-class support for it in the form of a dedicated new target.
10+
Rust 1.78 will introduce new `wasm32-wasip1` (tier 2) and `wasm32-wasip2` (tier
11+
3) targets. `wasm32-wasip1` is an effective rename of the existing `wasm32-wasi`
12+
target, freeing the target name up for an eventual WASI 1.0 release. **Starting
13+
Rust 1.78 (May 2nd, 2024), users of WASI 0.1 are encouraged to begin migrating
14+
to the new `wasm32-wasip1` target before the existing `wasm32-wasi` target is
15+
removed in Rust 1.84 (January 5th, 2025).**
16+
17+
In this post we'll discuss the introduction of the new targets, the motivation
18+
behind it, what that means for the existing WASI targets, and a detailed
19+
schedule for these changes. This post is about the WASI targets only; the
20+
existing `wasm32-unknown-unknown` and `wasm32-unknown-emscripten` targets are
21+
unaffected by any changes in this post.
22+
23+
## Introducing `wasm32-wasip2`
24+
25+
After nearly five years of work the [WASI 0.2 specification](https://wasi.dev)
26+
was recently stabilized. This work builds on [WebAssembly
27+
Components](https://component-model.bytecodealliance.org) (think: strongly-typed
28+
ABI for Wasm), providing standard interfaces for things like asynchronous IO,
29+
networking, and HTTP. This will finally make it possible to write asynchronous
30+
networked services on top of WASI, something which wasn't possible using WASI
31+
0.1.
32+
33+
People interested in compiling Rust code to WASI 0.2 today are able to do so
34+
using the [cargo-component](https://github.com/bytecodealliance/cargo-component)
35+
tool. This tool is able to take WASI 0.1 binaries, and transform them to WASI 0.2
36+
Components using a shim. It also provides native support for common cargo
37+
commands such as `cargo build`, `cargo test`, and `cargo run`. While it
38+
introduces some inefficiencies because of the additional translation layer, in
39+
practice this already works really well and people should be enough able to get
40+
started with WASI 0.2 development.
41+
42+
We're however keen to begin making that translation layer obsolete. And for
43+
that reason we're happy to share that Rust has made its first steps towards
44+
that with the introduction of the [tier
45+
3](https://doc.rust-lang.org/rustc/platform-support.html#tier-3) `wasm32-wasip2`
46+
target landing in Rust 1.78. **This will initially miss a lot of expected**
47+
**features such as stdlib support, and we don't recommend people use this target**
48+
**quite yet.** But as we fill in those missing features over the coming months, we
49+
aim to eventually hit meet the criteria to become a tier 2 target, at which
50+
point the `wasm32-wasip2` target would be considered ready for general use. This
51+
work will happen through 2024, and we expect for this to land before the end of
52+
the calendar year.
53+
54+
## Renaming `wasm32-wasi` to `wasm32-wasip1`
55+
56+
The original name for what we now call WASI 0.1 was "WebAssembly System
57+
Interface, snapshot 1". Rust shipped support for this in 2019, and we did so
58+
knowing the target would likely undergo significant changes in the future. With
59+
the knowledge we have today though, we would not have chosen to introduce the
60+
"WASI, snapshot 1" target as `wasm32-wasi`. We should have instead chosen to add
61+
some suffix to the initial target triple so that the eventual stable WASI 1.0
62+
target can just be called `wasm32-wasi`.
63+
64+
In anticipation of both an eventual WASI 1.0 target, and to preserve consistency
65+
between target names, we'll begin rolling out a name change to the existing WASI
66+
0.1 target. Starting in Rust 1.78 (May 2nd, 2024) a new `wasm32-wasip1` target
67+
will become available. Starting Rust 1.81 (September 5th, 2024) we will begin
68+
warning existing users of `wasm32-wasi` to migrate to `wasm32-wasip1`. And
69+
finally in Rust 1.84 (January 9th, 2025) the `wasm32-wasi` target will no longer
70+
be shipped on the stable release channel. This will provide an 8 month
71+
transition period for projects to switch to the new target name when they update
72+
their Rust toolchains.
73+
74+
The name `wasip1` can be read as either "WASI (zero) point one" or "WASI preview
75+
one". The official specification uses the "preview" moniker, however in most
76+
communication the form "WASI 0.1" is now preferred. This target triple was
77+
chosen because it not only maps to both terms, but also more closely resembles
78+
the target terminology used in [other programming
79+
languages](https://go.dev/blog/wasi). This is something the WASI Preview 2
80+
specification [also makes note
81+
of](https://github.com/WebAssembly/WASI/tree/f45e72e5294e990c23d548eea32fd35c80525fd6/preview2#introduction).
82+
83+
## Timeline
84+
85+
This table provides the dates and cut-offs for the target rename from
86+
`wasm32-wasi` to `wasm32-wasip1`. The dates in this table do not apply to the
87+
newly-introduced `wasm32-wasi-preview1-threads` target; this will be renamed to
88+
`wasm32-wasip1-threads` in Rust 1.78 without going through a transition period.
89+
The tier 3 `wasm32-wasip2` target will also be made available in Rust 1.78.
90+
91+
| date | Rust Stable | Rust Beta | Rust Nightly | Notes |
92+
| ---------- | ----------- | --------- | ------------ | ---------------------------------------- |
93+
| 2024-02-08 | 1.76 | 1.77 | 1.78 | `wasm32-wasip1` available on nightly |
94+
| 2024-03-21 | 1.77 | 1.78 | 1.79 | `wasm32-wasip1` available on beta |
95+
| 2024-05-02 | 1.78 | 1.79 | 1.80 | `wasm32-wasip1` available on stable |
96+
| 2024-06-13 | 1.79 | 1.80 | 1.81 | warn if `wasm32-wasi` is used on nightly |
97+
| 2024-07-25 | 1.80 | 1.81 | 1.82 | warn if `wasm32-wasi` is used on beta |
98+
| 2024-09-05 | 1.81 | 1.82 | 1.83 | warn if `wasm32-wasi` is used on stable |
99+
| 2024-10-17 | 1.82 | 1.83 | 1.84 | `wasm32-wasi` unavailable on nightly |
100+
| 2024-11-28 | 1.83 | 1.84 | 1.85 | `wasm32-wasi` unavailable on beta |
101+
| 2025-01-09 | 1.84 | 1.85 | 1.86 | `wasm32-wasi` unavailable on stable |
102+
103+
## Conclusion
104+
105+
In this post we've discussed the upcoming updates to Rust's WASI targets. Come
106+
Rust 1.78 the `wasm32-wasip1` (tier 2) and `wasm32-wasip2` (tier 3) targets will
107+
be added. In Rust 1.81 we will begin warning if `wasm32-wasi` is being used. And
108+
in Rust 1.84, the existing `wasm32-wasi` target will be removed. This will free
109+
up `wasm32-wasi` to eventually be used for a WASI 1.0 target. Users will have 8
110+
months to switch to the new target name when they update their Rust toolchains.
111+
112+
The `wasm32-wasip2` target marks the start of native support for WASI 0.2. In
113+
order to target it today from Rust, people are encouraged to use
114+
[cargo-component](https://github.com/bytecodealliance/cargo-component) tool
115+
instead. The plan is to eventually graduate `wasm32-wasip2` to a tier-2 target,
116+
at which point `cargo-component` will be upgraded to support it natively instead.
117+
118+
With WASI 0.2 finally stable, it's an exciting time for WebAssembly development.
119+
We're happy for Rust to begin implementing native support for WASI 0.2, and
120+
we're excited for what this will enable people to build.

0 commit comments

Comments
 (0)