cmake: add support for --toolchain command argument

Help/manual/OPTIONS_BUILD.txt

@@ -76,6 +76,10 @@
  native build system to choose a compiler or SDK.  See the
  :variable:`CMAKE_GENERATOR_PLATFORM` variable for details.
 
+``--toolchain <path-to-file>``
+ Specify the cross compiling toolchain file, equivalant to setting
+ :variable:`CMAKE_TOOLCHAIN_FILE` variable.
+
 ``--install-prefix <directory>``
  Specify the installation directory, used by the
  :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path.

Help/manual/cmake-toolchains.7.rst

@@ -96,8 +96,8 @@ Cross Compiling
 ===============
 
 If :manual:`cmake(1)` is invoked with the command line parameter
-``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set
+``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the
-values for the compilers.
+file will be loaded early to set values for the compilers.
 The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is
 cross-compiling.
 

Help/release/dev/cmake-toolchain-command.rst

@@ -0,0 +1,5 @@
+cmake-toolchain-command
+----------------------------
+
+* The :manual:`cmake(1)` command gained the ``--toolchain <path/to/file>``
+  command line option to specify a toolchain file.

Source/cmake.cxx

@@ -509,6 +509,16 @@ bool cmake::SetCacheArgs(const std::vector<std::string>& args)
     return false;
   };
 
+  auto ToolchainLambda = [&](std::string const& path, cmake* state) -> bool {
+    const std::string var = "CMAKE_TOOLCHAIN_FILE";
+    cmStateEnums::CacheEntryType type = cmStateEnums::FILEPATH;
+#ifndef CMAKE_BOOTSTRAP
+    state->UnprocessedPresetVariables.erase(var);
+#endif
+    state->ProcessCacheArg(var, path, type);
+    return true;
+  };
+
   std::vector<CommandArgument> arguments = {
     CommandArgument{ "-D", "-D must be followed with VAR=VALUE.",
                      CommandArgument::Values::One, DefineLambda },
@@ -530,6 +540,8 @@ bool cmake::SetCacheArgs(const std::vector<std::string>& args)
 
     CommandArgument{ "-P", "-P must be followed by a file name.",
                      CommandArgument::Values::One, ScriptLambda },
+    CommandArgument{ "--toolchain", "No file specified for --toolchain",
+                     CommandArgument::Values::One, ToolchainLambda },
     CommandArgument{ "--install-prefix",
                      "No install directory specified for --install-prefix",
                      CommandArgument::Values::One, PrefixLambda },
@@ -835,6 +847,8 @@ void cmake::SetArgs(const std::vector<std::string>& args)
                      CommandArgument::Values::One, PlatformLambda },
     CommandArgument{ "-T", "No toolset specified for -T",
                      CommandArgument::Values::One, ToolsetLamda },
+    CommandArgument{ "--toolchain", "No file specified for --toolchain",
+                     CommandArgument::Values::One, IgnoreAndTrueLambda },
     CommandArgument{ "--install-prefix",
                      "No install directory specified for --install-prefix",
                      CommandArgument::Values::One, IgnoreAndTrueLambda },

Source/cmake.h

@@ -712,6 +712,8 @@ private:
       "Specify toolset name if supported by generator." },                    \
     { "-A <platform-name>",                                                   \
       "Specify platform name if supported by generator." },                   \
+    { "--toolchain <file>",                                                   \
+      "Specify toolchain file [CMAKE_TOOLCHAIN_FILE]." },                     \
     { "--install-prefix <directory>",                                         \
       "Specify install directory [CMAKE_INSTALL_PREFIX]." },                  \
     { "-Wdev", "Enable developer warnings." },                                \

Tests/RunCMake/CommandLine/RunCMakeTest.cmake

@@ -61,7 +61,6 @@ run_cmake_command(build-bad-dir
 run_cmake_command(build-bad-generator
   ${CMAKE_COMMAND} --build ${RunCMake_SOURCE_DIR}/cache-bad-generator)
 
-
 run_cmake_command(install-prefix-no-arg ${CMAKE_COMMAND} -B DummyBuildDir --install-prefix)
 
 run_cmake_command(install-no-dir
@@ -153,6 +152,29 @@ project(ExplicitDirsMissing LANGUAGES NONE)
 endfunction()
 run_ExplicitDirs()
 
+function(run_Toolchain)
+  set(RunCMake_TEST_NO_SOURCE_DIR 1)
+  set(source_dir ${RunCMake_SOURCE_DIR}/Toolchain)
+
+  run_cmake_with_options(toolchain-no-arg -S ${source_dir} --toolchain=)
+  run_cmake_with_options(toolchain-valid-abs-path -S ${source_dir} --toolchain "${source_dir}/toolchain.cmake")
+  run_cmake_with_options(toolchain-valid-rel-src-path -S ${source_dir} --toolchain=toolchain.cmake)
+
+  set(RunCMake_TEST_NO_CLEAN 1)
+  set(binary_dir ${RunCMake_BINARY_DIR}/Toolchain-build)
+  set(RunCMake_TEST_BINARY_DIR "${binary_dir}")
+  file(REMOVE_RECURSE "${binary_dir}")
+
+  # Test that we both search the binary dir for toolchain files, and it takes
+  # precedence over source dir
+  file(WRITE ${binary_dir}/toolchain.cmake [=[
+set(CMAKE_SYSTEM_NAME Linux)
+set(toolchain_file binary_dir)
+]=])
+  run_cmake_with_options(toolchain-valid-rel-build-path ${CMAKE_COMMAND} -S ${source_dir} -B ${binary_dir} --toolchain toolchain.cmake)
+endfunction()
+run_Toolchain()
+
 function(run_BuildDir)
   # Use a single build tree for a few tests without cleaning.
   set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/BuildDir-build)

Tests/RunCMake/CommandLine/Toolchain/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.20)
+project(Toolchain LANGUAGES NONE)
+message(FATAL_ERROR "${toolchain_file}")

Tests/RunCMake/CommandLine/Toolchain/toolchain.cmake

@@ -0,0 +1,2 @@
+set(CMAKE_SYSTEM_NAME Linux)
+set(toolchain_file source_dir)

Tests/RunCMake/CommandLine/toolchain-no-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/toolchain-no-arg-stderr.txt

@@ -0,0 +1 @@
+^CMake Error: No file specified for --toolchain

Tests/RunCMake/CommandLine/toolchain-valid-abs-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/toolchain-valid-abs-path-stderr.txt

@@ -0,0 +1 @@
+^CMake Error.*source_dir

Tests/RunCMake/CommandLine/toolchain-valid-rel-build-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/toolchain-valid-rel-build-path-stderr.txt

@@ -0,0 +1 @@
+^CMake Error.*binary_dir

Tests/RunCMake/CommandLine/toolchain-valid-rel-src-path-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/toolchain-valid-rel-src-path-stderr.txt

@@ -0,0 +1 @@
+^CMake Error.*source_dir