Awesome
<div align="center"> <a href="https://github.com/rust-lang/rust"> <img width="200" height="200" alt="binaryen logo" src="https://www.rust-lang.org/logos/rust-logo-blk.svg"> </a> <a href="https://github.com/rollup/rollup"> <img width="200" height="200" alt="webpack logo" src="https://rollupjs.org/logo.svg"> </a> </div> <!-- [![stencil][stencil]][stencil-url] -->rollup-plugin-rust
<sup><sup>tl;dr -- see examples</sup></sup>
This is a rollup plugin that loads Rust code so it can be interop with Javascript base project. Currently, the Rust code will be compiled as:
- WebAssembly module/instance
- Node.js addon/ffi
Requirements
<ul> <li>Node v8 or later</li> <li>Rollup v0.64 or later</li> <li><details> <summary>Rust v1.28.0 with wasm32-uknown-unknown installed</summary>rustup default 1.28.0
rustup target add wasm32-unknown-unknown
</details></li>
</ul>
This module requires a minimum of Node v8.9.0, Rollup v0.64.0, and Rust in [nightly channel][].
Getting Started
To begin, you'll need to install rollup-plugin-rust
:
npm install rollup-plugin-rust --save-dev
Then add the plugin to your rollup
config. For example:
<b>rollup.config.js</b>
import rust from "rollup-plugin-rust";
export default [
{
input: "src/main.js",
output: {
file: "dist.index.js",
format: "esm"
},
plugins: [rust()]
}
];
<details>
<summary>quick usage</summary>
<b>lib.rs</b>
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
<b>index.js</b>
import wasm from "lib.rs";
export async function increment(a) {
const { instance } = await wasm;
return instance.exports.add(1, a);
}
</details>
And run rollup
via your preferred method.
Options
<details> <summary><b><code>export</code></b></summary>How wasm code would be exported. This options is identical with option export
in webassembly-loader. (see examples)
// in your rollup.config.js
{
plugins: [rust({ export: "instance" })];
}
</details>
<details>
<summary><b><code>target</code></b></summary>
- Type:
String
- Default:
wasm32-unknown-unknown
- Expected value: see supported platform
The Rust target to use. Currently it only support wasm related target
// in your rollup.config.js
{
plugins: [rust({ target: "wasm32-unknown-emscripten" })];
}
</details>
<details>
<summary><b><code>release</code></b></summary>
- Type:
Boolean
- Default:
true
Whether to compile the Rust code in debug or release mode.
// in your rollup.config.js
{
plugins: [rust({ release: false })]; // preserve debug symbol
}
</details>
<details>
<summary><b><code>include</code></b></summary>
- Type:
Array<string>
orstring
- Default:
['**/*.rs']
A single file, or array of files, to include when compiling.
// in your rollup.config.js
{
plugins: [
rust({
include: ["src/**/*.rs", "test/**/*.rs"]
})
];
}
</details>
<details>
<summary><b><code>exclude</code></b></summary>
- Type:
Array<string>
orstring
- Default:
['node_modules/**', 'target/**']
A single file, or array of files, to exclude when linting.
// in your rollup.config.js
{
plugins: [
rust({
exclude: ["**/node_modules/**", "**/target/**", "**/__caches__/**"]
})
];
}
</details>
Examples
See the test cases and example projects in fixtures and examples for more insight.
<details> <summary>TL;DR</summary>Given this Rust code
<b>lib.rs</b>
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
<b>Cargo.toml</b>
[package]
name = "adder"
version = "0.1.0"
authors = ["Full Name <email@site.domain>"]
[lib]
crate-type = ["cdylib"]
path = "lib.rs"
With options
{export: 'buffer'}
import wasmCode from "./lib.rs";
WebAssembly.compile(wasmCode).then(module => {
const instance = new WebAssembly.Instance(module);
console(instance.exports.add(1, 2)); // 3
});
{export: 'module'}
import wasmModule from "./lib.rs";
const instance = new WebAssembly.Instance(wasmModule);
console(instance.exports.add(1, 2)); // 3
{export: 'instance'}
import wasm from "./lib.rs";
console(wasm.exports.add(1, 2)); // 3
{export: 'async'}
extern {
fn hook(c: i32);
}
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
hook(a + b)
}
import wasmInstantiate from "./lib.rs";
wasmInstantiate(importObject | undefined).then(({ instance, module }) => {
console(instance.exports.add(1, 2)); // 3
// create different instance, extra will be called in different environment
const differentInstance = new WebAssembly.Instance(module, {
env: {
hook: result => result * 2
}
});
console(differentInstance.exports.add(1, 2)); // 6
});
{export: 'async-instance'}
import wasmInstantiate from "./lib.rs";
wasmInstantiate(importObject | undefined).then(instance => {
console(instance.exports.add(1, 2)); // 3
});
{export: 'async-module'}
import wasmInstantiate from "./lib.rs";
wasmCompile(importObject | undefined).then(module => {
const differentInstance = new WebAssembly.Instance(module);
console(differentInstance.exports.add(1, 2)); // 3
});
</details>
You may also want to look at
Who use this?
- example-stencil-rust
- [add yours 😉]
Contributing
- CONTRIBUTING.md for how you can make contribution
- HACKING.md for technical details