Nine Rules for Running Rust on WASM WASI | by Carl M. Kadie | Sep, 2024

Based mostly on my expertise with range-set-blaze, an information construction mission, listed below are the choices I like to recommend, described one by one. To keep away from wishy-washiness, I’ll specific them as guidelines.

In 2019, Docker co-creator Solomon Hykes tweeted:

If WASM+WASI existed in 2008, we wouldn’t have wanted to created Docker. That’s how necessary it’s. Webassembly on the server is the way forward for computing. A standardized system interface was the lacking hyperlink. Let’s hope WASI is as much as the duty.

Right this moment, if you happen to comply with expertise information, you’ll see optimistic headlines like these:

If WASM WASI had been really prepared and helpful, everybody would already be utilizing it. The truth that we preserve seeing these headlines suggests it’s not but prepared. In different phrases, they wouldn’t must preserve insisting that WASM WASI is prepared if it actually had been.

As of WASI Preview 1, right here is how issues stand: You possibly can entry some file operations, atmosphere variables, and have entry to time and random quantity technology. Nonetheless, there isn’t a help for networking.

WASM WASI would possibly be helpful for sure AWS Lambda-style internet companies, however even that’s unsure. As a result of wouldn’t you like to compile your Rust code natively and run twice as quick at half the fee in comparison with WASM WASI?

Perhaps WASM WASI is beneficial for plug ins and extensions. In genomics, I’ve a Rust extension for Python, which I compile for 25 totally different combos (5 variations of Python throughout 5 OS targets). Even with that, I don’t cowl each attainable OS and chip household. May I exchange these OS targets with WASM WASI? No, it might be too gradual. May I add WASM WASI as a sixth “catch-all” goal? Perhaps, but when I actually need portability, I’m already required to help Python and will simply use Python.

So, what’s WASM WASI good for? Proper now, its predominant worth lies in being a step towards working code within the browser or on embedded methods.

In Rule 1, I discussed “OS targets” in passing. Let’s look deeper into Rust targets — important info not only for WASM WASI, but additionally for normal Rust growth.

On my Home windows machine, I can compile a Rust mission to run on Linux or macOS. Equally, from a Linux machine, I can compile a Rust mission to focus on Home windows or macOS. Listed below are the instructions I exploit so as to add and verify the Linux goal to a Home windows machine:

rustup goal add x86_64-unknown-linux-gnu
cargo verify --target x86_64-unknown-linux-gnu

Apart: Whereas cargo verify verifies that the code compiles, constructing a totally useful executable requires extra instruments. To cross-compile from Home windows to Linux (GNU), you’ll additionally want to put in the Linux GNU C/C++ compiler and the corresponding toolchain. That may be difficult. Happily, for the WASM targets we care about, the required toolchain is simple to put in.

To see all of the targets that Rust helps, use the command:

rustc --print target-list

It can record over 200 targets together with x86_64-unknown-linux-gnu, wasm32-wasip1, and wasm32-unknown-unknown.

Goal names include as much as 4 elements: CPU household, vendor, OS, and atmosphere (for instance, GNU vs LVMM):

Now that we perceive one thing of targets, let’s go forward and set up the one we’d like for WASM WASI.

To run our Rust code on WASM outdoors of a browser, we have to goal wasm32-wasip1 (32-bit WebAssembly with WASI Preview 1). We’ll additionally set up WASMTIME, a runtime that enables us to run WebAssembly modules outdoors of the browser, utilizing WASI.

rustup goal add wasm32-wasip1
cargo set up wasmtime-cli

To check our setup, let’s create a brand new “Howdy, WebAssembly!” Rust mission utilizing cargo new. This initializes a brand new Rust bundle:

cargo new hello_wasi
cd hello_wasi

Edit src/predominant.rs to learn:

fn predominant() {
#[cfg(not(target_arch = "wasm32"))]
println!("Howdy, world!");
#[cfg(target_arch = "wasm32")]
println!("Howdy, WebAssembly!");
}

Apart: We’ll look deeper into the #[cfg(...)] attribute, which permits conditional compilation, in Rule 4.

Now, run the mission with cargo run, and it’s best to see Howdy, world! printed to the console.

Subsequent, create a .cargo/config.toml file, which specifies how Rust ought to run and check the mission when concentrating on WASM WASI.

[target.wasm32-wasip1]
runner = "wasmtime run --dir ."

Apart: This .cargo/config.toml file is totally different from the principle Cargo.toml file, which defines your mission’s dependencies and metadata.

Now, if you happen to say:

cargo run --target wasm32-wasip1

It’s best to see Howdy, WebAssembly!. Congratulations! You’ve simply efficiently run some Rust code within the container-like WASM WASI atmosphere.

Now, let’s examine #[cfg(...)]—a necessary device for conditionally compiling code in Rust. In Rule 3, we noticed:

fn predominant() {
#[cfg(not(target_arch = "wasm32"))]
println!("Howdy, world!");
#[cfg(target_arch = "wasm32")]
println!("Howdy, WebAssembly!");
}

The #[cfg(...)] strains inform the Rust compiler to incorporate or exclude sure code gadgets based mostly on particular circumstances. A “code merchandise” refers to a unit of code corresponding to a perform, assertion, or expression.

With #[cfg(…)] strains, you’ll be able to conditionally compile your code. In different phrases, you’ll be able to create totally different variations of your code for various conditions. For instance, when compiling for the wasm32 goal, the compiler ignores the #[cfg(not(target_arch = "wasm32"))] block and solely contains the next:

fn predominant() {
println!("Howdy, WebAssembly!");
}

You specify circumstances through expressions, for instance, target_arch = "wasm32". Supported keys embody target_os and target_arch. See the Rust Reference for the full list of supported keys. You can even create expressions with Cargo options, which we are going to study in Rule 6.

You might mix expressions with the logical operators not, any, and all. Rust’s conditional compilation doesn’t use conventional if...then...else statements. As a substitute, you will need to use #[cfg(...)] and its negation to deal with totally different circumstances:

#[cfg(not(target_arch = "wasm32"))]
...
#[cfg(target_arch = "wasm32")]
...

To conditionally compile a complete file, place #![cfg(...)] on the prime of the file. (Discover the “!”). That is helpful when a file is barely related for a selected goal or configuration.

You can even use cfg expressions in Cargo.toml to conditionally embody dependencies. This lets you tailor dependencies to totally different targets. For instance, this says “depend upon Criterion with Rayon when not concentrating on wasm32”.

[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
criterion = { model = "0.5.1", options = ["rayon"] }

Apart: For extra info on utilizing cfg expressions in Cargo.toml, see my article: Nine Rust Cargo.toml Wats and Wat Nots: Grasp Cargo.toml formatting guidelines and keep away from frustration | In direction of Information Science (medium.com).

It’s time to attempt to run your mission on WASM WASI. As described in Rule 3, create a .cargo/config.toml file to your mission. It tells Cargo the right way to run and check your mission on WASM WASI.

[target.wasm32-wasip1]
runner = "wasmtime run --dir ."

Subsequent, your project — like all good code — should already contain tests. My range-set-blaze mission contains, for instance, this check:

#[test]
fn insert_255u8() {
let range_set_blaze = RangeSetBlaze::::from_iter([255]);
assert!(range_set_blaze.to_string() == "255..=255");
}

Let’s now try and run your mission’s exams on WASM WASI. Use the next command:

cargo check --target wasm32-wasip1

If this works, it’s possible you’ll be carried out — but it surely most likely received’t work. Once I do this on range-set-blaze, I get this error message that complains about utilizing Rayon on WASM.

 error: Rayon can't be used when concentrating on wasi32. Attempt disabling default options.
--> C:Userscarlk.cargoregistrysrcindex.crates.io-6f17d22bba15001fcriterion-0.5.1srclib.rs:31:1
|
31 | compile_error!("Rayon can't be used when concentrating on wasi32. Attempt disabling default options.");

To repair this error, we should first perceive Cargo options.

To resolve points just like the Rayon error in Rule 5, it’s necessary to grasp how Cargo options work.

In Cargo.toml, an elective [features] part lets you outline totally different configurations, or variations, of your mission relying on which options are enabled or disabled. For instance, here’s a simplified a part of the Cargo.toml file from the Criterion benchmarking project:

[features]
default = ["rayon", "plotters", "cargo_bench_support"]
rayon = ["dep:rayon"]
plotters = ["dep:plotters"]
html_reports = []
cargo_bench_support = []
[dependencies]
#...
# Non-obligatory dependencies
rayon = { model = "1.3", elective = true }
plotters = { model = "^0.3.1", elective = true, default-features = false, options = [
"svg_backend",
"area_series",
"line_series",
] }

This defines 4 Cargo options: rayon, plotters, html_reports, and cargo_bench_support. Since every characteristic might be included or excluded, these 4 options create 16 attainable configurations of the mission. Be aware additionally the particular default Cargo characteristic.

A Cargo characteristic can embody different Cargo options. Within the instance, the particular default Cargo characteristic contains three different Cargo options — rayon, plotters, and cargo_bench_support.

A Cargo characteristic can embody a dependency. The rayon Cargo characteristic above contains the rayon crate as a dependent bundle.

Furthermore, dependent packages could have their very own Cargo options. For instance, the plotters Cargo characteristic above contains the plotters dependent bundle with the next Cargo options enabled: svg_backend, area_series, and line_series.

You possibly can specify which Cargo options to allow or disable when working cargo verify, cargo construct, cargo run, or cargo check. As an example, if you happen to’re engaged on the Criterion mission and wish to verify solely the html_reports characteristic with none defaults, you’ll be able to run:

cargo verify --no-default-features --features html_reports

This command tells Cargo to not embody any Cargo options by default however to particularly allow the html_reports Cargo characteristic.

Inside your Rust code, you’ll be able to embody/exclude code gadgets based mostly on enabled Cargo options. The syntax makes use of #cfg(…), as per Rule 4:

#[cfg(feature = "html_reports")]
SOME_CODE_ITEM

With this understanding of Cargo options, we are able to now try to repair the Rayon error we encountered when working exams on WASM WASI.

Once we tried working cargo check --target wasm32-wasip1, a part of the error message acknowledged: Criterion ... Rayon can't be used when concentrating on wasi32. Attempt disabling default options. This implies we should always disable Criterion’s rayon Cargo characteristic when concentrating on WASM WASI.

To do that, we have to make two adjustments in our Cargo.toml. First, we have to disable the rayon characteristic from Criterion within the [dev-dependencies] part. So, this beginning configuration:

[dev-dependencies]
criterion = { model = "0.5.1", options = ["html_reports"] }

turns into this, the place we explicitly flip off the default options for Criterion after which allow all of the Cargo options besides rayon.

[dev-dependencies]
criterion = { model = "0.5.1", options = [
"html_reports",
"plotters",
"cargo_bench_support"],
default-features = false }

Subsequent, to make sure rayon remains to be used for non-WASM targets, we add it again in with a conditional dependency in Cargo.toml as follows:

[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
criterion = { model = "0.5.1", options = ["rayon"] }

Typically, when concentrating on WASM WASI, it’s possible you’ll want to change your dependencies and their Cargo options to make sure compatibility. Generally this course of is easy, however different occasions it may be difficult — and even unimaginable, as we’ll talk about in Rule 8.

Apart: Within the subsequent article on this sequence — about WASM within the Browser — we’ll go deeper into methods for fixing dependencies.

After working the exams once more, we transfer previous the earlier error, solely to come across a brand new one, which is progress!

#[test]
fn test_demo_i32_len() {
assert_eq!(demo_i32_len(i32::MIN..=i32::MAX), u32::MAX as usize + 1);
^^^^^^^^^^^^^^^^^^^^^ try and compute 
`usize::MAX + 1_usize`, which might overflow
}

The compiler complains that u32::MAX as usize + 1 overflows. On 64-bit Home windows the expression doesn’t overflow as a result of usize is identical as u64 and might maintain u32::MAX as usize + 1. WASM, nonetheless, is a 32-bit atmosphere so usize is identical as u32 and the expression is one too large.

The repair right here is to exchange usize with u64, making certain that the expression doesn’t overflow. Extra usually, the compiler received’t at all times catch these points, so it’s necessary to assessment your use of usize and isize. Should you’re referring to the dimensions or index of a Rust information construction, usize is appropriate. Nonetheless, if you happen to’re coping with values that exceed 32-bit limits, it’s best to use u64 or i64.

Apart: In a 32-bit atmosphere, a Rust array, Vec, BTreeSet, and many others., can solely maintain as much as 2³²−1=4,294,967,295 parts.

So, we’ve fastened the dependency subject and addressed a usize overflow. However can we repair every thing? Sadly, the reply is not any.

WASM WASI Preview 1 (the present model) helps file entry (inside a specified listing), studying atmosphere variables, and dealing with time and random numbers. Nonetheless, its capabilities are restricted in comparison with what you would possibly anticipate from a full working system.

In case your mission requires entry to networking, asynchronous duties with Tokio, or multithreading with Rayon, Sadly, these options aren’t supported in Preview 1.

Happily, WASM WASI Preview 2 is predicted to enhance upon these limitations, providing extra options, together with higher help for networking and presumably asynchronous duties.

So, your exams move on WASM WASI, and your mission runs efficiently. Are you carried out? Not fairly. As a result of, as I wish to say:

If it’s not in CI, it doesn’t exist.

Steady integration (CI) is a system that may routinely run your exams each time you replace your code, making certain that your code continues to work as anticipated. By including WASM WASI to your CI, you’ll be able to assure that future adjustments received’t break your mission’s compatibility with the WASM WASI goal.

In my case, my mission is hosted on GitHub, and I exploit GitHub Actions as my CI system. Right here’s the configuration I added to .github/workflows/ci.yml to check my mission on WASM WASI:

test_wasip1:
identify: Take a look at WASI P1
runs-on: ubuntu-latest
steps:
- identify: Checkout
makes use of: actions/checkout@v4
- identify: Arrange Rust
makes use of: dtolnay/rust-toolchain@grasp
with:
toolchain: secure
targets: wasm32-wasip1
- identify: Set up Wasmtime
run: |
curl https://wasmtime.dev/set up.sh -sSf | bash
echo "${HOME}/.wasmtime/bin" >> $GITHUB_PATH
- identify: Run WASI exams
run: cargo check --verbose --target wasm32-wasip1

By integrating WASM WASI into CI, I can confidently add new code to my mission. CI will routinely check that every one my code continues to help WASM WASI sooner or later.