A simple helper that makes it easy to package Nu scripts with Nix, including inline dependency declarations for external commands and other packaged scripts.
flake
nu
nushell
nix
readme overhaul
+20
-6
+20
-6
README.md
+20
-6
README.md
···
3
3
nu2nix is a simple helper that makes it easy to package [Nu scripts](https://www.nushell.sh/book/scripts.html) with Nix, including inline dependency declarations for external commands and other packaged scripts.
4
4
Inspired by Python's [Inline Script Metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/) ([PEP 723](https://peps.python.org/pep-0723/)).
5
5
6
+
## Why uv2nix?
7
+
8
+
Nu scripts are great for small utilities and automation tasks, but packaging them with Nix means maintaining a separate Nix expression that actually builds your script into a runnable Nix package. Your dependency information ends up living in that Nix expression instead of with your script. This also ends up making it more difficult to, say, package a directory of scripts using `builtins.readDir` and some mapping magic, which is the original use case I created nu2nix for.
9
+
10
+
nu2nix fixes these problems by keeping your dependency information stored inside your Nu scripts themselves. Just point nu2nix at a script file and give it a package set. It'll scan your script for an `External Dependencies` block comment and parse it, then the resulting package will have all of the dependencies you declared in your block comment in `$PATH`. nixpkgs (`pkgs`), flake inputs (`inputs`), and a flake's `self` argument are all supported as dependency sources.
11
+
6
12
## Try it Out
7
13
8
14
The [`example` directory](./example) contains an example of how to use nu2nix. You can also run this example directly, like so:
···
43
49
44
50
## External Dependencies
45
51
46
-
nu2nix supports a custom format for declaring external dependencies inline in your script files.
52
+
nu2nix supports a custom format for declaring external dependencies inline in your script files.
53
+
All declared dependencies are automatically added to the script's `$PATH` when executed, using a wrapper script.
54
+
55
+
> ![NOTE]
56
+
> Only dependencies you declare in the `External Dependencies` comment or the `extraDependencies` argument to `mkNuScript` will be included in the script's `$PATH` wrapper. `$PATH` is completely overridden, not appended to. This helps with reproducibility; if an external command isn't explicitly included in the wrapper, Nushell won't be able to find it at runtime. The only exception to this is Nushell itself, as Nushell is implicitly added to the script's `$PATH` wrapper by `mkNuScript`.
47
57
48
58
```nu
49
59
#!/usr/bin/env nu
···
54
64
# inputs.niks3.niks3
55
65
# self.some-helper
56
66
# END: External Dependencies
67
+
68
+
^git --version
69
+
^nix --version
57
70
```
58
71
59
-
Dependencies beginning with `inputs` are resolved from the `inputs` argument passed to `mkNuScript`. For example, `inputs.niks3.niks3` is equivalent to`inputs.niks3.packages.${pkgs.stdenv.hostPlatform.system}.niks3`. The `system` and `packages` attribute are automatically inserted.
60
-
`self` works the same as `inputs`, but refers to the consuming flake. So, if you have a package you want to reuse in your Nu scripts that you declare in your flake, you can use this to refer to it.
61
-
Do note that using `inputs`/`self` in a Nu script's external dependencies block will result in an error if you don't pass `inputs`/`self` to `mkNuScript`.
62
-
Unqualified entries, such as `git` and `nix` in the example above, are pulled from the package set passed to `mkNuScript`. This will usually be nixpkgs.
72
+
### Dependency Formats
63
73
64
-
All declared dependencies are automatically added to the script's `$PATH` when executed, using a wrapper script.
74
+
| Scope | Usage Example | Resolves to | `mkNuScript` Argument |
75
+
| :---------------: | :----------------------: | :-----------------------------------------: | :------------------------------------------------: |
76
+
| _`<unqualified>`_ | `git` | `pkgs.git` | `pkgs` (raises error when missing) |
77
+
| `inputs` | `inputs.vicinae.default` | `inputs.vicinae.packages.${system}.default` | `inputs` (raises error when missing & referenced ) |
78
+
| `self` | `self.helper-script` | `self.packages.${system}.helper-script` | `self` (raises error when missing & referenced ) |