Skip to content

tessi/wasmex

main
Switch branches/tags
Code

Latest commit

Bumps [typetag](https://github.com/dtolnay/typetag) from 0.2.2 to 0.2.3.
- [Release notes](https://github.com/dtolnay/typetag/releases)
- [Commits](dtolnay/typetag@0.2.2...0.2.3)

---
updated-dependencies:
- dependency-name: typetag
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
d21c8df

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Wasmex logo

License CI

Wasmex is a fast and secure WebAssembly and WASI runtime for Elixir. It enables lightweight WebAssembly containers to be run in your Elixir backend.

It uses wasmer to execute WASM binaries through a NIF. We use Rust to implement the NIF to make it as safe as possible.

Install

The package can be installed by adding wasmex to your list of dependencies in mix.exs:

def deps do
  [
    {:wasmex, "~> 0.7.1"}
  ]
end

The docs can be found at https://hexdocs.pm/wasmex.

Example

There is a toy WASM program in test/wasm_test/src/lib.rs, written in Rust (but could potentially be any other language that compiles to WebAssembly). It defines many functions we use for end-to-end testing, but also serves as example code. For example:

#[no_mangle]
pub extern fn sum(x: i32, y: i32) -> i32 {
    x + y
}

Once this program compiled to WebAssembly (which we do every time when running tests), we end up with a wasmex_test.wasm binary file.

This WASM file can be executed in Elixir:

{:ok, bytes } = File.read("wasmex_test.wasm")
{:ok, module} = Wasmex.Module.compile(bytes)
{:ok, instance } = Wasmex.start_link(%{module: module}) # starts a GenServer running this WASM instance

{:ok, [42]} == Wasmex.call_function(instance, "sum", [50, -8])

Documentation

Please visit the Wasmex documentation for further info. If a topic is not covered (in the needed depth) there, please open an issue.

What is WebAssembly?

Quoting the WebAssembly site:

WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable target for compilation of high-level languages like C/C++/Rust, enabling deployment on the web for client and server applications.

About speed:

WebAssembly aims to execute at native speed by taking advantage of common hardware capabilities available on a wide range of platforms.

About safety:

WebAssembly describes a memory-safe, sandboxed execution environment […].

Development

To set up a development environment install the latest stable rust and rust-related tooling:

rustup component add rustfmt
rustup component add clippy
rustup target add wasm32-unknown-unknown # to compile our example WASM files for testing
rustup target add wasm32-wasi # to compile our example WASM/WASI files for testing

Then install the erlang/elixir dependencies:

asdf install # assuming you install elixir, erlang with asdf. if not, make sure to install them your way
mix deps.get

If you plan to change something on the Rust part of this project, set the following ENV WASMEX_BUILD=true so that your changes will be picked up.

I´m looking forward to your contributions. Please open a PR containing the motivation of your change. If it is a bigger change or refactoring, consider creating an issue first. We can discuss changes there first which might safe us time down the road :)

Any changes should be covered by tests, they can be run with mix test. In addition to tests, we expect the formatters and linters (cargo fmt, cargo clippy, mix format, mix dialyzer, mix credo) to pass.

Your contributions will be licenced under the same license as this project.

License

The entire project is under the MIT License. Please read theLICENSE file.