From 80e3fd91a92149cb6b463ebe32d5859f89fa6cda Mon Sep 17 00:00:00 2001
From: nicoo <nicoo@mur.at>
Date: Thu, 8 Aug 2024 16:17:13 +0000
Subject: [PATCH] doc/build-helpers: document `runCommandWith`

Co-authored-by: Johannes Kirschbauer <hsjobeki+github@gmail.com>
---
 .../trivial-build-helpers.chapter.md          | 72 ++++++++++++++++++-
 .../trivial-builders/default.nix              | 13 +---
 2 files changed, 73 insertions(+), 12 deletions(-)

diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md
index 5d4ede836a1b..0c7c3f899a73 100644
--- a/doc/build-helpers/trivial-build-helpers.chapter.md
+++ b/doc/build-helpers/trivial-build-helpers.chapter.md
@@ -3,6 +3,76 @@
 Nixpkgs provides a variety of wrapper functions that help build commonly useful derivations.
 Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these build helpers creates a derivation, but the arguments passed are different (usually simpler) from those required by `stdenv.mkDerivation`.
 
+
+## `runCommandWith` {#trivial-builder-runCommandWith}
+
+The function `runCommandWith` returns a derivation built using the specified command(s), in a specified environment.
+
+It is the underlying base function of  all `runCommand*` variants. 
+The general behavior is controlled via a single attribute set passed 
+as the first argument, and allows specifying `stdenv` freely.
+
+### Type {#trivial-builder-runCommandWith-Type}
+
+```
+runCommandWith :: {
+  name :: name;
+  stdenv? :: Derivation;
+  runLocal? :: Bool;
+  derivationArgs? :: { ... };
+} -> String -> Derivation
+```
+
+### Inputs {#trivial-builder-runCommandWith-Inputs}
+
+`name` (String)
+:   The derivation's name, which Nix will append to the store path; see [`mkDerivation`](#sec-using-stdenv).
+
+`runLocal` (Boolean)
+:   If set to `true` this forces the derivation to be built locally. Remote substitutes and distributed builds, won't be used.
+    Its effect is to set [`preferLocalBuild = true`][preferLocalBuild] and [`allowSubstitutes = false`][allowSubstitutes].
+
+   ::: {.note}
+   This prevents the use of substitutors, so only set `runLocal` (or use `runCommandLocal`) when certain the user will
+   always have a builder for the `system` of the derivation. This should be true for most trivial use cases
+   (e.g., just copying some files to a different location or adding symlinks) because there the `system`
+   is usually the same as `builtins.currentSystem`.
+   :::
+
+`stdenv` (Derivation)
+:   The [standard environment](#chap-stdenv) to use, defaulting to `pkgs.stdenv`
+
+`derivationArgs` (Attribute set)
+:   Additional arguments for [`mkDerivation`](#sec-using-stdenv).
+
+`buildCommand` (String)
+:   Shell commands to run in the derivation builder.
+
+    ::: {.note}
+    You have to create a file or directory `$out` for Nix to be able to run the builder successfully.
+    :::
+
+[allowSubstitutes]: https://nixos.org/nix/manual/#adv-attr-allowSubstitutes
+[preferLocalBuild]: https://nixos.org/nix/manual/#adv-attr-preferLocalBuild
+
+::: {.example #ex-runcommandwith}
+# Invocation of `runCommandWith`
+
+```nix
+runCommandWith {
+  name = "example";
+  derivationArgs.nativeBuildInputs = [ cowsay ];
+} ''
+  cowsay > $out <<EOMOO
+  'runCommandWith' is a bit cumbersome,
+  so we have more ergonomic wrappers.
+  EOMOO
+''
+```
+
+:::
+
+
 ## `runCommand` {#trivial-builder-runCommand}
 
 `runCommand :: String -> AttrSet -> String -> Derivation`
@@ -58,7 +128,7 @@ This works just like `runCommand`. The only difference is that it also provides
 Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network round-trip and can speed up a build.
 
 ::: {.note}
-This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr-allowSubstitutes), so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g., just copying some files to a different location or adding symlinks) because there the `system` is usually the same as `builtins.currentSystem`.
+This sets [`allowSubstitutes` to `false`][allowSubstitutes], so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g., just copying some files to a different location or adding symlinks) because there the `system` is usually the same as `builtins.currentSystem`.
 :::
 
 ## Writing text files {#trivial-builder-text-writing}
diff --git a/pkgs/build-support/trivial-builders/default.nix b/pkgs/build-support/trivial-builders/default.nix
index fc6f07fdd11b..1939b24ccec3 100644
--- a/pkgs/build-support/trivial-builders/default.nix
+++ b/pkgs/build-support/trivial-builders/default.nix
@@ -36,17 +36,8 @@ rec {
   # `runCommandCCLocal` left out on purpose.
   # We shouldn’t force the user to have a cc in scope.
 
-  # TODO: Move documentation for runCommandWith to the Nixpkgs manual
-  /*
-    Generalized version of the `runCommand`-variants
-    which does customized behavior via a single
-    attribute set passed as the first argument
-    instead of having a lot of variants like
-    `runCommand*`. Additionally it allows changing
-    the used `stdenv` freely and has a more explicit
-    approach to changing the arguments passed to
-    `stdenv.mkDerivation`.
-   */
+  # Docs in doc/build-helpers/trivial-build-helpers.chapter.md
+  # See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-runCommandWith
   runCommandWith =
     let
       # prevent infinite recursion for the default stdenv value