How to run WebAssembly from your Rust Program
Tags: rust, webassembly, wasmtime
Published: 2023-02-13 13:41:03

_Cover Photo by [Arun Prakash](https://unsplash.com/@its_arunprakash?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/photos/a6a0igv3Ris?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)_


Have you ever considered enhancing your Rust program's capabilities with
another language? WebAssembly (wasm) is a perfect candidate to script
behavior and add capabilities without the hassle. Starting with
WebAssembly is not as difficult as it might seem. This article will
explore how to embed Web Assembly code in a Rust application.

## What is Web Assembly?

According to MDN:

> WebAssembly is a new type of code that can be run in modern web
> browsers — it is a low-level assembly-like language with a compact
> binary format that runs with near-native performance and provides
> languages such as C/C++, C# and Rust with a compilation target so that
> they can run on the web. It is also designed to run alongside
> JavaScript, allowing both to work together. –
> <https://developer.mozilla.org/en-US/docs/webassembly>

wasm has been picking up steam since its inception in March 2017. While
initially designed for the browser, people are actively working on
building runtimes and environments on all sorts of platforms. This post
focuses on using wasm as a secure runtime to script application
behavior.

## Implement a Custom Programming Language?

Sometimes, we might need the user to script certain behaviors in our
application. While use cases vary, the first question that comes up is:
Do I need to build my own [Domain Specific
Language(DSL)](https://en.wikipedia.org/wiki/Domain-specific_language)?
The inner geek might answer this with a definite YES! It's a great
challenge, though rolling a custom language has some serious drawbacks:

-   Users need to spend extra time learning it
-   There's little to no support on pages such as StackOverflow
-   Additional confusion if the DSL imitates syntax from an existing
    language

As the first two bullet points line out, a lot of effort goes into
supporting a custom language. While it grants you many liberties when
implementing use cases and features, the developer experience often
suffers. Before discussing why Web Assembly is the solution, let's look
at a real-world example of embedding another language.

## CouchDB: Embedding JavaScript

[Apache CouchDB](https://couchdb.apache.org/) belongs to the family of
NoSQL databases. It is a document store with a strong focus on
replication and reliability. One of the most significant differences
between CouchDB and a relational database (besides the absence of tables
and schemas) is how you query data. Relational databases allow their
users to execute arbitrary and dynamic queries via
[SQL](https://en.wikipedia.org/wiki/SQL). Each SQL query may look
completely different than the previous one. These dynamic aspects are
significant for use cases where you work exploratively with your dataset
but don't matter as much in a web context. Additionally, defining an
index for a specific table is optional. Most developers will define
indices to boost performance, but the database does not require it.

CouchDB, on the other hand, does not allow developers to run dynamic
queries on the fly. This circumstance might seem a bit odd at first.
However, once you realize that regular web application database queries
are static, this perceived restriction does not matter as much anymore.
While implementing use cases, a web developer defines a query while
implementing code. Once defined, this query stays the same, no matter
where the code runs (development, staging, and production).

CouchDB also does not use SQL or a custom language. Instead, it
leverages a language most web developers are already familiar with:
JavaScript. The main database engine is written in Erlang, allowing
users to specify queries in JavaScript. This design decision has several
reasons: CouchDB requires users to build an index by default. Users will
query a specific index when they want to fetch data. To construct an
index, CouchDB will run user-defined JavaScript code. This code comes in
the form of a `map` function that gets called for each document in the
database. The `map` function decides if a document should be listed in
the index.

``` javascript
//Example of a map function in CouchDB
//Source: https://docs.couchdb.org/en/stable/ddocs/ddocs.html#view-functions
function (doc) {
 if (doc.type === 'post' && doc.tags && Array.isArray(doc.tags)) {
   doc.tags.forEach(function (tag) {
     emit(tag.toLowerCase(), 1);
   });
 }
}
```

The advantage here is clear: The user can define complex logic to build
their indices in a well-documented and understood programming language.
The barrier to getting started is much lower compared to a database that
uses a custom language.

## WebAssembly is the Answer

Embedding JavaScript has been a well-accepted solution for a long time.
The main reason is that JavaScript does not have a substantial standard
library. It lacks many features other languages ship out of the box,
such as any form of I/O. This lack of features is primarily due to the
fact that JavaScript running in the browser does not require filesystem
access (it's a security feature).

-   The disadvantage\*: JavaScript runtimes are complex and are designed
    for long-running programs. Also, we might not want to rely on
    JavaScript in the first place but on other languages. That's where
    WebAssembly becomes an alternative. First of all, its footprint is
    much smaller. It does not come with a standard library nor allows
    access to the outside world by default. From a developer's point of
    view, the main benefit is: We can compile almost every currently
    popular programming language to WebAssembly. We can support both
    users if one user prefers to write Python while another wants to
    stick to JavaScript. While we will look at some wasm code later in
    the tutorial, it is mainly a compilation target. Developers do not
    write wasm by hand.

    The wasm runtime does not care what language you write your code in.
    Our advantage: An improved developer experience, as developers can
    leverage the language they're most comfortable with and compile down
    to Web Assembly at the end of the day.

wasm is the perfect candidate as an embedded runtime to allow users to
script application behavior.

## How to Embed WebAssembly in a Rust Application

In this tutorial, we rely on
[`wasmtime`](https://github.com/bytecodealliance/wasmtime). `wasmtime`
is a standalone runtime for WebAssembly.

Let's start by creating a new Rust project:

``` bash
$ cargo new rustwasm
$ cd rustwasm
```

Next, let's install a few crates we'll need:

``` bash
$ cargo add anyhow
$ cargo add wasmtime
```

Once the crates are installed, we add the code to our `main.rs` file
(explanation below):

``` rust
 //Original Code from https://github.com/bytecodealliance/wasmtime/blob/main/examples/hello.rs
 //Adapted for brevity
 use anyhow::Result;
 use wasmtime::*;

 fn main() -> Result<()> {
     println!("Compiling module...");
     let engine = Engine::default();
     let module = Module::from_file(&engine, "hello.wat")?; //(1)

     println!("Initializing...");
     let mut store = Store::new(
         &engine,
         ()
     ); //(2)

     println!("Creating callback...");
     let hello_func = Func::wrap(&mut store, |_caller: Caller<'_, ()>| {
         println!("Calling back...");
     }); //(3)

     println!("Instantiating module...");
     let imports = [hello_func.into()];
     let instance = Instance::new(&mut store, &module, &imports)?;

     println!("Extracting export...");
     let run = instance.get_typed_func::<(), ()>(&mut store, "run")?; //(4)

     println!("Calling export...");
     run.call(&mut store, ())?; //(5)

     println!("Done.");
     Ok(())
}
```

### Step 1:

We start by loading a module from disk. In this case, we're loading
`hello.wat`. By default, you would distribute Web Assembly code in
binary form. For our purposes, however, we rely on the textual
representation (`wat`).

### Step 2:

We also want to share some state between the host and wasm code when we
run wasm code. With `Store`, we can share this context. In our case, we
don't need to share anything right now. Therefore we specify a Unit type
as the second argument to `Store::new`.

### Step 3:

In this tutorial, we want to make a Rust function available to the wasm
code it then subsequently can call. We wrap a Rust closure with
`Func::wrap`. This function does not take any arguments and also does
not return anything; it just prints out `"Calling back"` when invoked.

### Step 4:

wasm code by default does not have a `main` function; we treat it as a
library. In our case, we expect a `run` function to be present, which
we'll use as our entry point.

Before we can invoke the function, we need to retrieve it first. We use
`get_typed_func` to specify its type signature as well. If we find it in
the binary, we can invoke it.

### Step 5:

Now that we located the function let's `call` it.

## Inspecting Web Assembly Code

With our Rust program in place, let's have a look at the wasm code we
want to load:

``` wasm
(module
  (func $hello (import "" "hello"))
  (func (export "run") (call $hello))
)
```

The wasm text format uses so-called S-expressions.

> S-expressions are a very old and very simple textual format for
> representing trees, and thus we can think of a module as a tree of
> nodes that describe the module's structure and its code. Unlike the
> Abstract Syntax Tree of a programming language, though, WebAssembly's
> tree is pretty flat, mostly consisting of lists of instructions. –
> <https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format>

This small program performs three tasks:

-   It imports a function with the name `hello` from its host
    environment and binds it to the local name `$hello`.
    (`(func $hello (import "" "hello"))`)
-   It defines a function `run` which it also exports.
-   In `run`, it calls the imported `$hello` function.

As mentioned earlier, `.wat` (same for the binary representation) is not
something we usually write by hand but is generated by a compiler.

## Run everything

With all components in place, let's run it:

``` bash
 $ cargo run 
     Finished dev [unoptimized + debuginfo] target(s) in 0.62s
     Running `target/debug/rustwasm`
Compiling module...
Initializing...
Creating callback...
Instantiating module...
Extracting export...
Calling export...
Calling back...
Done.
```

Find the full source code on [GitHub](https://github.com/schultyy/rust-wasm-intro).