top-level: Document the `{local,cross}System, contrasting with `*Platform`

This is an implementation detail of how the bootstrapping chain is chosen,
and thus need not be in the manual.

1 files changed, 16 insertions, 0 deletions

diff --git a/pkgs/top-level/default.nix b/pkgs/top-level/default.nix
index b7a4273acff..3c67d316f7c 100644
--- a/pkgs/top-level/default.nix
+++ b/pkgs/top-level/default.nix
@@ -83,6 +83,22 @@ in let
   boot = import ../stdenv/booter.nix { inherit lib allPackages; };
 
   stages = stdenvStages {
+    # One would think that `localSystem` and `crossSystem` overlap horribly with
+    # the three `*Platforms` (`buildPlatform`, `hostPlatform,` and
+    # `targetPlatform`; see `stage.nix` or the manual). Actually, those
+    # identifiers I, @Ericson2314, 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 manual shows
+    # how to interpolate between the these two "end points" to get the 3
+    # platform triple for each bootstrapping stage.
+    #
+    # Also, less philosophically but quite practically, `crossSystem` should be
+    # null when one doesn't want to cross-compile, while the `*Platform`s are
+    # always non-null. `localSystem` is always non-null.
     localSystem = { inherit system platform; };
     inherit lib crossSystem config overlays;
   };