doc: Cross chapter: Add note on why use example platforms

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml
index 3e67944e58f7..10e4706b0590 100644
--- a/doc/cross-compilation.xml
+++ b/doc/cross-compilation.xml
@@ -256,6 +256,16 @@
     You can use them programmatically, or on the command line: <programlisting>
 nix-build &lt;nixpkgs&gt; --arg crossSystem '(import &lt;nixpkgs/lib&gt;).systems.examples.fooBarBaz' -A whatever</programlisting>
   </para>
+  <note>
+    <para>
+      Eventually we would like to make these platform examples an unnecessary convenience so that <programlisting>
+nix-build &lt;nixpkgs&gt; --arg crossSystem.config '&lt;arch&gt;-&lt;os&gt;-&lt;vendor&gt;-&lt;abi&gt;' -A whatever</programlisting>
+      works in the vast majority of cases.
+      The problem today is dependencies on other sorts of configuration which aren't given proper defaults.
+      We rely on the examples to crudely to set those configuration parameters in some vaguely sane manner on the users behalf.
+      Issue <link xlink:href="https://github.com/NixOS/nixpkgs/issues/34274">#34274</link> tracks this inconvenience along with its root cause in crufty configuration options.
+    </para>
+  </note>
   <para>
     While one is free to pass both parameters in full, there's a lot of logic to fill in missing fields.
     As discussed in the previous section, only one of <varname>system</varname>, <varname>config</varname>, and <varname>parsed</varname> is needed to infer the other two.