Merge pull request #26037 from obsidiansystems/platform-examples

lib: Consolidate platform configurations (used for crossSystem)

1 files changed, 44 insertions, 8 deletions

diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml
index de1b9b80d30..e99e90bac9c 100644
--- a/doc/cross-compilation.xml
+++ b/doc/cross-compilation.xml
@@ -85,7 +85,8 @@
       This field is obsolete and will soon disappear—please do not use it.
     </para></note>
     <para>
-      The exact scheme these fields is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up.
+      The exact schema these fields follow is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up.
+      You can see examples of ones used in practice in <literal>lib.systems.examples</literal>; note how they are not all very consistent.
       For now, here are few fields can count on them containing:
     </para>
     <variablelist>
@@ -118,8 +119,27 @@
             This is a nix representation of a parsed LLVM target triple with white-listed components.
             This can be specified directly, or actually parsed from the <varname>config</varname>.
             [Technically, only one need be specified and the others can be inferred, though the precision of inference may not be very good.]
-            See <literal>lib.systems.parse</literal> for the exact representation, along with some <literal>is*</literal>predicates.
-            These predicates are superior to the ones in <varname>stdenv</varname> as they aren't tied to the build platform (host, as previously discussed, would be a saner default).
+            See <literal>lib.systems.parse</literal> for the exact representation.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><varname>libc</varname></term>
+        <listitem>
+          <para>
+            This is a string identifying the standard C library used.
+            Valid identifiers include "glibc" for GNU libc, "libsystem" for Darwin's Libsystem, and "uclibc" for µClibc.
+            It should probably be refactored to use the module system, like <varname>parse</varname>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><varname>is*</varname></term>
+        <listitem>
+          <para>
+            These predicates are defined in <literal>lib.systems.inspect</literal>, and slapped on every platform.
+            They are superior to the ones in <varname>stdenv</varname> as they force the user to be explicit about which platform they are inspecting.
+            Please use these instead of those.
           </para>
         </listitem>
       </varlistentry>
@@ -128,7 +148,7 @@
         <listitem>
           <para>
             This is, quite frankly, a dumping ground of ad-hoc settings (it's an attribute set).
-            See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform one is working.
+            See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform that is working.
             Please help us triage these flags and give them better homes!
           </para>
         </listitem>
@@ -184,12 +204,28 @@
     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.
+    Nixpkgs can be instantiated with <varname>localSystem</varname> alone, in which case there is no cross compiling and everything is built by and for that system,
+    or also with <varname>crossSystem</varname>, in which case packages run on the latter, but all building happens on the former.
+    Both parameters take the same schema as the 3 (build, host, and target) platforms defined in the previous section.
+    As mentioned above, <literal>lib.systems.examples</literal> has some platforms which are used as arguments for these parameters in practice.
+    You can use them programmatically, or on the command line like <command>nix-build &lt;nixpkgs&gt; --arg crossSystem '(import &lt;nixpkgs/lib&gt;).systems.examples.fooBarBaz'</command>.
   </para>
   <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.
+    Additionally, <varname>libc</varname> will be inferred from <varname>parse</varname>.
+    Finally, <literal>localSystem.system</literal> is also <emphasis>impurely</emphasis> inferred based on the platform evaluation occurs.
+    This means it is often not necessary to pass <varname>localSystem</varname> at all, as in the command-line example in the previous paragraph.
+  </para>
+  <note>
+    <para>
+      Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, along with the optional <varname>crossSystem</varname> to nixpkgs:
+      <literal>import &lt;nixpkgs&gt; { system = ..; platform = ..; crossSystem = ..; }</literal>.
+      Passing those two instead of <varname>localSystem</varname> is still supported for compatibility, but is discouraged.
+      Indeed, much of the inference we do for these parameters is motivated by compatibility as much as convenience.
+    </para>
+  </note>
+  <para>
     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.