https://github.com/fricklerhandwerk/attr-cmd
Build shell commands from Nix attribute sets.
https://github.com/fricklerhandwerk/attr-cmd
nix nix-shell
Last synced: over 1 year ago
JSON representation
Build shell commands from Nix attribute sets.
- Host: GitHub
- URL: https://github.com/fricklerhandwerk/attr-cmd
- Owner: fricklerhandwerk
- Created: 2024-02-10T00:40:24.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-23T01:47:04.000Z (about 2 years ago)
- Last Synced: 2024-10-12T00:24:02.748Z (over 1 year ago)
- Topics: nix, nix-shell
- Language: Nix
- Homepage:
- Size: 33.2 KB
- Stars: 14
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# `attr-cmd`
Build shell commands from Nix attribute sets.
## `lib.attr-cmd.exec`
exec :: AttrSet -> AttrSet
`exec` transforms a nested attribute set `` into a flat attribute set ``.
For each attribute `` of `` at the [attribute path](https://nix.dev/manual/nix/stable/language/operators.html#attribute-selection) ` . [...] . ` that evaluates to a [derivation](https://nix.dev/manual/nix/stable/language/derivations), it creates an attribute `` in ``.
All other attribute paths are ignored.
> **Example**
>
> ### Transformation of attributes
>
> ```nix
> { lib, attr-cmd }:
> let
> input = {
> a.b.c = drv;
> d.e.f = drv';
> g.h.i = "ignored";
> };
> output = attr-cmd.exec input;
> in
> {
> inherit = output;
> executable = lib.getExe output.a;
> }
> ```
>
> ```console
> { output = { a = drv''; d = drv'''; }; executable = "/nix/store/...-a/bin/a"}
> ```
>
Each attribute `` in `` is a derivation that produces an executable `/bin/`.
Such an executable `` accepts [command line words](https://www.gnu.org/software/bash/manual/bash.html#index-word) that correspond to attribute paths in `` starting from ``.
The final command line word `` executes the `meta.mainProgram` (or `/bin/`) from the derivation's `bin` (or `out`) [output](https://nix.dev/manual/nix/stable/language/derivations#attr-outputs) at the corresponding attribute `` from ``.
After adding the derivations from `` to the environment, run the executable `` by specifying its attribute path as command line arguments:
```console
... []...
```
Help will be shown for intermediate subcommands, displaying `meta.description` on a derivation or attribute set if available.
> **Example**
>
> ### Create a command from a derivation in an attribute set
>
> Declare a nested attribute set `foo` with a derivation `baz` as a leaf attribute, and pass that attribute set to `attr-cmd`:
>
> ```nix
> # ./default.nix
> {
> sources ? import ./npins,
> system ? builtins.currentSystem,
> pkgs ? import sources.nixpkgs { inherit system; config = { }; overlays = [ ]; },
> attr-cmd ? pkgs.callPackage "${sources.attr-cmd}/lib.nix" {};
> }:
> let
> lib = pkgs.lib // attr-cmd.lib
> lib
> rec {
> foo.bar.baz = pkgs.writeScriptBin "baz" "echo success $@";
> commands = lib.attr-cmd.exec { inherit foo; }; ;
> shell = pkgs.mkShellNoCC {
> packages = builtins.attrValues commands ++ [
> pkgs.npins
> ];
> };
> }
> ```
>
> The values of the resulting attribute set `commands` are now derivations that create executables:
>
> ```shell-session
> $ nix-shell -p npins --run "npins init"
> $ nix-shell
> [nix-shell:~]$ foo bar baz
> success
> [nix-shell:~]$ foo bar baz or else
> success or else
> ```
>