Update docs

This commit is contained in:
Isaac Clayton 2022-07-14 13:46:41 +02:00
parent 80b45ef93b
commit af1ad474e3
2 changed files with 24 additions and 8 deletions

View File

@ -152,7 +152,7 @@ Plugins in the `plugins` directory are automatically recompiled and serialized t
- `plugin.wasm` is the plugin compiled to Wasm. As a baseline, this should be about 4MB for debug builds and 2MB for release builds, but it depends on the specific plugin being built.
- `plugin.wasm.pre` is the plugin compiled to Wasm *and additionally* precompiled to host-platform-agnostic cranelift-specific IR. This should be about 700KB for debug builds and 500KB in release builds. Each plugin takes about 1 or 2 seconds to compile to native code using cranelift, so precompiling plugins drastically reduces the startup time required to begin to run a plugin.
- `plugin.wasm.the-target-triple` is the plugin compiled to Wasm *and additionally* precompiled to host-platform-specific native code, determined by the `TARGET` cargo exposes at compile-time. This should be about 700KB for debug builds and 500KB in release builds. Each plugin takes about 1 or 2 seconds to compile to native code using cranelift, so precompiling plugins drastically reduces the startup time required to begin to run a plugin.
For all intents and purposes, it is *highly recommended* that you use precompiled plugins where possible, as they are much more lightweight and take much less time to instantiate.
@ -246,18 +246,36 @@ Once all imports are marked, we can instantiate the plugin. To instantiate the p
```rust
let plugin = builder
.init(
true,
include_bytes!("../../../plugins/bin/cool_plugin.wasm.pre"),
PluginBinary::Precompiled(bytes),
)
.await
.unwrap();
```
The `.init` method currently takes two arguments:
The `.init` method takes a single argument containing the plugin binary.
1. First, the 'precompiled' flag, indicating whether the plugin is *normal* (`.wasm`) or precompiled (`.wasm.pre`). When using a precompiled plugin, set this flag to `true`.
1. If not precompiled, use `PluginBinary::Wasm(bytes)`. This supports both the WebAssembly Textual format (`.wat`) and the WebAssembly Binary format (`.wasm`).
2. Second, the raw plugin Wasm itself, as an array of bytes. When not precompiled, this can be either the Wasm binary format (`.wasm`) or the Wasm textual format (`.wat`). When precompiled, this must be the precompiled plugin (`.wasm.pre`).
2. If precompiled, use `PluginBinary::Precompiled(bytes)`. This supports precompiled plugins ending in `.wasm.the-target-triple`. You need to be extra-careful when using precompiled plugins to ensure that the plugin target matches the target of the binary you are compiling:
a. To tell the current crate what the current `target` triple is, add the following line to the crate's `build.rs`:
```rust
println!(
"cargo:rustc-env=TARGET_TRIPLE={}",
std::env::var("TARGET").unwrap()
);
```
b. To get the correct precompiled binary in the crate itself, read this exposed environment variable and include the plugin:
```rust
let bytes = include_bytes!(concat!(
"../../../plugins/bin/plugin.wasm.",
env!("TARGET_TRIPLE"),
));
let precompiled = PluginBinary::Precompiled(bytes);
```
The `.init` method is asynchronous, and must be `.await`ed upon. If the plugin is malformed or doesn't import the right functions, an error will be raised.

View File

@ -28,9 +28,7 @@ fn main() {
};
// Get the target architecture for pre-cross-compilation of plugins
// and write it to disk to be used when embedding plugins
let target_triple = std::env::var("TARGET").unwrap().to_string();
println!("cargo:rerun-if-env-changed=TARGET");
// Invoke cargo to build the plugins
let build_successful = std::process::Command::new("cargo")