<p align="center">
  <img width="300" src="./logo.svg" alt="Wasmex logo">
<p align="center">
  <a href="">
    <img src="" alt="License">
  <a href="">
    <img src="" alt="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 [wasmtime]( to execute WASM binaries through a [Rust]( NIF.

Documentation can be found at [](

## Install

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

def deps do
    {:wasmex, "~> 0.8.2"}

## Example

There is a toy WASM program in `test/wasm_test/src/`, 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:

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:

bytes =!("wasmex_test.wasm")
{:ok, pid} = Wasmex.start_link(%{bytes: bytes}) # starts a GenServer running a WASM instance
{:ok, [42]} == Wasmex.call_function(pid, "sum", [50, -8])

## 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]( […].

Using WebAssembly on an Elixir host is great not only, but especially for the following use cases:

* Running user-provided code safely
* Share business logic between systems written in different programming languages. E.g. a JS frontend and Elixir backend
* Run existing libraries/programs and easily interface them from Elixir

## 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.

### Release

To release this package, make sure CI is green, increase the package version, and:

git tag -a v0.8.0 # change version accordingly, copy changelog into tag message
git push --tags
mix Wasmex.Native --all --ignore-unavailable --print

Inspect it's output carefully, but ignore NIF version `2.14` and `arm-unknown-linux-gnueabihf` arch errors because we don't build for them.
Now inspect the checksum-Elixir.Wasmex.Native.exs file - it should include all prebuilt binaries in their checksums

Then continue with

mix hex.publish

## License

The entire project is under the MIT License. Please read [the`LICENSE` file](

### Licensing

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, shall be licensed as above, without any
additional terms or conditions.