Prefer CMAKE_MAKE_PROGRAM over CMAKE_BUILD_TOOL (#14548)

Historically these were both added for the Makefile and Visual Studio
generators, respectively.  Later the VS generators started using the
CMAKE_MAKE_PROGRAM cache entry to find the IDE build tool, and the
CMAKE_BUILD_TOOL was simply set as an alias.

Fix the documentation to explain that CMAKE_MAKE_PROGRAM is the modern
variable and that CMAKE_BUILD_TOOL is the compatibility alias, not the
other way around.  Replace uses of CMAKE_BUILD_TOOL with
CMAKE_MAKE_PROGRAM in CMake-provided modules.  Nothing needs to lookup
CMAKE_BUILD_TOOL in the cache, so simply set it as a normal variable.

7 files changed, 15 insertions, 20 deletions

diff --git a/Help/variable/CMAKE_BUILD_TOOL.rst b/Help/variable/CMAKE_BUILD_TOOL.rst
index f0bc938b2d..61334917bb 100644
--- a/Help/variable/CMAKE_BUILD_TOOL.rst
+++ b/Help/variable/CMAKE_BUILD_TOOL.rst
@@ -1,11 +1,6 @@
 CMAKE_BUILD_TOOL
 ----------------
 
-Tool used for the actual build process.
-
-This variable is set to the program that will be needed to build the
-output of CMake.  If the generator selected was Visual Studio 6, the
-CMAKE_BUILD_TOOL will be set to msdev, for Unix Makefiles it will be
-set to make or gmake, and for Visual Studio 7 it set to devenv.  For
-NMake Makefiles the value is nmake.  This can be useful for adding
-special flags and commands based on the final build environment.
+This variable exists only for backwards compatibility.
+It contains the same value as :variable:`CMAKE_MAKE_PROGRAM`.
+Use that variable instead.
diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst
index 8307bc6362..b546815b27 100644
--- a/Help/variable/CMAKE_MAKE_PROGRAM.rst
+++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst
@@ -1,7 +1,10 @@
 CMAKE_MAKE_PROGRAM
 ------------------
 
-See CMAKE_BUILD_TOOL.
+Tool used for the actual build process.
 
-This variable is around for backwards compatibility, see
-CMAKE_BUILD_TOOL.
+This variable is set to the program that will be needed to build the
+output of CMake.  If the generator selected was Visual Studio 6, the
+CMAKE_MAKE_PROGRAM will be set to msdev, for Unix Makefiles it will be
+set to make or gmake, and for Visual Studio 7 it set to devenv.  For
+NMake Makefiles the value is nmake.
diff --git a/Modules/CMakeCXXInformation.cmake b/Modules/CMakeCXXInformation.cmake
index 45ec95aff0..9cf3489754 100644
--- a/Modules/CMakeCXXInformation.cmake
+++ b/Modules/CMakeCXXInformation.cmake
@@ -287,7 +287,6 @@ if(NOT CMAKE_CXX_LINK_EXECUTABLE)
 endif()
 
 mark_as_advanced(
-CMAKE_BUILD_TOOL
 CMAKE_VERBOSE_MAKEFILE
 CMAKE_CXX_FLAGS
 CMAKE_CXX_FLAGS_RELEASE
diff --git a/Modules/CMakeCommonLanguageInclude.cmake b/Modules/CMakeCommonLanguageInclude.cmake
index e945aa7c8d..38a6d35ea8 100644
--- a/Modules/CMakeCommonLanguageInclude.cmake
+++ b/Modules/CMakeCommonLanguageInclude.cmake
@@ -94,12 +94,10 @@ set (CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS_INIT} $ENV{LDFLAGS}"
 set (CMAKE_STATIC_LINKER_FLAGS "${CMAKE_STATIC_LINKER_FLAGS_INIT}"
      CACHE STRING "Flags used by the linker during the creation of static libraries.")
 
-set(CMAKE_BUILD_TOOL ${CMAKE_MAKE_PROGRAM} CACHE INTERNAL
-     "What is the target build tool cmake is generating for.")
-
+# Alias the build tool variable for backward compatibility.
+set(CMAKE_BUILD_TOOL ${CMAKE_MAKE_PROGRAM})
 
 mark_as_advanced(
-CMAKE_BUILD_TOOL
 CMAKE_VERBOSE_MAKEFILE
 
 CMAKE_EXE_LINKER_FLAGS
diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake
index ada8655fb3..7759ead6da 100644
--- a/Modules/CTest.cmake
+++ b/Modules/CTest.cmake
@@ -244,7 +244,7 @@ if(BUILD_TESTING)
         "${CMAKE_CXX_COMPILER}" ${DART_NAME_COMPONENT})
     else()
       get_filename_component(DART_CXX_NAME
-        "${CMAKE_BUILD_TOOL}" ${DART_NAME_COMPONENT})
+        "${CMAKE_MAKE_PROGRAM}" ${DART_NAME_COMPONENT})
     endif()
     if(DART_CXX_NAME MATCHES "msdev")
       set(DART_CXX_NAME "vs60")
diff --git a/Source/cmGlobalKdevelopGenerator.cxx b/Source/cmGlobalKdevelopGenerator.cxx
index e7c857e4ca..273d4bba34 100644
--- a/Source/cmGlobalKdevelopGenerator.cxx
+++ b/Source/cmGlobalKdevelopGenerator.cxx
@@ -462,7 +462,7 @@ void cmGlobalKdevelopGenerator
         "      <numberofjobs>1</numberofjobs>\n"
         "      <dontact>false</dontact>\n"
         "      <makebin>" << this->GlobalGenerator->GetLocalGenerators()[0]->
-            GetMakefile()->GetRequiredDefinition("CMAKE_BUILD_TOOL")
+            GetMakefile()->GetRequiredDefinition("CMAKE_MAKE_PROGRAM")
             << " </makebin>\n"
         "      <selectedenvironment>default</selectedenvironment>\n"
         "      <environments>\n"
diff --git a/Tests/RunCMake/build_command/ErrorsCommon.cmake b/Tests/RunCMake/build_command/ErrorsCommon.cmake
index d22453916d..f007b8875a 100644
--- a/Tests/RunCMake/build_command/ErrorsCommon.cmake
+++ b/Tests/RunCMake/build_command/ErrorsCommon.cmake
@@ -37,9 +37,9 @@ build_command(cmd)
 message("4. cmd='${cmd}'")
 
 # Test the two-arg legacy signature:
-build_command(legacy_cmd ${CMAKE_BUILD_TOOL})
+build_command(legacy_cmd ${CMAKE_MAKE_PROGRAM})
 message("5. legacy_cmd='${legacy_cmd}'")
-message("   CMAKE_BUILD_TOOL='${CMAKE_BUILD_TOOL}'")
+message("   CMAKE_MAKE_PROGRAM='${CMAKE_MAKE_PROGRAM}'")
 
 # Test the optional KEYWORDs:
 build_command(cmd CONFIGURATION hoohaaConfig)