nixpkgs manual: add a section about passthru

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index 8df23c911522..bab4a8b292e4 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -247,6 +247,39 @@ genericBuild
 
 </variablelist>
 
+<variablelist>
+  <title>Special variables</title>
+
+  <varlistentry>
+    <term><varname>passthru</varname></term>
+    <listitem><para>This is an attribute set which can be filled with arbitrary
+    values. For example:
+
+<programlisting>
+passthru = {
+  foo = "bar";
+  baz = {
+    value1 = 4;
+    value2 = 5;
+  };
+}
+</programlisting>
+
+</para>
+
+    <para>Values inside it are not passed to the builder, so you can change
+    them without triggering a rebuild. However, they can be accessed outside of a
+    derivation directly, as if they were set inside a derivation itself, e.g.
+    <literal>hello.baz.value1</literal>. We don't specify any usage or
+    schema of <literal>passthru</literal> - it is meant for values that would be
+    useful outside the derivation in other parts of a Nix expression (e.g. in other
+    derivations). An example would be to convey some specific dependency of your
+    derivation which contains a program with plugins support.  Later, others who
+    make derivations with plugins can use passed-through dependency to ensure that
+    their plugin would be binary-compatible with built program.</para></listitem>
+  </varlistentry>
+
+</variablelist>
 
 </section>