From 5b64e52f508c9a568d2158fcd0eda3d2ea1c50d6 Mon Sep 17 00:00:00 2001 From: Devyn Cairns Date: Sun, 21 Apr 2024 23:40:34 -0700 Subject: [PATCH 1/2] Documentation for the plugin.msgpackz overhaul --- book/plugins.md | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/book/plugins.md b/book/plugins.md index 9aa24f0c7d..edb8661e55 100644 --- a/book/plugins.md +++ b/book/plugins.md @@ -32,36 +32,31 @@ If you chose to download the git repository instead, run this when inside the cl > cargo install --path . ``` -This will create a binary file that can be used to register the plugin. +This will create a binary file that can be used to add the plugin. Keep in mind that when installing using crates.io, the binary can be saved in different locations depending on how your system is set up. A typical location is in the users's home directory under .cargo/bin. -## Registering a plugin +## Adding a plugin -To enable an installed plugin, call the [`register`](/commands/docs/register.md) command to tell Nu where to find it. As you do, you'll need to also tell Nushell what encoding the plugin uses. +To add a plugin to the plugin cache file, call the [`plugin add`](/commands/docs/plugin_add.md) command to tell Nu where to find it. Please note that the plugin name needs to start with `nu_plugin_`, Nu uses the name prefix to detect plugins. Linux+macOS: ```nu -> register ./my_plugins/nu_plugin_cool +> plugin add ./my_plugins/nu_plugin_cool ``` Windows: ```nu -> register .\my_plugins\nu_plugin_cool.exe +> plugin add .\my_plugins\nu_plugin_cool.exe ``` -When [`register`](/commands/docs/register.md) is called: +When [`plugin add`](/commands/docs/plugin_add.md) is called, Nu runs the plugin binary and communicates via the [plugin protocol](plugin_protocol_reference.md) to get the signatures of all of the commands the plugin supports. It then saves information about the plugin, including the command signatures, to the plugin cache file at `$nu.plugin-path` in a custom brotli-compressed MessagePack format. This caching step saves `nu` from having to run all plugins during startup, which could be very slow. -1. Nu launches the plugin, and waits for the plugin to tell Nu which communication encoding it should use -2. Nu sends it a "Signature" message over stdin -3. The plugin responds via stdout with a message containing its signature (name, description, arguments, flags, and more) -4. Nu saves the plugin signature in the file at `$nu.plugin-path`, so registration is persisted across multiple launches - -Once registered, the plugin is available as part of your set of commands: +Once added, the next time `nu` is started, the plugin's commands are available as part of your set of commands: ```nu > help commands | where command_type == "plugin" @@ -69,7 +64,7 @@ Once registered, the plugin is available as part of your set of commands: ### Updating a plugin -When updating a plugin, it is important to run `register` again just as above to load the new signatures from the plugin and allow Nu to rewrite them to the plugin file (`$nu.plugin-path`). +When updating a plugin, it is important to run `plugin add` again just as above to load the new signatures from the plugin and allow Nu to rewrite them to the plugin file (`$nu.plugin-path`). ## Managing plugins From d777ba02f3af4728af443447c3e821cae008038f Mon Sep 17 00:00:00 2001 From: Devyn Cairns Date: Mon, 22 Apr 2024 19:19:44 -0700 Subject: [PATCH 2/2] find more `register` cases --- book/cheat_sheet.md | 4 ++-- book/plugins.md | 8 +++++++- book/variables_and_subexpressions.md | 4 ++-- contributor-book/plugins.md | 7 ++++--- 4 files changed, 15 insertions(+), 8 deletions(-) diff --git a/book/cheat_sheet.md b/book/cheat_sheet.md index eefe66f54f..67c1b34e00 100644 --- a/book/cheat_sheet.md +++ b/book/cheat_sheet.md @@ -456,8 +456,8 @@ > This expression results in error.** ```nu - > const plugin = 'path/­to/­plugin' - > register $plugin + > const file = 'path/­to/­file.nu' + > source $file ``` > **a constant variable is immutable value which is fully evaluated at parse-time** diff --git a/book/plugins.md b/book/plugins.md index edb8661e55..830f82277d 100644 --- a/book/plugins.md +++ b/book/plugins.md @@ -139,7 +139,13 @@ For more information on exactly under what circumstances a plugin is considered ## Removing a plugin -To remove a plugin, edit the `$nu.plugin-path` file and remove all of the `register` commands referencing the plugin you want to remove, including the signature argument. +To remove a plugin, call `plugin rm` with the name of the plugin you want to remove. For example, if you previously added the plugin `~/.cargo/bin/nu_plugin_gstat`, its name would be `gstat`. To remove it: + +```nushell +plugin rm gstat +``` + +You can check the name of a plugin by running `plugin list`. ## Examples diff --git a/book/variables_and_subexpressions.md b/book/variables_and_subexpressions.md index 18bc21eaf3..76b8310d2e 100644 --- a/book/variables_and_subexpressions.md +++ b/book/variables_and_subexpressions.md @@ -76,8 +76,8 @@ To use mutable variables for such behaviour, you are encouraged to use the loops A constant variable is an immutable variable that can be fully evaluated at parse-time. These are useful with commands that need to know the value of an argument at parse time, like [`source`](/commands/docs/source.md), [`use`](/commands/docs/use.md) and [`register`](/commands/docs/register.md). See [how nushell code gets run](how_nushell_code_gets_run.md) for a deeper explanation. They are declared using the `const` keyword ```nu -const plugin = 'path/to/plugin' -register $plugin +const file = 'path/to/file.nu' +source $file ``` ### Variable Names diff --git a/contributor-book/plugins.md b/contributor-book/plugins.md index b0ea21d1c1..7d2f84da61 100644 --- a/contributor-book/plugins.md +++ b/contributor-book/plugins.md @@ -16,7 +16,7 @@ For more detailed information about how exactly this communication works, especi ## Discovery -Nu keeps a registry of plugins at the file system location defined by configuration variable `$nu.plugin-path`. To register a plugin, execute `register ` in a Nu shell. +Nu keeps a registry of plugins known as the ‘plugin cache file’ at the file system location defined by configuration variable `$nu.plugin-path`. To add a plugin, execute `plugin add ` in a Nu shell. ## Launch environment @@ -243,11 +243,12 @@ Once we have finished our plugin, to use it all we need to do is install it. ```sh > cargo install --path . +> plugin add ~/.cargo/bin/nu_plugin_len # add .exe on Windows ``` -Once `nu` starts up, it will discover the plugin and register it as a command. +Once `nu` starts up, it will discover the plugin and add its commands to the scope. -If you're already running `nu` during the installation process of your plugin, ensure you restart `nu` so that it can load and register your plugin or register it manually with `register ./target/release/nu_plugin_len`. +If you're already running `nu` during the installation process of your plugin, ensure you restart `nu` so that it can load your plugin. ``` > nu