From af1ad474e3a9cb9e9e6feddb446e19b556f732f7 Mon Sep 17 00:00:00 2001 From: Isaac Clayton Date: Thu, 14 Jul 2022 13:46:41 +0200 Subject: [PATCH] Update docs --- crates/plugin_runtime/README.md | 34 +++++++++++++++++++++++++-------- crates/plugin_runtime/build.rs | 2 -- 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/crates/plugin_runtime/README.md b/crates/plugin_runtime/README.md index 8ac843cb02f0491dbdc09250e51734440abe561a..012f1563625135f5ca088f4e0272b0cb6820f65d 100644 --- a/crates/plugin_runtime/README.md +++ b/crates/plugin_runtime/README.md @@ -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: - -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`. - -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`). +The `.init` method takes a single argument containing the plugin binary. + +1. If not precompiled, use `PluginBinary::Wasm(bytes)`. This supports both the WebAssembly Textual format (`.wat`) and the WebAssembly Binary format (`.wasm`). + +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. diff --git a/crates/plugin_runtime/build.rs b/crates/plugin_runtime/build.rs index 49c3f89a808b0db003f8f0522e2e4b1b2985d6de..dbfdebf9a88bcced99daa1d3373b872e2c6623ad 100644 --- a/crates/plugin_runtime/build.rs +++ b/crates/plugin_runtime/build.rs @@ -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")