cmake: Allow CMAKE_TOOLCHAIN_FILE to be set by environment variable

When no `CMAKE_TOOLCHAIN_FILE` is explicitly specified while creating
a new build tree, check for an environment variable of the same name.

17 files changed, 86 insertions, 0 deletions

diff --git a/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst b/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst
new file mode 100644
index 0000000..7ea9cea
--- /dev/null
+++ b/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst
@@ -0,0 +1,12 @@
+CMAKE_TOOLCHAIN_FILE
+--------------------
+
+.. versionadded:: 3.21
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_TOOLCHAIN_FILE`` environment variable specifies a default value
+for the :variable:`CMAKE_TOOLCHAIN_FILE` variable 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_TOOLCHAIN_FILE`.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index 8932abf..bfdc841 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -41,6 +41,7 @@ Environment Variables that Control the Build
    /envvar/CMAKE_MSVCIDE_RUN_PATH
    /envvar/CMAKE_NO_VERBOSE
    /envvar/CMAKE_OSX_ARCHITECTURES
+   /envvar/CMAKE_TOOLCHAIN_FILE
    /envvar/DESTDIR
    /envvar/LDFLAGS
    /envvar/MACOSX_DEPLOYMENT_TARGET
diff --git a/Help/release/dev/env-toolchain-file.rst b/Help/release/dev/env-toolchain-file.rst
new file mode 100644
index 0000000..0bcd493
--- /dev/null
+++ b/Help/release/dev/env-toolchain-file.rst
@@ -0,0 +1,5 @@
+env-toolchain-file
+------------------
+
+* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to
+  provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable.
diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
index e462c5e..ff8d59a 100644
--- a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
+++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
@@ -10,3 +10,6 @@ platform and compiler related information.
 
 Relative paths are allowed and are interpreted first as relative to the
 build directory, and if not found, relative to the source directory.
+
+This is initialized by the :envvar:`CMAKE_TOOLCHAIN_FILE` environment
+variable if it is set when a new build tree is first created.
diff --git a/Source/cmake.cxx b/Source/cmake.cxx
index 840a9d9..9a866ab 100644
--- a/Source/cmake.cxx
+++ b/Source/cmake.cxx
@@ -2040,6 +2040,16 @@ int cmake::ActualConfigure()
                         this->GlobalGenerator->GetExtraGeneratorName().c_str(),
                         "Name of external makefile project generator.",
                         cmStateEnums::INTERNAL);
+
+    if (!this->State->GetInitializedCacheValue("CMAKE_TOOLCHAIN_FILE")) {
+      std::string envToolchain;
+      if (cmSystemTools::GetEnv("CMAKE_TOOLCHAIN_FILE", envToolchain) &&
+          !envToolchain.empty()) {
+        this->AddCacheEntry("CMAKE_TOOLCHAIN_FILE", envToolchain.c_str(),
+                            "The CMake toolchain file",
+                            cmStateEnums::FILEPATH);
+      }
+    }
   }
 
   if (cmProp instance =
diff --git a/Tests/RunCMake/CommandLine/EnvToolchain-toolchain.cmake b/Tests/RunCMake/CommandLine/EnvToolchain-toolchain.cmake
new file mode 100644
index 0000000..d9fbd58
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchain-toolchain.cmake
@@ -0,0 +1 @@
+set(ENV_TOOLCHAIN 1)
diff --git a/Tests/RunCMake/CommandLine/EnvToolchain.cmake b/Tests/RunCMake/CommandLine/EnvToolchain.cmake
new file mode 100644
index 0000000..230051d
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchain.cmake
@@ -0,0 +1,3 @@
+message(STATUS "ENV{CMAKE_TOOLCHAIN_FILE}='$ENV{CMAKE_TOOLCHAIN_FILE}'")
+message(STATUS "CMAKE_TOOLCHAIN_FILE='${CMAKE_TOOLCHAIN_FILE}'")
+message(STATUS "ENV_TOOLCHAIN='${ENV_TOOLCHAIN}'")
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainAbsolute-stdout.txt b/Tests/RunCMake/CommandLine/EnvToolchainAbsolute-stdout.txt
new file mode 100644
index 0000000..ab4bbde
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainAbsolute-stdout.txt
@@ -0,0 +1,5 @@
+-- ENV{CMAKE_TOOLCHAIN_FILE}='[^
+]*/Tests/RunCMake/CommandLine/EnvToolchain-toolchain.cmake'
+-- CMAKE_TOOLCHAIN_FILE='[^
+]*/Tests/RunCMake/CommandLine/EnvToolchain-toolchain.cmake'
+-- ENV_TOOLCHAIN='1'
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainAbsolute.cmake b/Tests/RunCMake/CommandLine/EnvToolchainAbsolute.cmake
new file mode 100644
index 0000000..0f91b5e
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainAbsolute.cmake
@@ -0,0 +1 @@
+include(EnvToolchain.cmake)
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainIgnore-stdout.txt b/Tests/RunCMake/CommandLine/EnvToolchainIgnore-stdout.txt
new file mode 100644
index 0000000..4de9505
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainIgnore-stdout.txt
@@ -0,0 +1,4 @@
+-- ENV{CMAKE_TOOLCHAIN_FILE}='[^
+]*/Tests/RunCMake/CommandLine/EnvToolchain-toolchain.cmake'
+-- CMAKE_TOOLCHAIN_FILE=''
+-- ENV_TOOLCHAIN=''
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainIgnore.cmake b/Tests/RunCMake/CommandLine/EnvToolchainIgnore.cmake
new file mode 100644
index 0000000..0f91b5e
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainIgnore.cmake
@@ -0,0 +1 @@
+include(EnvToolchain.cmake)
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainNone-stdout.txt b/Tests/RunCMake/CommandLine/EnvToolchainNone-stdout.txt
new file mode 100644
index 0000000..cfe655d
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainNone-stdout.txt
@@ -0,0 +1,3 @@
+-- ENV{CMAKE_TOOLCHAIN_FILE}=''
+-- CMAKE_TOOLCHAIN_FILE=''
+-- ENV_TOOLCHAIN=''
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainNone.cmake b/Tests/RunCMake/CommandLine/EnvToolchainNone.cmake
new file mode 100644
index 0000000..0f91b5e
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainNone.cmake
@@ -0,0 +1 @@
+include(EnvToolchain.cmake)
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainNoneExisting-stdout.txt b/Tests/RunCMake/CommandLine/EnvToolchainNoneExisting-stdout.txt
new file mode 100644
index 0000000..4de9505
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainNoneExisting-stdout.txt
@@ -0,0 +1,4 @@
+-- ENV{CMAKE_TOOLCHAIN_FILE}='[^
+]*/Tests/RunCMake/CommandLine/EnvToolchain-toolchain.cmake'
+-- CMAKE_TOOLCHAIN_FILE=''
+-- ENV_TOOLCHAIN=''
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainRelative-stdout.txt b/Tests/RunCMake/CommandLine/EnvToolchainRelative-stdout.txt
new file mode 100644
index 0000000..4bafbba
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainRelative-stdout.txt
@@ -0,0 +1,4 @@
+-- ENV{CMAKE_TOOLCHAIN_FILE}='EnvToolchain-toolchain.cmake'
+-- CMAKE_TOOLCHAIN_FILE='[^
+]*/Tests/RunCMake/CommandLine/EnvToolchainRelative-build/EnvToolchain-toolchain.cmake'
+-- ENV_TOOLCHAIN='1'
diff --git a/Tests/RunCMake/CommandLine/EnvToolchainRelative.cmake b/Tests/RunCMake/CommandLine/EnvToolchainRelative.cmake
new file mode 100644
index 0000000..0f91b5e
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvToolchainRelative.cmake
@@ -0,0 +1 @@
+include(EnvToolchain.cmake)
diff --git a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
index 2eb8784..c4d3e4a 100644
--- a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
+++ b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
@@ -344,6 +344,33 @@ if(RunCMake_GENERATOR MATCHES "Unix Makefiles" OR RunCMake_GENERATOR MATCHES "Ni
   run_EnvironmentExportCompileCommands()
 endif()
 
+function(run_EnvironmentToolchain)
+  set(ENV{CMAKE_TOOLCHAIN_FILE} "${RunCMake_SOURCE_DIR}/EnvToolchain-toolchain.cmake")
+  run_cmake(EnvToolchainAbsolute)
+  run_cmake_with_options(EnvToolchainIgnore -DCMAKE_TOOLCHAIN_FILE=)
+  unset(ENV{CMAKE_TOOLCHAIN_FILE})
+
+  set(ENV{CMAKE_TOOLCHAIN_FILE} "EnvToolchain-toolchain.cmake")
+  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/EnvToolchainRelative-build)
+  set(RunCMake_TEST_NO_CLEAN 1)
+  file(REMOVE_RECURSE "${RunCMake_TEST_BINARY_DIR}")
+  file(MAKE_DIRECTORY "${RunCMake_TEST_BINARY_DIR}")
+  configure_file("${RunCMake_SOURCE_DIR}/EnvToolchain-toolchain.cmake" "${RunCMake_TEST_BINARY_DIR}/EnvToolchain-toolchain.cmake" COPYONLY)
+  run_cmake(EnvToolchainRelative)
+  unset(ENV{CMAKE_TOOLCHAIN_FILE})
+  unset(RunCMake_TEST_NO_CLEAN)
+
+  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/EnvToolchainNone-build)
+  run_cmake(EnvToolchainNone)
+  set(RunCMake_TEST_NO_CLEAN 1)
+  file(REMOVE_RECURSE "${RunCMake_TEST_BINARY_DIR}/CMakeFiles")
+  set(ENV{CMAKE_TOOLCHAIN_FILE} "${RunCMake_SOURCE_DIR}/EnvToolchain-toolchain.cmake")
+  run_cmake_command(EnvToolchainNoneExisting ${CMAKE_COMMAND} .)
+  unset(ENV{CMAKE_TOOLCHAIN_FILE})
+  unset(RunCMake_TEST_NO_CLEAN)
+endfunction()
+run_EnvironmentToolchain()
+
 if(RunCMake_GENERATOR STREQUAL "Ninja")
   # Use a single build tree for a few tests without cleaning.
   set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/Build-build)