Merge branch 'master' into staging

1 files changed, 23 insertions, 8 deletions

diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml
index e93d1a98f7fd..8e981a4318e1 100644
--- a/doc/cross-compilation.xml
+++ b/doc/cross-compilation.xml
@@ -25,7 +25,7 @@
 <!--============================================================-->
 
 <section xml:id="sec-cross-packaging">
-  <title>Packing in a cross-friendly manner</title>
+  <title>Packaging in a cross-friendly manner</title>
 
   <section>
     <title>Platform parameters</title>
@@ -105,14 +105,15 @@
       This is the most important guiding principle behind cross-compilation with Nixpkgs, and will be called the <wordasword>sliding window principle</wordasword>.
       In this manner, given the 3 platforms for one package, we can determine the three platforms for all its transitive dependencies.
     </para>
+    <para>
+      Some examples will probably make this clearer.
+      If a package is being built with a <literal>(build, host, target)</literal> platform triple of <literal>(foo, bar, bar)</literal>, then its build-time dependencies would have a triple of <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis> build-time dependencies would have triple of <literal>(foo, foo, foo)</literal>.
+      In other words, it should take two "rounds" of following build-time dependency edges before one reaches a fixed point where, by the sliding window principle, the platform triple no longer changes.
+      Indeed, this happens with cross compilation, where only rounds of native dependencies starting with the second necessarily coincide with native packages.
+    </para>
     <note><para>
       The depending package's target platform is unconstrained by the sliding window principle, which makes sense in that one can in principle build cross compilers targeting arbitrary platforms.
     </para></note>
-    <warning><para>
-      From the above, one would surmise that if a package is being built with a <literal>(build, host, target)</literal> platform triple of <literal>(foo, bar, bar)</literal>, then its build-time dependencies would have a triple of <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis> build-time dependencies would have triple of <literal>(foo, foo, foo)</literal>.
-      In other words, it should take two "rounds" of following build-time dependency edges before one reaches a fixed point where, by the sliding window principle, the platform triple no longer changes.
-      Unfortunately, at the moment, we do <emphasis>not</emphasis> implement this correctly, and after only one round of following build-time dependencies is the fixed point reached, with target incorrectly kept different than the others.
-    </para></warning>
     <para>
       How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from from <varname>buildPackages</varname>, whereas run-time dependencies are taken from the top level attribute set.
       For example, <varname>buildPackages.gcc</varname> should be used at build time, while <varname>gcc</varname> should be used at run time.
@@ -131,9 +132,23 @@
 
 <section xml:id="sec-cross-usage">
   <title>Cross-building packages</title>
+  <note><para>
+    More information needs to moved from the old wiki, especially <link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this section.
+  </para></note>
+  <para>
+    Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, and, optionally, <varname>crossSystem</varname> to nixpkgs:
+    <literal>import &lt;nixpkgs&gt; { system = ..; platform = ..; crossSystem = ..; }</literal>.
+    <varname>system</varname> and <varname>platform</varname> together determine the system on which packages are built, and <varname>crossSystem</varname> specifies the platform on which packages are ultimately intended to run, if it is different.
+    This still works, but with more recent changes, one can alternatively pass <varname>localSystem</varname>, containing <varname>system</varname> and <varname>platform</varname>, for symmetry.
+  </para>
   <para>
-    To be written.
-    This is basically unchanged so see the old wiki for now.
+    One would think that <varname>localSystem</varname> and <varname>crossSystem</varname> overlap horribly with the three <varname>*Platforms</varname> (<varname>buildPlatform</varname>, <varname>hostPlatform,</varname> and <varname>targetPlatform</varname>; see <varname>stage.nix</varname> or the manual).
+    Actually, those identifiers are purposefully not used here to draw a subtle but important distinction:
+    While the granularity of having 3 platforms is necessary to properly *build* packages, it is overkill for specifying the user's *intent* when making a build plan or package set.
+    A simple "build vs deploy" dichotomy is adequate: the sliding window principle described in the previous section shows how to interpolate between the these two "end points" to get the 3 platform triple for each bootstrapping stage.
+    That means for any package a given package set, even those not bound on the top level but only reachable via dependencies or <varname>buildPackages</varname>, the three platforms will be defined as one of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the former replacing the latter as one traverses build-time dependencies.
+    A last simple difference then is <varname>crossSystem</varname> should be null when one doesn't want to cross-compile, while the <varname>*Platform</varname>s are always non-null.
+    <varname>localSystem</varname> is always non-null.
   </para>
 </section>