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

   1 # Development Shell helpers {#chap-devShellTools}
   2
   3 The `nix-shell` command has popularized the concept of transient shell environments for development or testing purposes.
   4 <!--
   5   We should try to document the product, not its development process in the Nixpkgs reference manual,
   6   but *something* needs to be said to provide context for this library.
   7   This is the most future proof sentence I could come up with while Nix itself does yet make use of this.
   8   Relevant is the current status of the devShell attribute "project": https://github.com/NixOS/nix/issues/7501
   9   -->
  10 However, `nix-shell` is not the only way to create such environments, and even `nix-shell` itself can indirectly benefit from this library.
  11
  12 This library provides a set of functions that help create such environments.
  13
  14 ## `devShellTools.valueToString` {#sec-devShellTools-valueToString}
  15
  16 Converts Nix values to strings in the way the [`derivation` built-in function](https://nix.dev/manual/nix/2.23/language/derivations) does.
  17
  18 :::{.example}
  19 ## `valueToString` usage examples
  20
  21 ```nix
  22 devShellTools.valueToString (builtins.toFile "foo" "bar")
  23 => "/nix/store/...-foo"
  24 ```
  25
  26 ```nix
  27 devShellTools.valueToString false
  28 => ""
  29 ```
  30
  31 :::
  32
  33 ## `devShellTools.unstructuredDerivationInputEnv` {#sec-devShellTools-unstructuredDerivationInputEnv}
  34
  35 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.
  36 This function does not support `__structuredAttrs`, but does support `passAsFile`.
  37
  38 :::{.example}
  39 ## `unstructuredDerivationInputEnv` usage example
  40
  41 ```nix
  42 devShellTools.unstructuredDerivationInputEnv {
  43   drvAttrs = {
  44     name = "foo";
  45     buildInputs = [ hello figlet ];
  46     builder = bash;
  47     args = [ "-c" "${./builder.sh}" ];
  48   };
  49 }
  50 => {
  51   name = "foo";
  52   buildInputs = "/nix/store/...-hello /nix/store/...-figlet";
  53   builder = "/nix/store/...-bash";
  54 }
  55 ```
  56
  57 Note that `args` is not included, because Nix does not added it to the builder process environment.
  58
  59 :::
  60
  61 ## `devShellTools.derivationOutputEnv` {#sec-devShellTools-derivationOutputEnv}
  62
  63 Takes the relevant parts of a derivation and returns a set of environment variables, that would be present in the derivation.
  64
  65 :::{.example}
  66 ## `derivationOutputEnv` usage example
  67
  68 ```nix
  69 let
  70   pkg = hello;
  71 in
  72 devShellTools.derivationOutputEnv { outputList = pkg.outputs; outputMap = pkg; }
  73 ```
  74
  75 :::