CrossCompiling: Load CMAKE_CROSSCOMPILING_EMULATOR from environment

Read `CMAKE_CROSSCOMPILING_EMULATOR` from an environment variable of the
same name if not specified with `-D` or an initial cache value.

Along with existing environment variable settings such as
`CMAKE_TOOLCHAIN_FILE`, cross compilation configuration can be more
completely set via environment variables.

Suggested-by: Henry Schreiner <henryschreineriii@gmail.com>

Help/envvar/CMAKE_CROSSCOMPILING_EMULATOR.rst

@@ -0,0 +1,11 @@
+CMAKE_CROSSCOMPILING_EMULATOR
+-----------------------------
+
+.. versionadded:: 3.28
+
+.. include:: ENV_VAR.txt
+
+The default value for :variable:`CMAKE_CROSSCOMPILING_EMULATOR` when there
+is no explicit configuration given on the first run while creating a new
+build tree.  On later runs in an existing build tree the value persists in
+the cache as :variable:`CMAKE_CROSSCOMPILING_EMULATOR`.

Help/manual/cmake-env-variables.7.rst

@@ -43,6 +43,7 @@ Environment Variables that Control the Build
    /envvar/CMAKE_COLOR_DIAGNOSTICS
    /envvar/CMAKE_CONFIGURATION_TYPES
    /envvar/CMAKE_CONFIG_TYPE
+   /envvar/CMAKE_CROSSCOMPILING_EMULATOR
    /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
    /envvar/CMAKE_GENERATOR
    /envvar/CMAKE_GENERATOR_INSTANCE

Help/release/dev/CMAKE_CROSSCOMPILING_EMULATOR-env-variable.rst

@@ -0,0 +1,6 @@
+CMAKE_CROSSCOMPILING_EMULATOR-env-variable
+------------------------------------------
+
+* The :envvar:`CMAKE_CROSSCOMPILING_EMULATOR` environment variable
+  was added to initialize the :variable:`CMAKE_CROSSCOMPILING_EMULATOR`
+  cache variable.

Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst

@@ -12,6 +12,10 @@ for the target system.
   Lists>`, then the first value is the command and remaining values are its
   arguments.
 
+.. versionadded:: 3.28
+  This variable can be initialized via an
+  :envvar:`CMAKE_CROSSCOMPILING_EMULATOR` environment variable.
+
 The command will be used to run :command:`try_run` generated executables,
 which avoids manual population of the ``TryRunResults.cmake`` file.
 

Source/cmake.cxx

@@ -2507,6 +2507,18 @@ int cmake::ActualConfigure()
                         "Name of generator toolset.", cmStateEnums::INTERNAL);
   }
 
+  if (!this->State->GetInitializedCacheValue(
+        "CMAKE_CROSSCOMPILING_EMULATOR")) {
+    cm::optional<std::string> emulator =
+      cmSystemTools::GetEnvVar("CMAKE_CROSSCOMPILING_EMULATOR");
+    if (emulator && !emulator->empty()) {
+      std::string message =
+        "Emulator to run executables and tests when cross compiling.";
+      this->AddCacheEntry("CMAKE_CROSSCOMPILING_EMULATOR", *emulator, message,
+                          cmStateEnums::STRING);
+    }
+  }
+
   // reset any system configuration information, except for when we are
   // InTryCompile. With TryCompile the system info is taken from the parent's
   // info to save time

Tests/RunCMake/CrosscompilingEmulator/EnvCrossCompilingEmulator-stdout.txt

@@ -0,0 +1,2 @@
+-- env_emulator='pseudo_emulator(\.exe)?'
+-- emulator='pseudo_emulator(\.exe)?'

Tests/RunCMake/CrosscompilingEmulator/EnvCrossCompilingEmulator.cmake

@@ -0,0 +1,6 @@
+message(STATUS "ENV{CMAKE_CROSS_COMPILING_EMULATOR}='$ENV{CMAKE_CROSSCOMPILING_EMULATOR}'")
+message(STATUS "CMAKE_CROSSCOMPLING_EMULATOR='${CMAKE_CROSSCOMPILING_EMULATOR}'")
+get_filename_component(env_emulator "$ENV{CMAKE_CROSSCOMPILING_EMULATOR}" NAME)
+message(STATUS "env_emulator='${env_emulator}'")
+get_filename_component(emulator "${CMAKE_CROSSCOMPILING_EMULATOR}" NAME)
+message(STATUS "emulator='${emulator}'")

Tests/RunCMake/CrosscompilingEmulator/RunCMakeTest.cmake

@@ -26,3 +26,11 @@ set(RunCMake_TEST_OPTIONS
 "-DCMAKE_CROSSCOMPILING_EMULATOR=${PSEUDO_EMULATOR_CUSTOM_COMMAND_ARG}\;custom_argument")
 CustomCommandGenerator_run_and_build(AddCustomCommandWithArg)
 CustomCommandGenerator_run_and_build(AddCustomTargetWithArg)
+unset(RunCMake_TEST_OPTIONS)
+
+function(run_EnvCrossCompilingEmulator)
+  set(ENV{CMAKE_CROSSCOMPILING_EMULATOR} "${PSEUDO_EMULATOR}")
+  run_cmake(EnvCrossCompilingEmulator)
+  unset(ENV{CMAKE_CROSSCOMPILING_EMULATOR})
+endfunction()
+run_EnvCrossCompilingEmulator()