mirror of
https://github.com/zed-industries/zed.git
synced 2024-11-13 06:39:31 +03:00
Merge pull request #1326 from zed-industries/plugin-docs
Write about how plugins work and how to use them
This commit is contained in:
Isaac Clayton
GitHub
commit
8bcfcce506
10
README.md
10
README.md
@ -42,6 +42,16 @@ script/zed_with_local_servers --release
|
||||
|
||||
If you trigger `cmd-alt-i`, Zed will copy a JSON representation of the current window contents to the clipboard. You can paste this in a tool like [DJSON](https://chrome.google.com/webstore/detail/djson-json-viewer-formatt/chaeijjekipecdajnijdldjjipaegdjc?hl=en) to navigate the state of on-screen elements in a structured way.
|
||||
|
||||
### Wasm Plugins
|
||||
|
||||
Zed has a Wasm-based plugin runtime which it currently uses to embed plugins. To compile Zed, you'll need to have the `wasm32-wasi` toolchain installed on your system. To install this toolchain, run:
|
||||
|
||||
```bash
|
||||
rustup target add wasm32-wasi
|
||||
```
|
||||
|
||||
Plugins can be found in the `plugins` folder in the root. For more information about how plugins work, check the [Plugin Guide](./crates/plugin_runtime/README.md) in `crates/plugin_runtime/README.md`.
|
||||
|
||||
## Roadmap
|
||||
|
||||
We will organize our efforts around the following major milestones. We'll create tracking issues for each of these milestones to detail the individual tasks that comprise them.
|
||||
|
||||
@ -1,41 +1,124 @@
|
||||
# Zed's Plugin Runner
|
||||
Wasm plugins can be run through `wasmtime`, with supported for sandboxed system integration through WASI. There are three `plugin` crates that implement different things:
|
||||
This is a short guide that aims to answer the following questions:
|
||||
|
||||
1. `plugin_runtime` loads and runs compiled `Wasm` plugins, and handles setting up system bindings.
|
||||
- How do plugins work in Zed?
|
||||
- How can I create a new plugin?
|
||||
- How can I integrate plugins into a part of Zed?
|
||||
|
||||
2. `plugin` is the crate that Rust Wasm plugins should depend on. It re-exports some required crates (e.g. `serde`, `bincode`) and provides some necessary macros for generating bindings that `plugin_runtime` can hook into.
|
||||
### Nomenclature
|
||||
|
||||
3. `plugin_macros` implements the proc macros required by `plugin`, like the `#[bind]` attribute macro.
|
||||
- Host-side: The native Rust runtime managing plugins, e.g. Zed.
|
||||
- Guest-side: The wasm-based runtime that plugins use.
|
||||
|
||||
## ABI
|
||||
## How plugins work
|
||||
Zed's plugins are WebAssembly (Wasm) based, and have access to the WebAssembly System Interface (WASI), which allows for permissions-based access to subsets of system resources, like the filesystem.
|
||||
|
||||
To execute plugins, Zed's plugin system uses the sandboxed [`wasmtime`](https://wasmtime.dev/) runtime, which is Open Source and developed by the [Bytecode Alliance](https://bytecodealliance.org/). Wasmtime uses the [Cranelift](https://docs.rs/cranelift/latest/cranelift/) codegen library to compile plugins to native code.
|
||||
|
||||
Zed has three `plugin` crates that implement different things:
|
||||
|
||||
1. `plugin_runtime` is a host-side library that loads and runs compiled `Wasm` plugins, in addition to setting up system bindings. This crate should be used host-side
|
||||
|
||||
2. `plugin` contains a prelude for guest-side plugins to depend on. It re-exports some required crates (e.g. `serde`, `bincode`) and provides some necessary macros for generating bindings that `plugin_runtime` can hook into.
|
||||
|
||||
3. `plugin_macros` implements the proc macros required by `plugin`, like the `#[import]` and `#[export]` attribute macros, and should also be used guest-side.
|
||||
|
||||
### ABI
|
||||
The interface between the host Rust runtime ('Runtime') and plugins implemented in Wasm ('Plugin') is pretty simple.
|
||||
|
||||
`Buffer` is a pair of two 4-byte (`u32`) fields, encoded as a single `u64`.
|
||||
When calling a guest-side function, all arguments are serialized to bytes and passed through `Buffer`s. We currently use `serde` + [`bincode`](https://docs.rs/bincode/latest/bincode/) to do this serialization. This means that any type that can be serialized using serde can be passed across the ABI boundary. For types that represent resources that cannot pass the ABI boundary (e.g. `Rope`), we are working on an opaque callback-based system.
|
||||
|
||||
```
|
||||
All `Buffer`s are stored in Wasm linear memory (Wasm memory). A `Buffer` is a pointer, length pair to a byte array somewhere in Wasm memory. A `Buffer` itself is represented as a pair of two 4-byte (`u32`) fields:
|
||||
|
||||
```rust
|
||||
struct Buffer {
|
||||
ptr: u32,
|
||||
len: u32,
|
||||
}
|
||||
```
|
||||
|
||||
All functions that Plugin exports must have the following properties:
|
||||
Which we encode as a single `u64` when crossing the ABI boundary:
|
||||
|
||||
- Have the signature `fn(ptr: u64) -> u64`, where both the argument and return types are a `Buffer`:
|
||||
```
|
||||
+-------+-------+
|
||||
| ptr | len |
|
||||
+-------+-------+
|
||||
|
|
||||
~ ~ ~ ~ | ~ ~ ~ ~ spOoky ABI boundary O.o
|
||||
V
|
||||
+---------------+
|
||||
| u64 |
|
||||
+---------------+
|
||||
```
|
||||
|
||||
This means that all exported and imported functions essentially have the following signature:
|
||||
|
||||
All functions that a plugin exports or imports have the following properties:
|
||||
|
||||
- A function signature of `fn(u64) -> u64`, where both the argument (input) and return type (output) are a `Buffer`:
|
||||
|
||||
- The input `Buffer` will contain the input arguments serialized to `bincode`.
|
||||
- The output `Buffer` will contain the output arguments serialized to `bincode`.
|
||||
|
||||
- Have a name starting with two underscores.
|
||||
|
||||
Additionally, Plugin must export an:
|
||||
Luckily for us, we don't have to worry about mangling names or writing serialization code. The `plugin::prelude::*` defines a couple of macros—aptly named `#[import]` and `#[export]`—that generate all serialization code and perform all mangling of names requisite for crossing the ABI boundary.
|
||||
|
||||
There are also a couple important things every plugin must have:
|
||||
|
||||
- `__alloc_buffer` function that, given a `u32` length, returns a `u32` pointer to a buffer of that length.
|
||||
- `__free_buffer` function that, given a buffer encoded as a `u64`, frees the buffer at the given location, and does not return anything.
|
||||
|
||||
Note that all of these requirements are automatically fullfilled for any Rust Wasm plugin that uses the `plugin` crate, and imports the `prelude`.
|
||||
Luckily enough for us yet again, the `plugin` prelude defines two ready-made versions of these functions, so you don't have to worry about implementing them yourselves.
|
||||
|
||||
Here's an example Rust Wasm plugin that doubles the value of every float in a `Vec<f64>` passed into it:
|
||||
So, what does importing and exporting functions from a plugin look like in practice? I'm glad you asked...
|
||||
|
||||
## Creating new plugins
|
||||
Since Zed's plugin system uses Wasm + WASI, in theory any language that compiles to Wasm can be used to write plugins. In practice, and out of practicality, however, we currently only really support plugins written in Rust.
|
||||
|
||||
A plugin is just a rust crate like any other. All plugins embedded in Zed are located in the `plugins` folder in the root. These plugins will automatically be compiled, optimized, and recompiled on change, so it's recommended that when creating a new plugin you create it there.
|
||||
|
||||
As plugins are compiled to Wasm + WASI, you need to have the `wasm32-wasi` toolchain installed on your system. If you don't have it already, a little rustup magick will do the trick:
|
||||
|
||||
```bash
|
||||
rustup target add wasm32-wasi
|
||||
```
|
||||
|
||||
### Configuring a plugin
|
||||
After you've created a new plugin in `plugins` using `cargo new --lib`, edit your `Cargo.toml` to ensure that it looks something like this:
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "my_very_cool_incredible_plugin_with_a_short_name_of_course"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
plugin = { path = "../../crates/plugin" }
|
||||
|
||||
[profile.release]
|
||||
opt-level = "z"
|
||||
lto = true
|
||||
```
|
||||
|
||||
Here's a quick explainer of what we're doing:
|
||||
|
||||
- `crate-type = ["cdylib"]` is used because a plugin essentially acts a *library*, exposing functions with specific signatures that perform certain tasks. This key ensures that the library is generated in a reproducible manner with a layout `plugin_runtime` knows how to hook into.
|
||||
|
||||
- `plugin = { path = "../../crates/plugin" }` is used so we have access to the prelude, which has a few useful functions and can automatically generate serialization glue code for us.
|
||||
|
||||
- `[profile.release]` these options wholistically optimize for size, which will become increasibgly important as we add more plugins.
|
||||
|
||||
### Importing and Exporting functions
|
||||
To import or export a function, all you need are two things:
|
||||
|
||||
1. Make sure that you've imported `plugin::prelude::*`
|
||||
2. Annotate your function or signature with `#[export]` or `#[import]` respectively.
|
||||
|
||||
Here's an example plugin that doubles the value of every float in a `Vec<f64>` passed into it:
|
||||
|
||||
```rust
|
||||
use plugin::prelude::*;
|
||||
@ -51,8 +134,188 @@ All the serialization code is automatically generated by `#[export]`.
|
||||
You can specify functions that must be defined host-side by using the `#[import]` attribute. This attribute must be attached to a function signature:
|
||||
|
||||
```rust
|
||||
use plugin::prelude::*;
|
||||
|
||||
#[import]
|
||||
fn run(command: String) -> Vec<u8>;
|
||||
```
|
||||
|
||||
The `#[import]` macro will generate a function body that performs the proper serialization/deserialization needed to call out to the host rust runtime. Note that the same ABI is used for both `#[import]` and `#[export]`.
|
||||
The `#[import]` macro will generate a function body that performs the proper serialization/deserialization needed to call out to the host rust runtime. Note that the same `serde` + `bincode` + `Buffer` ABI is used for both `#[import]` and `#[export]`.
|
||||
|
||||
> **Note**: If you'd like to see an example of importing and exporting functions, check out the `test_plugin`, which can be found in the `plugins` directory.
|
||||
|
||||
## Integrating plugins into Zed
|
||||
Currently, plugins are used to add support for language servers to Zed. Plugins should be fairly simple to integrate for library-like applications. Here's a quick overview of how plugins work:
|
||||
|
||||
### Normal vs Precompiled plugins
|
||||
Plugins in the `plugins` directory are automatically recompiled and serialized to disk when compiling Zed. The resulting artifacts can be found in the `plugins/bin` directory. For each `plugin`, you should see two files:
|
||||
|
||||
- `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.
|
||||
|
||||
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.
|
||||
|
||||
### Instantiating a plugin
|
||||
So you have something you'd like to add a plugin for. What now? The general pattern for adding support for plugins is as follows:
|
||||
|
||||
#### 1. Create a struct to hold the plugin
|
||||
To call the functions that a plugin exports host-side, you need to have 'handles' to those functions. Each handle is typed and stored in `WasiFn<A, R>` where `A: Serialize` and `R: DeserializeOwned`.
|
||||
|
||||
For example, let's suppose we're creating a plugin that:
|
||||
|
||||
1. formats a message
|
||||
2. processes a list of numbers somehow
|
||||
|
||||
We could create a struct for this plugin as follows:
|
||||
|
||||
```rust
|
||||
use plugin_runtime::{WasiFn, Plugin};
|
||||
|
||||
pub struct CoolPlugin {
|
||||
format: WasiFn<String, String>,
|
||||
process: WasiFn<Vec<f64>, f64>,
|
||||
runtime: Plugin,
|
||||
}
|
||||
```
|
||||
|
||||
Note that this plugin also holds an owned reference to the runtime, which is stored in the `Plugin` type. In asynchronous or multithreaded contexts, it may be required to put `Plugin` behind an `Arc<Mutex<Plugin>>`. Although plugins expose an asynchronous interface, the underlying Wasm engine can only execute a single function at a time.
|
||||
|
||||
> **Note**: This is a limitation of the WebAssembly standard itself. In the future, to work around this, we've been considering starting a pool of plugins, or instantiating a new plugin per call (this isn't as bad as it sounds, as instantiating a new plugin only takes about 30µs).
|
||||
|
||||
In the following steps, we're going to build a plugin and extract handles to fill this struct we've created.
|
||||
|
||||
#### 2. Bind all imported functions
|
||||
While a plugin can export functions, it can also import them. We'll refer to the host-side functions that a plugin imports as 'native' functions. Native functions are represented using callbacks, and both synchronous and asynchronous callbacks are supported.
|
||||
|
||||
To bind imported functions, the first thing we need to do is create a new plugin using `PluginBuilder`. `PluginBuilder` uses the builder pattern to configure a new plugin, after which calling the `init` method will instantiate the `Plugin`.
|
||||
|
||||
You can create a new plugin builder as follows:
|
||||
|
||||
```rust
|
||||
let builder = PluginBuilder::new_with_default_ctx();
|
||||
```
|
||||
|
||||
This creates a plugin with a sensible default set of WASI permissions, namely the ability to write to `stdout` and `stderr` (note that, by default, plugins do not have access to `stdin`). For more control, you can use `PluginBuilder::new` and pass in a `WasiCtx` manually.
|
||||
|
||||
##### Synchronous Functions
|
||||
To add a sync native function to a plugin, use the `.host_function` method:
|
||||
|
||||
```rust
|
||||
let builder = builder.host_function(
|
||||
"add_f64",
|
||||
|(a, b): (f64, f64)| a + b,
|
||||
).unwrap();
|
||||
```
|
||||
|
||||
The `.host_function` method takes two arguments: the name of the function, and a sync callback that implements it. Note that this name must match the name of the function declared in the plugin exactly. For example, to use the `add_f64` from a plugin, you must include the following `#[import]` signature:
|
||||
|
||||
```rust
|
||||
use plugin::prelude::*;
|
||||
|
||||
#[import]
|
||||
fn add_f64(a: f64, b: f64) -> f64;
|
||||
```
|
||||
|
||||
Note that the specific names of the arguments do not matter, as long as they are unique. Once a function has been imported, it may be used in the plugin as any other Rust function.
|
||||
|
||||
##### Asynchronous Functions
|
||||
To add an async native function to a plugin, use the `.host_function_async` method:
|
||||
|
||||
```rust
|
||||
let builder = builder.host_function_async(
|
||||
"half",
|
||||
|n: f64| async move { n / 2.0 },
|
||||
).unwrap();
|
||||
```
|
||||
|
||||
This method works exactly the same as the `.host_function` method, but requires a callback that returns an async future. On the plugin side, there is no distinction made between sync and async functions (as Wasm has no built-in notion of sync vs. async), so the required import signature should *not* use the `async` keyword:
|
||||
|
||||
```rust
|
||||
use plugin::prelude::*;
|
||||
|
||||
#[import]
|
||||
fn half(n: f64) -> f64;
|
||||
```
|
||||
|
||||
All functions declared by the builder must be imported by the Wasm plugin, otherwise an error will be raised.
|
||||
|
||||
#### 3. Get the compiled plugin
|
||||
Once all imports are marked, we can instantiate the plugin. To instantiate the plugin, simply call the `.init` method on a `PluginBuilder`:
|
||||
|
||||
```rust
|
||||
let plugin = builder
|
||||
.init(
|
||||
true,
|
||||
include_bytes!("../../../plugins/bin/cool_plugin.wasm.pre"),
|
||||
)
|
||||
.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 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.
|
||||
|
||||
#### 4. Get handles to all exported functions
|
||||
Once the plugin has been compiled, it's time to start filling in the plugin struct defined earlier. In the case of `CoolPlugin` from earlier, this can be done as follows:
|
||||
|
||||
```rust
|
||||
let mut cool_plugin = CoolPlugin {
|
||||
format: plugin.function("format").unwrap(),
|
||||
process: plugin.function("process").unwrap(),
|
||||
runtime: plugin,
|
||||
};
|
||||
```
|
||||
|
||||
Because the struct definition defines the types of functions we're grabbing handles to, it's not required to specify the types of the functions here.
|
||||
|
||||
Note that, yet again, the names of guest-side functions we import must match exactly. Here's an example of what that implementation might look like:
|
||||
|
||||
```rust
|
||||
use plugin::prelude::*;
|
||||
|
||||
#[export]
|
||||
pub fn format(message: String) -> String {
|
||||
format!("Cool Plugin says... '{}!'", message)
|
||||
}
|
||||
|
||||
#[export]
|
||||
pub fn process(numbers: Vec<f64>) -> f64 {
|
||||
// Process by calculating the average
|
||||
let mut total = 0.0;
|
||||
for number in numbers.into_iter() {
|
||||
total += number;
|
||||
}
|
||||
total / numbers.len()
|
||||
}
|
||||
```
|
||||
|
||||
That's it! Now you have a struct that holds an instance of a plugin. The last thing you need to know is how to call out the plugin you've defined...
|
||||
|
||||
### Using a plugin
|
||||
To call a plugin function, use the async `.call` method on `Plugin`:
|
||||
|
||||
```rust
|
||||
let average = cool_plugin.runtime
|
||||
.call(
|
||||
&cool_plugin.process,
|
||||
vec![1.0, 2.0, 3.0],
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
```
|
||||
|
||||
The `.call` method takes two arguments:
|
||||
|
||||
1. A reference to the handle of the function we want to call.
|
||||
2. The input argument to this function.
|
||||
|
||||
This method is async, and must be `.await`ed. If something goes wrong (e.g. the plugin panics, or there is a type mismatch between the plugin and `WasiFn`), then this method will return an error.
|
||||
|
||||
## Last Notes
|
||||
This has been a brief overview of how the plugin system currently works in Zed. We hope to implement higher-level affordances as time goes on, to make writing plugins easier, and providing tooling so that users of Zed may also write plugins to extend their own editors.
|
||||
Loading…
Reference in New Issue
Block a user