depot/third_party/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; }

:::