nixpkgs/doc/build-helpers/dev-shell-tools.chapter.md

Development Shell helpers

The nix-shell command has popularized the concept of transient shell environments for development or testing purposes.

However, nix-shell is not the only way to create such environments, and even nix-shell itself can indirectly benefit from this library.

This library provides a set of functions that help create such environments.

devShellTools.valueToString

Converts Nix values to strings in the way the derivation built-in function does.

:::{.example}

valueToString usage examples

devShellTools.valueToString (builtins.toFile "foo" "bar")
# => "/nix/store/...-foo"

devShellTools.valueToString false
# => ""

:::

devShellTools.unstructuredDerivationInputEnv

Convert a set of derivation attributes (as would be passed to [derivation]) to a set of environment variables that can be used in a shell script. This function does not support __structuredAttrs, but does support passAsFile.

:::{.example}

unstructuredDerivationInputEnv usage example

devShellTools.unstructuredDerivationInputEnv {
  drvAttrs = {
    name = "foo";
    buildInputs = [
      hello
      figlet
    ];
    builder = bash;
    args = [
      "-c"
      "${./builder.sh}"
    ];
  };
}
# => {
#  name = "foo";
#  buildInputs = "/nix/store/...-hello /nix/store/...-figlet";
#  builder = "/nix/store/...-bash";
#}

Note that args is not included, because Nix does not added it to the builder process environment.

:::

devShellTools.derivationOutputEnv

Takes the relevant parts of a derivation and returns a set of environment variables, that would be present in the derivation.

:::{.example}

derivationOutputEnv usage example

let
  pkg = hello;
in
devShellTools.derivationOutputEnv {
  outputList = pkg.outputs;
  outputMap = pkg;
}

:::