about summary refs log tree commit diff
path: root/web/bubblegum/examples
diff options
context:
space:
mode:
authorsterni <sternenseemann@systemli.org>2021-02-20T17·02+0100
committersterni <sternenseemann@systemli.org>2021-04-01T18·50+0000
commit68f3ac64c4a2ae50dcb125f067692536f647e370 (patch)
treebd301237e8b9b7a6a78de24fb09c2cb0b4c416b9 /web/bubblegum/examples
parent7907319a11c659c3f5f7d68a3c221083892fd4fb (diff)
feat(sterni/nint): shebang interpreter for nix scripts r/2393
nint (short for nix interpreter) is a tiny wrapper around nix-instantiate
which allows to run nix scripts, i. e. nix expressions that conform to
a certain calling convention. A nix script runnable using nint must
conform to the following constraints:

* It must evaluate to a function which has a set pattern with an
  ellipsis as the single argument.

* It must produce a string as a return value or fail.

When invoked, a the expression receives the following arguments:

* `currentDir`: the current working directory as a nix path

* `argv`: a list of strings containing `argv` including `argv[0]`

* extra arguments which are manually specified which allows for
  passing along dependencies or libraries, for example:

    nint --arg depot '(import /depot {})' my-prog.nix [ argv[1] … ]

  would pass along depot to be used in `my-prog.nix`.

Such nix scripts are purely functional in a sense: The way inputs can be
taken is very limited and causing effects is also only possible in a
very limited sense (using builtins.fetchurl if TARBALL_TTL is 0,
adding files and directories to the nix store, realising derivations).
As an approximation, a program executed using nint can be thought of
as a function with the following signature:

  λ :: environment → working directory → argv → stdout

where environment includes:

* the time at the start of the program (`builtins.currentTime`)
* other information about the machine (`builtins.currentSystem` …)
* environment variables (`builtins.getEnv`)
* the file system (`builtins.readDir`, `builtins.readFile`, …) which
  is the biggest input impurity as it may change during evaluation

Additionally import from derivation and builtin fetchers are available
which introduce further impurities to be utilized.

Future work:

* Streaming I/O via lazy lists. This would allow usage of
  stdin and output before the program terminates. However this would
  require using libexpr directly or writing a custom nix interpreter.

  A description of how this would work can be found on the website of the
  esoteric programming language Lazy K: https://tromp.github.io/cl/lazy-k.html

* An effect system beyond stdin / stdout.

* Better error handling, support setting exit codes etc.

These features would require either using an alternative or custom
interpreter for nix (tvix or hnix) or to link against libexpr directly
to have more control over evaluation.

Change-Id: I61528516eb418740df355852f23425acc4d0656a
Reviewed-on: https://cl.tvl.fyi/c/depot/+/2745
Reviewed-by: sterni <sternenseemann@systemli.org>
Tested-by: BuildkiteCI
Diffstat (limited to 'web/bubblegum/examples')
0 files changed, 0 insertions, 0 deletions