devShellTools: Docs, fix args env

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

@@ -27,3 +27,49 @@ devShellTools.valueToString (builtins.toFile "foo" "bar")
 devShellTools.valueToString false
 => ""
 ```
+
+:::
+
+## `devShellTools.unstructuredDerivationInputEnv` {#sec-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
+
+```nix
+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` {#sec-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
+
+```nix
+let
+  pkg = hello;
+in
+devShellTools.derivationOutputEnv { outputList = pkg.outputs; outputMap = pkg; }
+```
+
+:::

pkgs/build-support/dev-shell-tools/default.nix

@@ -6,6 +6,8 @@ let
   inherit (builtins) typeOf;
 in
 rec {
+  # Docs: doc/build-helpers/dev-shell-tools.chapter.md
+  # Tests: ./tests/default.nix
   # This function closely mirrors what this Nix code does:
   # https://github.com/NixOS/nix/blob/2.8.0/src/libexpr/primops.cc#L1102
   # https://github.com/NixOS/nix/blob/2.8.0/src/libexpr/eval.cc#L1981-L2036
@@ -18,6 +20,8 @@ rec {
     else toString value;
 
 
+  # Docs: doc/build-helpers/dev-shell-tools.chapter.md
+  # Tests: ./tests/default.nix
   # https://github.com/NixOS/nix/blob/2.8.0/src/libstore/build/local-derivation-goal.cc#L992-L1004
   unstructuredDerivationInputEnv = { drvAttrs }:
     # FIXME: this should be `normalAttrs // passAsFileAttrs`
@@ -29,13 +33,15 @@ rec {
         else lib.nameValuePair name str
       )
       (removeAttrs drvAttrs [
+        # TODO: there may be more of these
         "args"
       ]);
 
+  # Docs: doc/build-helpers/dev-shell-tools.chapter.md
+  # Tests: ./tests/default.nix
   derivationOutputEnv = { outputList, outputMap }:
     # A mapping from output name to the nix store path where they should end up
     # https://github.com/NixOS/nix/blob/2.8.0/src/libexpr/primops.cc#L1253
     lib.genAttrs outputList (output: builtins.unsafeDiscardStringContext outputMap.${output}.outPath);
 
-
 }

pkgs/build-support/dev-shell-tools/tests/default.nix

@@ -149,8 +149,12 @@ in
         )
 
         ''${args:+fail "args should not be set by Nix. We don't expect it to and unstructuredDerivationInputEnv removes it."}
+        if [[ "''${builder:-x}" == x ]]; then
+          fail "builder should be set by Nix. We don't remove it in unstructuredDerivationInputEnv."
+        fi
       '';
     } // removeAttrs drvAttrs [
+      # This would break the derivation. Instead, we have a check in the derivation to make sure Nix doesn't set it.
       "args"
     ]);
 }