doc/builders/trivial-builders: added runCommandLocal docs

The link in the note points to the `id` added in
https://github.com/NixOS/nix/pull/3255, so it might take some time to
start working correctly.

1 files changed, 13 insertions, 0 deletions

diff --git a/doc/builders/trivial-builders.xml b/doc/builders/trivial-builders.xml
index df0e38da1aa..18d1f9701a4 100644
--- a/doc/builders/trivial-builders.xml
+++ b/doc/builders/trivial-builders.xml
@@ -52,6 +52,19 @@
   </varlistentry>
   <varlistentry>
    <term>
+    <literal>runCommandLocal</literal>, <literal>runCommandCCLocal</literal>
+   </term>
+   <listitem>
+    <para>
+     Variants of <literal>runCommand</literal> and <literal>runCommandCC</literal> that force the derivation to be built locally, it is not substituted. This is intended for very cheap commands (&lt;1s execution time). It saves on the network roundrip and can speed up a build.
+    </para>
+    <note><para>
+      This sets <link xlink:href="https://nixos.org/nix/manual/#adv-attr-allowSubstitutes"><literal>allowSubstitutes</literal> to <literal>false</literal></link>, so only use <literal>runCommandLocal</literal> if you are certain the user will always have a builder for the <literal>system</literal> 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 <literal>system</literal> is usually the same as <literal>builtins.currentSystem</literal>.
+    </para></note>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
     <literal>writeTextFile</literal>, <literal>writeText</literal>, <literal>writeTextDir</literal>, <literal>writeScript</literal>, <literal>writeScriptBin</literal>
    </term>
    <listitem>