add a helper module to install Nushell dependencies

README.md

@@ -15,6 +15,7 @@ A fast *interactive explorer* tool for *structured data* inspired by [`nu-explor
     - [*an example*](#an-example)
     - [*some convenience*](#-some-convenience)
 - [*see the documentation locally*](#see-the-documentation-locally)
+- [*troubleshooting*](#troubleshooting)
 - [*contributing*](#contributing)
 - [*TODO*](#todo)
     - [*features*](#features)
@@ -41,6 +42,13 @@ will come very handy in a day-to-day basis for me at least :)
 so here we are... LET'S GO :muscle:
 
 # installation
+> **Important**
+> if you are using bleeding-edge versions of Nushell, please make sure the
+> Nushell dependencies are the same as your Nushell install by running
+> ```nushell
+> use scripts/deps.nu; deps --current
+> ```
+
 ## using `nupm install` (recommended)
 - download [nushell/nupm](https://github.com/nushell/nupm)
 - load the `nupm` module
@@ -110,6 +118,20 @@ and voila :yum:
 cargo doc --document-private-items --no-deps --open
 ```
 
+# troubleshooting
+in case you get some weird error or behaviour, before filing any issue, the
+easiest is to make sure the plugin is compiled with the same revision as the
+Nushell you are using!
+```nushell
+use scripts/deps.nu; deps --current
+```
+and then you can come back to the [*installation*](#installation) section.
+
+> **Note**
+> of course, this will not work if the version of Nushell you are using is too
+> old, because then the state of `nu_plugin_explore` will be too recent for
+> everything to compile properly...
+
 # contributing
 in order to help, you can have a look at
 - the [todo](#todo) list down below, there might be unticked tasks to tackle

scripts/deps.nu

@@ -0,0 +1,36 @@
+const NUSHELL_REMOTE = "https://github.com/nushell/nushell"
+const PKGS = [ "nuon", "nu-protocol", "nu-plugin" ]
+
+# setup Nushell dependencies
+#
+# > **Note**
+# > options are shown in inverse order of precedence
+export def main [
+    --rev: string, # a Nushell revision
+    --tag: string, # a Nushell tag
+    --current,     # use the current Nushell version
+] {
+    let opts = if $current {
+        if (version).commit_hash != null {
+            print $"using current revision of Nushell: (version | get commit_hash)"
+            [ --rev (version).commit_hash ]
+        } else {
+            print $"using current version of Nushell: (version | get version)"
+            [ --tag (version).version ]
+        }
+    } else {
+        if $tag != null {
+            print $"using user version: ($tag)"
+            [ --tag $tag ]
+        } else if $rev != null {
+            print $"using user revision: ($rev)"
+            [ --rev $rev ]
+        } else {
+            error make --unspanned { msg: "please give either `--rev` or `--tag`" }
+        }
+    }
+
+    for pkg in $PKGS {
+        cargo add $pkg --git $NUSHELL_REMOTE ...$opts
+    }
+}