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.

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.

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.

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

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

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")

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"

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)