top-level: Deprecate top-level `{build,host,target}Platform`

I don't know when we can/should remove them, but this at least gets
people to stop using them. The preferred alternatives also date back to
17.09 so writing forward-compatable code without extra conditions is
easy.

Beginning with these as they are the least controversial.

2 files changed, 14 insertions, 12 deletions

diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml
index 3b90596bcc2c6..c7187d86d1b3e 100644
--- a/doc/cross-compilation.xml
+++ b/doc/cross-compilation.xml
@@ -47,13 +47,9 @@
 
    <para>
     In Nixpkgs, these three platforms are defined as attribute sets under the
-    names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>,
-    and <literal>targetPlatform</literal>. All three are always defined as
-    attributes in the standard environment, and at the top level. That means
-    one can get at them just like a dependency in a function that is imported
-    with <literal>callPackage</literal>:
-<programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting>
-    , or just off <varname>stdenv</varname>:
+    names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and
+    <literal>targetPlatform</literal>. They are always defined as attributes in
+    the standard environment. That means one can access them like:
 <programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting>
     .
    </para>
diff --git a/pkgs/top-level/stage.nix b/pkgs/top-level/stage.nix
index 06978d1067bf9..5ca8b72b8b8e8 100644
--- a/pkgs/top-level/stage.nix
+++ b/pkgs/top-level/stage.nix
@@ -79,11 +79,17 @@ let
 
   # The old identifiers for cross-compiling. These should eventually be removed,
   # and the packages that rely on them refactored accordingly.
-  platformCompat = self: super: let
-    inherit (super.stdenv) buildPlatform hostPlatform targetPlatform;
-  in {
-    inherit buildPlatform hostPlatform targetPlatform;
-    inherit (buildPlatform) system;
+  platformCompat = self: super: {
+    buildPlatform = lib.warn
+      "top-level `buildPlatform` is deprecated since 18.09. Please use `stdenv.buildPlatform`."
+      super.stdenv.buildPlatform;
+    hostPlatform = lib.warn
+      "top-level `hostPlatform` is deprecated since 18.09. Please use `stdenv.hostPlatform`."
+      super.stdenv.hostPlatform;
+    targetPlatform = lib.warn
+      "top-level `targetPlatform` is deprecated since 18.09. Please use `stdenv.targetPlatform`."
+      super.stdenv.targetPlatform;
+    inherit (super.stdenv.buildPlatform) system;
   };
 
   splice = self: super: import ./splice.nix lib self (buildPackages != null);