From 66a0358a15337d99e89e31d6c20081b7b74854de Mon Sep 17 00:00:00 2001
From: Ingo Blechschmidt <iblech@speicherleck.de>
Date: Tue, 5 Apr 2022 16:00:51 +0200
Subject: [PATCH 1/2] nixos-rebuild: document cross compilation subtlety

---
 nixos/doc/manual/man-nixos-rebuild.xml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml
index b2ca9f457a2..ea96f49fa97 100644
--- a/nixos/doc/manual/man-nixos-rebuild.xml
+++ b/nixos/doc/manual/man-nixos-rebuild.xml
@@ -548,6 +548,14 @@
       (<replaceable>user@host</replaceable>). You can also set ssh options by
       defining the <envar>NIX_SSHOPTS</envar> environment variable.
      </para>
+
+     <para>
+      Note that <command>nixos-rebuild</command> honors the
+      <literal>nixpkgs.crossSystem</literal> setting of the given configuration
+      but disregards the true architecture of the target host. Hence the
+      <literal>nixpkgs.crossSystem</literal> setting has to match the target
+      platform or else activation will fail.
+     </para>
     </listitem>
    </varlistentry>
 

From c3428419e05c8e3ef2b722b82b2f7065a6d46441 Mon Sep 17 00:00:00 2001
From: Ingo Blechschmidt <iblech@speicherleck.de>
Date: Tue, 5 Apr 2022 16:52:09 +0200
Subject: [PATCH 2/2] nixos/switch-to-configuration: Provider better error
 message in cross-compiling situations

---
 .../system/activation/switch-to-configuration.pl     | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/nixos/modules/system/activation/switch-to-configuration.pl b/nixos/modules/system/activation/switch-to-configuration.pl
index 9e5b760434a..3f0d976e70b 100755
--- a/nixos/modules/system/activation/switch-to-configuration.pl
+++ b/nixos/modules/system/activation/switch-to-configuration.pl
@@ -1,5 +1,17 @@
 #! @perl@/bin/perl
 
+# Issue #166838 uncovered a situation in which a configuration not suitable
+# for the target architecture caused a cryptic error message instead of
+# a clean failure. Due to this mismatch, the perl interpreter in the shebang
+# line wasn't able to be executed, causing this script to be misinterpreted
+# as a shell script.
+#
+# Let's detect this situation to give a more meaningful error
+# message. The following two lines are carefully written to be both valid Perl
+# and Bash.
+printf "Perl script erroneously interpreted as shell script,\ndoes target platform match nixpkgs.crossSystem platform?\n" && exit 1
+    if 0;
+
 use strict;
 use warnings;
 use Config::IniFiles;