meson: add mesonEmulatorHook

fixes building documentation while cross-compiling and other issues
Exec format error: './gdk3-scan'

added some simple documentation

doc/stdenv/cross-compilation.chapter.md

@@ -153,6 +153,24 @@ Add the following to your `mkDerivation` invocation.
 doCheck = stdenv.hostPlatform == stdenv.buildPlatform;
 ```
 
+#### Package using Meson needs to run binaries for the host platform during build. {#cross-meson-runs-host-code}
+
+Add `mesonEmulatorHook` cross conditionally to `nativeBuildInputs`.
+
+e.g.
+
+```
+nativeBuildInputs = [
+  meson
+] ++ lib.optionals (stdenv.buildPlatform != stdenv.hostPlatform) [
+  mesonEmulatorHook
+];
+```
+
+Example of an error which this fixes.
+
+`[Errno 8] Exec format error: './gdk3-scan'`
+
 ## Cross-building packages {#sec-cross-usage}
 
 Nixpkgs can be instantiated with `localSystem` alone, in which case there is no cross-compiling and everything is built by and for that system, or also with `crossSystem`, 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, `lib.systems.examples` has some platforms which are used as arguments for these parameters in practice. You can use them programmatically, or on the command line:

pkgs/development/tools/build-managers/meson/emulator-hook.sh

@@ -0,0 +1,5 @@
+add_meson_exe_wrapper_cross_flag() {
+  mesonFlagsArray+=(--cross-file=@crossFile@)
+}
+
+preConfigureHooks+=(add_meson_exe_wrapper_cross_flag)

pkgs/top-level/all-packages.nix

@@ -3942,6 +3942,24 @@ with pkgs;
 
   meson = callPackage ../development/tools/build-managers/meson { };
 
+  # while building documentation meson may want to run binaries for host
+  # which needs an emulator
+  # example of an error which this fixes
+  # [Errno 8] Exec format error: './gdk3-scan'
+  mesonEmulatorHook =
+    if (stdenv.buildPlatform != stdenv.targetPlatform) then
+      makeSetupHook
+        {
+          name = "mesonEmulatorHook";
+          substitutions = {
+            crossFile = writeText "cross-file.conf" ''
+              [binaries]
+              exe_wrapper = ${lib.escapeShellArg (stdenv.targetPlatform.emulator buildPackages)}
+            '';
+          };
+        } ../development/tools/build-managers/meson/emulator-hook.sh
+    else throw "mesonEmulatorHook has to be in a cross conditional i.e. (stdenv.buildPlatform != stdenv.hostPlatform)";
+
   meson-tools = callPackage ../misc/meson-tools { };
 
   metabase = callPackage ../servers/metabase { };