Linker configuration: rely now on CMAKE_<LANG>_LINK_MODE variable.

CMake now provides the CMAKE_<LANG>_LINK_MODE variable which specify how
the link step is done. So, the CMAKE_<LANG>_USING_LINKER_MODE variable
is no longer needed.

Help/manual/cmake-variables.7.rst

@@ -488,7 +488,6 @@ Variables that Control the Build
    /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG
    /variable/CMAKE_LANG_LINKER_LAUNCHER
-   /variable/CMAKE_LANG_USING_LINKER_MODE
    /variable/CMAKE_LANG_USING_LINKER_TYPE
    /variable/CMAKE_LANG_VISIBILITY_PRESET
    /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY
@@ -854,6 +853,7 @@ Deprecated Variables that Control the Build
    :maxdepth: 1
 
    /variable/CMAKE_IOS_INSTALL_COMBINED
+   /variable/CMAKE_LANG_USING_LINKER_MODE
    /variable/CMAKE_USE_RELATIVE_PATHS
 
 Deprecated Variables for Languages

Help/release/dev/linker-configuration.rst

@@ -0,0 +1,7 @@
+linker-configuration
+--------------------
+
+* The :variable:`CMAKE_<LANG>_USING_LINKER_MODE` variable is no longer used to
+  determine the type of the contents of the
+  :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable. The
+  :variable:`CMAKE_<LANG>_LINK_MODE` variable, set by CMake, is used instead.

Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst

@@ -15,3 +15,18 @@ variable should be interpreted. The supported linker mode values are:
 ``TOOL``
   :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds the path to the linker
   tool.
+
+.. warning::
+
+  The variable must be set accordingly to how CMake manage the link step:
+
+  * value ``TOOL`` is expected and required when the linker is used directly
+    for the link step.
+  * value ``FLAGS`` is expected or the variable not set when the compiler is
+    used as driver for the link step.
+
+.. deprecated:: 4.0
+
+This variable is no longer used. The type of information stored in the
+:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable is determined by the
+:variable:`CMAKE_<LANG>_LINK_MODE` variable.

Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst

@@ -6,9 +6,15 @@ CMAKE_<LANG>_USING_LINKER_<TYPE>
 This variable defines how to specify the ``<TYPE>`` linker for the link step,
 as controlled by the :variable:`CMAKE_LINKER_TYPE` variable or the
 :prop_tgt:`LINKER_TYPE` target property. Depending on the value of the
-:variable:`CMAKE_<LANG>_USING_LINKER_MODE` variable,
+:variable:`CMAKE_<LANG>_LINK_MODE` variable,
 ``CMAKE_<LANG>_USING_LINKER_<TYPE>`` can hold compiler flags for the link step,
-or flags to be given directly to the linker tool.
+or the path to the linker tool.
+
+.. versionchanged:: 4.0
+
+The type of information stored in this variable is now determined by the
+:variable:`CMAKE_<LANG>_LINK_MODE` variable instead of the
+:variable:`CMAKE_<LANG>_USING_LINKER_MODE` variable.
 
 .. note::
 
@@ -19,21 +25,25 @@ For example, the ``LLD`` linker for ``GNU`` compilers is defined like so:
 
 .. code-block:: cmake
 
+  # CMAKE_C_LINK_MODE holds value "DRIVER"
   set(CMAKE_C_USING_LINKER_LLD "-fuse-ld=lld")
 
-On the ``Windows`` platform with ``Clang`` compilers simulating ``MSVC``:
+On the ``Windows`` platform with ``Clang`` compilers simulating ``MSVC`` with
+``GNU`` front-end:
 
 .. code-block:: cmake
 
+  # CMAKE_C_LINK_MODE holds value "DRIVER"
   set(CMAKE_C_USING_LINKER_LLD "-fuse-ld=lld-link")
 
-And for the ``MSVC`` compiler, the linker is invoked directly, not via the
-compiler frontend:
+And for the ``MSVC`` compiler or ``Clang`` compilers simulating ``MSVC`` with
+``MSVC`` front-end, the linker is invoked directly, not via the compiler
+front-end:
 
 .. code-block:: cmake
 
+  # CMAKE_C_LINK_MODE holds value "LINKER"
   set(CMAKE_C_USING_LINKER_LLD "/path/to/lld-link.exe")
-  set(CMAKE_C_USING_LINKER_MODE TOOL)
 
 A custom linker type can also be defined, usually in a toolchain file:
 
@@ -41,4 +51,3 @@ A custom linker type can also be defined, usually in a toolchain file:
 
   set(CMAKE_LINKER_TYPE lld_launcher)
   set(CMAKE_C_USING_LINKER_lld_launcher "-fuse-ld=/path/to/lld-launcher.sh")
-  set(CMAKE_C_USING_LINKER_MODE FLAG)

Modules/Platform/Windows-MSVC.cmake

@@ -510,7 +510,6 @@ macro(__windows_compiler_msvc lang)
   set(CMAKE_${lang}_USING_LINKER_SYSTEM "${CMAKE_LINKER_LINK}")
   set(CMAKE_${lang}_USING_LINKER_LLD "${CMAKE_LINKER_LLD}")
   set(CMAKE_${lang}_USING_LINKER_MSVC "${CMAKE_LINKER_LINK}")
-  set(CMAKE_${lang}_USING_LINKER_MODE TOOL)
 endmacro()
 
 macro(__windows_compiler_msvc_enable_rc flags)

Modules/Platform/Windows-NVIDIA-CUDA.cmake

@@ -51,7 +51,6 @@ unset(__IMPLICIT_DLINK_FLAGS)
 set(CMAKE_CUDA_USING_LINKER_SYSTEM "${CMAKE_LINKER_LINK}")
 set(CMAKE_CUDA_USING_LINKER_LLD "${CMAKE_LINKER_LLD}")
 set(CMAKE_CUDA_USING_LINKER_MSVC "${CMAKE_LINKER_LINK}")
-set(CMAKE_CUDA_USING_LINKER_MODE TOOL)
 
 string(REPLACE "/D" "-D" _PLATFORM_DEFINES_CUDA "${_PLATFORM_DEFINES}${_PLATFORM_DEFINES_CXX}")
 

Source/cmGeneratorTarget.cxx

@@ -3703,11 +3703,10 @@ std::string cmGeneratorTarget::GetLinkerTool(std::string const& config) const
 std::string cmGeneratorTarget::GetLinkerTool(std::string const& lang,
                                              std::string const& config) const
 {
-  auto usingLinker =
-    cmStrCat("CMAKE_", lang, "_USING_", this->IsDeviceLink() ? "DEVICE_" : "",
-             "LINKER_");
-  auto format = this->Makefile->GetDefinition(cmStrCat(usingLinker, "MODE"));
-  if (!format || format != "TOOL"_s) {
+  auto linkMode = cmStrCat(
+    "CMAKE_", lang, this->IsDeviceLink() ? "_DEVICE_" : "_", "LINK_MODE");
+  auto mode = this->Makefile->GetDefinition(linkMode);
+  if (!mode || mode != "LINKER"_s) {
     return this->Makefile->GetDefinition("CMAKE_LINKER");
   }
 
@@ -3715,7 +3714,9 @@ std::string cmGeneratorTarget::GetLinkerTool(std::string const& lang,
   if (linkerType.empty()) {
     linkerType = "DEFAULT";
   }
-  usingLinker = cmStrCat(usingLinker, linkerType);
+  auto usingLinker =
+    cmStrCat("CMAKE_", lang, "_USING_", this->IsDeviceLink() ? "DEVICE_" : "",
+             "LINKER_", linkerType);
   auto linkerTool = this->Makefile->GetDefinition(usingLinker);
 
   if (!linkerTool) {

Source/cmLocalGenerator.cxx

@@ -3359,12 +3359,11 @@ void cmLocalGenerator::AppendLinkerTypeFlags(std::string& flags,
       return;
   }
 
-  auto usingLinker =
-    cmStrCat("CMAKE_", linkLanguage, "_USING_",
-             target->IsDeviceLink() ? "DEVICE_" : "", "LINKER_");
-
-  auto format = this->Makefile->GetDefinition(cmStrCat(usingLinker, "MODE"));
-  if (format && format != "FLAG"_s) {
+  auto linkMode =
+    cmStrCat("CMAKE_", linkLanguage, target->IsDeviceLink() ? "_DEVICE_" : "_",
+             "LINK_MODE");
+  auto mode = this->Makefile->GetDefinition(linkMode);
+  if (mode && mode != "DRIVER"_s) {
     return;
   }
 
@@ -3372,7 +3371,9 @@ void cmLocalGenerator::AppendLinkerTypeFlags(std::string& flags,
   if (linkerType.empty()) {
     linkerType = "DEFAULT";
   }
-  usingLinker = cmStrCat(usingLinker, linkerType);
+  auto usingLinker =
+    cmStrCat("CMAKE_", linkLanguage, "_USING_",
+             target->IsDeviceLink() ? "DEVICE_" : "", "LINKER_", linkerType);
   auto linkerTypeFlags = this->Makefile->GetDefinition(usingLinker);
   if (linkerTypeFlags) {
     if (!linkerTypeFlags.IsEmpty()) {

Tests/RunCMake/LinkerSelection/CustomLinkerType.cmake

@@ -26,13 +26,13 @@ endif()
 #
 # Generate file for validation
 #
-if (CMAKE_C_USING_LINKER_MODE STREQUAL "TOOL")
+if (CMAKE_C_LINK_MODE STREQUAL "LINKER")
   cmake_path(GET CMAKE_C_USING_LINKER_FOO_C FILENAME LINKER_TYPE_OPTION)
 else()
   set(LINKER_TYPE_OPTION "${CMAKE_C_USING_LINKER_FOO_C}")
 endif()
 if(CMake_TEST_CUDA)
-  if (CMAKE_CUDA_USING_LINKER_MODE STREQUAL "TOOL")
+  if (CMAKE_CUDA_LINK_MODE STREQUAL "LINKER")
     cmake_path(GET CMAKE_CUDA_USING_LINKER_FOO_CUDA FILENAME CUDA_LINKER)
   else()
     set(CUDA_LINKER "${CMAKE_CUDA_USING_LINKER_FOO_CUDA}")
@@ -41,7 +41,7 @@ if(CMake_TEST_CUDA)
 endif()
 
 if(CMake_TEST_Swift)
-  if(CMAKE_Swift_USING_LINKER_MODE STREQUAL "TOOL")
+  if(CMAKE_Swift_LINK_MODE STREQUAL "LINKER")
     cmake_path(GET CMAKE_Swift_USING_LINKER_FOO_Swift FILENAME Swift_LINKER)
   else()
     set(Swift_LINKER "${CMAKE_Swift_USING_LINKER_FOO_Swift}")

Tests/RunCMake/LinkerSelection/ValidLinkerType.cmake

@@ -19,13 +19,13 @@ endif()
 #
 # Generate file for validation
 #
-if (CMAKE_C_USING_LINKER_MODE STREQUAL "TOOL")
+if (CMAKE_C_LINK_MODE STREQUAL "LINKER")
   cmake_path(GET CMAKE_C_USING_LINKER_LLD FILENAME LINKER_TYPE_OPTION)
 else()
   set(LINKER_TYPE_OPTION "${CMAKE_C_USING_LINKER_LLD}")
 endif()
 if(CMake_TEST_CUDA)
-  if (CMAKE_CUDA_USING_LINKER_MODE STREQUAL "TOOL")
+  if (CMAKE_CUDA_LINK_MODE STREQUAL "LINKER")
     cmake_path(GET CMAKE_CUDA_USING_LINKER_LLD FILENAME CUDA_LINKER)
   else()
     set(CUDA_LINKER "${CMAKE_CUDA_USING_LINKER_LLD}")
@@ -33,7 +33,7 @@ if(CMake_TEST_CUDA)
   string(APPEND LINKER_TYPE_OPTION "|${CUDA_LINKER}")
 endif()
 if(CMake_TEST_Swift)
-  if(CMAKE_Swift_USING_LINKER_MODE STREQUAL "TOOL")
+  if(CMAKE_Swift_LINK_MODE STREQUAL "LINKER")
     cmake_path(GET CMAKE_Swift_USING_LINKER_LLD FILENAME LINKER_TYPE_OPTION)
   else()
     set(Swift_LINKER "${CMAKE_Swift_USING_LINKER_LLD}")

Tests/RunCMake/try_compile/ProjectVars-stdout.txt

@@ -1,8 +1,5 @@
 CMAKE_LINKER_TYPE = DEFAULT
-.*CMAKE_C_USING_LINKER_MODE = [^
-]*
 .*CMAKE_C_USING_LINKER_abc123 = /path/to/somewhere
 .*CMAKE_C_USING_LINKER_Hi_There = some-tool
 .*CMAKE_ASM_NASM_USING_LINKER_custom = /place/holder
 .*CMAKE_ASM-ATT_USING_LINKER_custom = /more/text
-.*CMAKE_ASM-ATT_USING_LINKER_MODE = TOOL

Tests/RunCMake/try_compile/ProjectVars.cmake

@@ -7,7 +7,6 @@ set(CMAKE_C_USING_LINKER_abc123 /path/to/somewhere)
 set(CMAKE_C_USING_LINKER_Hi_There some-tool)
 set(CMAKE_ASM_NASM_USING_LINKER_custom /place/holder)
 set(CMAKE_ASM-ATT_USING_LINKER_custom /more/text)
-set(CMAKE_ASM-ATT_USING_LINKER_MODE TOOL)
 
 try_compile(RESULT
   PROJECT TestProject

Tests/RunCMake/try_compile/proj_vars/CMakeLists.txt

@@ -3,10 +3,8 @@ project(TestProject LANGUAGES NONE)
 
 add_custom_target(show_vars ALL
   COMMAND ${CMAKE_COMMAND} -E echo "CMAKE_LINKER_TYPE = ${CMAKE_LINKER_TYPE}"
-  COMMAND ${CMAKE_COMMAND} -E echo "CMAKE_C_USING_LINKER_MODE = ${CMAKE_C_USING_LINKER_MODE}"
   COMMAND ${CMAKE_COMMAND} -E echo "CMAKE_C_USING_LINKER_abc123 = ${CMAKE_C_USING_LINKER_abc123}"
   COMMAND ${CMAKE_COMMAND} -E echo "CMAKE_C_USING_LINKER_Hi_There = ${CMAKE_C_USING_LINKER_Hi_There}"
   COMMAND ${CMAKE_COMMAND} -E echo "CMAKE_ASM_NASM_USING_LINKER_custom = ${CMAKE_ASM_NASM_USING_LINKER_custom}"
   COMMAND ${CMAKE_COMMAND} -E echo "CMAKE_ASM-ATT_USING_LINKER_custom = ${CMAKE_ASM-ATT_USING_LINKER_custom}"
-  COMMAND ${CMAKE_COMMAND} -E echo "CMAKE_ASM-ATT_USING_LINKER_MODE = ${CMAKE_ASM-ATT_USING_LINKER_MODE}"
 )