* doc: improve documentation for trivial text writing functions
Co-authored-by: Brian Merchant <bzm3r@proton.me>
Co-authored-by: Robert Hensing <robert@roberthensing.nl>
Co-authored-by: Alexander Groleau <alex@proof.construction>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
The build log of the following won't output `foo` as one might expect, but the
`$PATH` set by stdenv.
```nix
with import <nixpkgs> {};
runCommand "foo" { PATH = "foo"; } "echo $PATH; touch $out"
```
Derivations built with `writeShellScriptBin`
should always be runnable with `nix run`. At present,
the derivation is missing both `meta.mainProgram`
and `pname`– this means that `nix run` falls back
to inferring the bin path from `name`. This is
unreliable and depends on faulty heuristics.
For context, reference the following snippet from
`nix run --help`:
If installable evaluates to a derivation, it will try to execute the
program <out>/bin/<name>, where out is the primary output store path
of the derivation, and name is the first of the following that exists:
· The meta.mainProgram attribute of the derivation.
· The pname attribute of the derivation.
· The name part of the value of the name attribute of the derivation.
Currently all packages defined by a call to runCommand have their
meta.position pointing to trivial-builders.nix.
This change makes uses of runCommand that supply at least one attribute
in the second argument point to the right file.
While searching for something different I wondered why there is a
trivial-builders.nix file next to the trivial-builders directory where
only tests live. Lets fix that.
