From 4c17cd555f6443207144da9af6e1c2b1304afd8b Mon Sep 17 00:00:00 2001 From: John Ericson Date: Sun, 15 Jan 2017 17:45:04 -0500 Subject: [PATCH] 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. --- pkgs/top-level/default.nix | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/pkgs/top-level/default.nix b/pkgs/top-level/default.nix index b7a4273acff0..3c67d316f7c8 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; };