rust-webassembly

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

rust-webassembly

(★ 72)

Provide examples of how to use Rust to compile to Web Assembly

rust-webassembly Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Introduction
The goal of this repo is to provide examples of how to use Rust to compile to Web Assembly.

## Motivation

I recently completed a hack-a-thon where my team made a Rust Javascript AST parser, which compiled to Web Assembly. I found several pieces of information on the web, but everything felt disconnected. This repo aims to bring together the information I learned so that others can compile to Web Assembly.

## Getting Started

*Assumptions:*
	* You have a basic understand of Rust and Web Languages (HTML/JS)
	* You have Rust installed

### Web Assembly Target

You'll need to add the Web Assembly target, so that Rust can compile to it. Run this command in your terminal:

`rustup target add wasm32-unknown-emscripten`

### Emscripten SDK + tool chain

Next, you need to install the emscripten tool chain. You can either compile it from source, or install the portable. Download the portable version from: http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html#download-and-install

Extract it some where, and execute `source ./emsdk_env.sh` against the included `emsdk_env.sh`.

This should cause `emcc` to become available to your terminal. Test this by reading the version string: `emcc -v`, if it doesn't appear, you may need to update your `$PATH` to include the path to the extracted emsdk.

Now we need install the toolchain.

Update the list of available binaries: `emsdk update`
Install latest: `emsdk install latest`
Activate latest: `emsdk activate latest`

If you don't want latest, or want to install a different version, first execute `emsdk list` to get a list of available binaries, then install the matching version.

### Ready to compile

#### rustc

When compiling with EMSDK using `rustc`, you'll generate an example HTML file, and a Module Javascript file in addition to the WASM. The following example presumes you have a "hello world" rust file.

```
rustc --target=wasm32-unknown-emscripten hello.rs -o hello.html
Generates::

hello.wasm
hello.js
hello.html
```

#### cargo build

Compiling using `cargo build` is a bit more complex. The following examples presumes you have a "hello world" cargo project, i.e, `cargo new hello-world`.

```
cargo build --release --target wasm32-unknown-emscripten
```

This will create a release with the WASM target. Unlike the `rustc` example, this will only generate the `.wasm` and `.js` file (amongst other cargo build files).

You'll need to create an HTML file which includes the generated script. *Note:* the generated JS file assumes the WASM is in the same directory as the JS file.

```
# index.html
<html>
	<head>Hello-Cargo</head>
	<body>
		<script type="text/javascript" src="./hello-cargo.js"></script>
		<script type="text/javascript">
			Module.addOnInit(function () {
				console.log('Module ready!');
			});
		</script>
	</body>
</html>
```

### Executing methods in rust

Now lets do something meaningful, and execute a method defined in our rust application.

Lets say that you have a string, "One apon a time" and you want to replace "One" with "Once".

```
main.rs

use std::os::raw::c_char;
use std::ffi::CStr;
use std::ffi::CString;

fn my_string_safe(i: *mut c_char) -> String {
  unsafe {
      CStr::from_ptr(i).to_string_lossy().into_owned()
  }
}

#[no_mangle]
pub fn fix_story(in: *mut c_char) -> *mut c_char {
	let data = my_string_safe(in);
	let out = data.replace("one", "once");

CString::new(out.as_str())
		.unwrap()
		.into_raw()
}
```
```
.cargo/config

[target.wasm32-unknown-emscripten]
rustflags = [
    "-Clink-args=-s EXPORTED_FUNCTIONS=['_fix_story'] -s ASSERTIONS=1",
]
```
```
index.html

#### So how does this work?

In rust, we declare that we expect a raw pointer defined as a `c_char` type. We use CStr to access that pointer, and convert it to a std::String. Finally, we use CString to convert the std::String back into a `c_char` pointer and return that back to Web Assembly. emscripten does the work (within `cwrap`) to capture the string from memory, and return it to the JS runtime (and ultimately `console.log` it).

#### How does Web Assembly know how to access `fix_story` ?

In the .cargo/config file we define a set of exported functions to the compiler via `EXPORT_FUNCTIONS`. *Note:* You must prepend the exported function with an underscore.

## Examples

I've included several examples under the `examples` directory. Just `cd` into one, and run `make` to build the example.

*Note:* You will need a server to host the released files. I personally use `serve` which can be found over at https://www.npmjs.com/package/serve.

## Todo

[x] Create string -> String example
[x] Create number -> i32 example
[ ] Create array -> vec example
[ ] Create object -> struct example _possible?_

rust-webassembly

rust-webassembly Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

rust-webassembly

rust-webassembly Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README