From 3134ed6fc279af29f178b00d5965cf67cd9d8345 Mon Sep 17 00:00:00 2001 From: riceicetea <104317939+riceicetea@users.noreply.github.com> Date: Sun, 11 Dec 2022 17:48:06 +0100 Subject: [PATCH] add documentation Co-authored-by: Max Petts Signed-off-by: gilice <104317939+gilice@users.noreply.github.com> --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..cc8da02 --- /dev/null +++ b/README.md @@ -0,0 +1,45 @@ +# lapce-volt + +This repository serves as a starting point for writing [Lapce](https://lapce.dev/) plugins in the [Rust Programming Language](https://www.rust-lang.org). +If you haven't used Rust before, consider familiarizing yourself with the [documentation](https://doc.rust-lang.org/book/) . + +## Getting started + +- If not yet done, [install Rust](https://www.rust-lang.org/learn/get-started) +- This template uses [cargo-make](https://github.com/sagiegurari/cargo-make) as a build system. Install it using `cargo install --force cargo-make`. +- Generate your own repository based on this one by following the instructions [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template). +- [Clone it](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) locally +- Ensure the wasi target is installed, using: `rustup target add wasm32-wasi` +- Compile your addon by executing `cargo make dev` in the cloned directory. This will create a `bin/lapce-plugin-template.wasm` file. +- Edit the extension's metadata in the `volt.toml` file. + - Check the `activation` block. Here, you can configure when Lapce will load your plugin. The two corresponding settings, `language` and `workspace-contains` accept an array of RegExps. + - Although this is **not recommended because of performance concerns**, to always load your extension, you can use `*` + - Edit the `wasm` property to reflect the (relative) path of the built plugin. +- Edit the `Cargo.toml` name property to match the `volt.toml` name property. +- Lapce loads extensions that are placed inside its plugins folder. + - If your filesystem supports symbolic links, symlink the plugin directory to `~/.local/share/lapce-stable/`, or `/Users/[USERNAME]/Library/Application Support/dev.lapce.Lapce-Stable/plugins` for Mac. + - If it doesn't, + - Make a folder in the plugins directory in the format of `author.plugin-name`, so for example `~/.local/share/lapce-stable/plugins/bob.awesome-plugin` + - copy the forementioned `lapce-plugin-template.wasm` and the `volt.toml` files to this directory + - Open Lapce, or, if already open, run the `Reload Window` command and check if your plugin appears in the sidebar. + - If it does not, check that the relative path to the `.wasm` file is correct. + +## Development + +- The `src/main.rs` file provides plenty of comments to help you get started with writing your plugin. +- You can configure the user-facing settings of the plugin in the `config` header of the `volt.toml` file. + - The plugin has read and write access to it's own folder only. **DO NOT use this to persist data**, because it'll be deleted when Lapce updates your plugin. +- You can quickly reload your extension without restarting lapce by clicking the cog icon besides the plugin's version in the UI and selecting `Reload Plugin` +- To show user-facing notifications, use `PLUGIN_RPC.window_show_message()`. _You can't use `print!()` and `eprint!()` from plugins for logging._ +- The template includes [`anyhow`](https://github.com/dtolnay/anyhow) for pragmatic, flexible error handling. + +## Publishing your plugin + +- Before publishing, check that all information is correct in `volt.toml`. +- If there is one, Lapce will show the `README.md` file as the plugin's description. You might want to write one to help with discoverability. +- Register an account for [Lapce's extension directory](https://plugins.lapce.dev) +- Install the `volts` tool, used for publishing extensions with `cargo install volts` + - Create an api token on the website. + - Build your plugin, and navigate to the directory of it (in the `plugins` directory, from where it's loaded) + - Execute `volts publish`. Paste the token, that you've just created, in. + - In a few minutes, your plugin should be up.