Honor CMAKE_*_LINKER_FLAGS[_<CONFIG>]_INIT set in toolchain files

Document these variables.

Change our convention for setting these variables from:

    set(CMAKE_EXE_LINKER_FLAGS_INIT "...")

to

    string(APPEND CMAKE_EXE_LINKER_FLAGS_INIT " ...")

so that any value previously set by a toolchain file will be used.

Help/manual/cmake-variables.7.rst

@@ -253,7 +253,9 @@ Variables that Control the Build
    /variable/CMAKE_DEBUG_POSTFIX
    /variable/CMAKE_ENABLE_EXPORTS
    /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_EXE_LINKER_FLAGS
+   /variable/CMAKE_EXE_LINKER_FLAGS_INIT
    /variable/CMAKE_Fortran_FORMAT
    /variable/CMAKE_Fortran_MODULE_DIRECTORY
    /variable/CMAKE_GNUtoMS
@@ -280,7 +282,9 @@ Variables that Control the Build
    /variable/CMAKE_MACOSX_RPATH
    /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG
    /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_MODULE_LINKER_FLAGS
+   /variable/CMAKE_MODULE_LINKER_FLAGS_INIT
    /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
    /variable/CMAKE_NO_BUILTIN_CHRPATH
    /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED
@@ -293,11 +297,15 @@ Variables that Control the Build
    /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
    /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_SHARED_LINKER_FLAGS
+   /variable/CMAKE_SHARED_LINKER_FLAGS_INIT
    /variable/CMAKE_SKIP_BUILD_RPATH
    /variable/CMAKE_SKIP_INSTALL_RPATH
    /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_STATIC_LINKER_FLAGS
+   /variable/CMAKE_STATIC_LINKER_FLAGS_INIT
    /variable/CMAKE_TRY_COMPILE_CONFIGURATION
    /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
    /variable/CMAKE_TRY_COMPILE_TARGET_TYPE

Help/release/dev/toolchain-flag-init.rst

@@ -5,3 +5,12 @@ toolchain-flag-init
   :variable:`CMAKE_<LANG>_FLAGS_INIT` variable to initialize the
   :variable:`CMAKE_<LANG>_FLAGS` cache entry the first time a language is
   enabled in a build tree.
+
+* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set
+  :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`,
+  :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and
+  :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT` variables to initialize the
+  :variable:`CMAKE_EXE_LINKER_FLAGS`,
+  :variable:`CMAKE_SHARED_LINKER_FLAGS`, and
+  :variable:`CMAKE_MODULE_LINKER_FLAGS` cache entries the first time
+  a language is enabled in a build tree.

Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst

@@ -0,0 +1,10 @@
+CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT
+------------------------------------
+
+Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`.

Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst

@@ -0,0 +1,11 @@
+CMAKE_EXE_LINKER_FLAGS_INIT
+---------------------------
+
+Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also the configuration-specific variable
+:variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT`.

Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst

@@ -0,0 +1,10 @@
+CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT
+---------------------------------------
+
+Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT`.

Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst

@@ -0,0 +1,11 @@
+CMAKE_MODULE_LINKER_FLAGS_INIT
+------------------------------
+
+Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also the configuration-specific variable
+:variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT`.

Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst

@@ -0,0 +1,10 @@
+CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT
+---------------------------------------
+
+Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`.

Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst

@@ -0,0 +1,11 @@
+CMAKE_SHARED_LINKER_FLAGS_INIT
+------------------------------
+
+Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also the configuration-specific variable
+:variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT`.

Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst

@@ -0,0 +1,10 @@
+CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT
+---------------------------------------
+
+Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also :variable:`CMAKE_STATIC_LINKER_FLAGS_INIT`.

Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst

@@ -0,0 +1,11 @@
+CMAKE_STATIC_LINKER_FLAGS_INIT
+------------------------------
+
+Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS`
+cache entry the first time a build tree is configured.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also the configuration-specific variable
+:variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT`.

Modules/Platform/AIX-GNU.cmake

@@ -21,9 +21,9 @@ set(__AIX_COMPILER_GNU 1)
 #
 # By default, runtime linking is enabled. All shared objects specified on the command line
 # will be listed, even if there are no symbols referenced, in the output file.
-set (CMAKE_SHARED_LINKER_FLAGS_INIT "-Wl,-brtl")
+string(APPEND CMAKE_SHARED_LINKER_FLAGS_INIT " -Wl,-brtl")
-set (CMAKE_MODULE_LINKER_FLAGS_INIT "-Wl,-brtl")
+string(APPEND CMAKE_MODULE_LINKER_FLAGS_INIT " -Wl,-brtl")
-set (CMAKE_EXE_LINKER_FLAGS_INIT "-Wl,-brtl")
+string(APPEND CMAKE_EXE_LINKER_FLAGS_INIT " -Wl,-brtl")
 
 
 macro(__aix_compiler_gnu lang)

Modules/Platform/AIX-XL.cmake

@@ -21,9 +21,9 @@ set(__AIX_COMPILER_XL 1)
 #
 # By default, runtime linking is enabled. All shared objects specified on the command line
 # will be listed, even if there are no symbols referenced, in the output file.
-set(CMAKE_SHARED_LINKER_FLAGS_INIT "-Wl,-brtl")
+string(APPEND CMAKE_SHARED_LINKER_FLAGS_INIT " -Wl,-brtl")
-set(CMAKE_MODULE_LINKER_FLAGS_INIT "-Wl,-brtl")
+string(APPEND CMAKE_MODULE_LINKER_FLAGS_INIT " -Wl,-brtl")
-set(CMAKE_EXE_LINKER_FLAGS_INIT "-Wl,-brtl")
+string(APPEND CMAKE_EXE_LINKER_FLAGS_INIT " -Wl,-brtl")
 
 
 macro(__aix_compiler_xl lang)

Modules/Platform/CYGWIN-GNU.cmake

@@ -19,7 +19,7 @@ endif()
 set(__CYGWIN_COMPILER_GNU 1)
 
 # TODO: Is -Wl,--enable-auto-import now always default?
-set(CMAKE_EXE_LINKER_FLAGS_INIT "-Wl,--enable-auto-import")
+string(APPEND CMAKE_EXE_LINKER_FLAGS_INIT " -Wl,--enable-auto-import")
 set(CMAKE_CREATE_WIN32_EXE  "-mwindows")
 
 set(CMAKE_GNULD_IMAGE_VERSION

Modules/Platform/Windows-Embarcadero.cmake

@@ -65,9 +65,9 @@ set (CMAKE_BUILD_TYPE Debug CACHE STRING
      "Choose the type of build, options are: Debug Release RelWithDebInfo MinSizeRel.")
 
 foreach(t EXE SHARED MODULE)
-  set(CMAKE_${t}_LINKER_FLAGS_INIT "${_tM} -lS:1048576 -lSc:4098 -lH:1048576 -lHc:8192 ")
+  string(APPEND CMAKE_${t}_LINKER_FLAGS_INIT " ${_tM} -lS:1048576 -lSc:4098 -lH:1048576 -lHc:8192 ")
-  set(CMAKE_${t}_LINKER_FLAGS_DEBUG_INIT "-v")
+  string(APPEND CMAKE_${t}_LINKER_FLAGS_DEBUG_INIT " -v")
-  set(CMAKE_${t}_LINKER_FLAGS_RELWITHDEBINFO_INIT "-v")
+  string(APPEND CMAKE_${t}_LINKER_FLAGS_RELWITHDEBINFO_INIT " -v")
 endforeach()
 
 # The Borland link tool does not support multiple concurrent

Modules/Platform/Windows-MSVC.cmake

@@ -252,15 +252,15 @@ endif()
 foreach(t EXE SHARED MODULE)
   string(APPEND CMAKE_${t}_LINKER_FLAGS_INIT " ${_MACHINE_ARCH_FLAG}")
   if (CMAKE_COMPILER_SUPPORTS_PDBTYPE)
-    set(CMAKE_${t}_LINKER_FLAGS_DEBUG_INIT "/debug /pdbtype:sept ${MSVC_INCREMENTAL_YES_FLAG}")
+    string(APPEND CMAKE_${t}_LINKER_FLAGS_DEBUG_INIT " /debug /pdbtype:sept ${MSVC_INCREMENTAL_YES_FLAG}")
-    set(CMAKE_${t}_LINKER_FLAGS_RELWITHDEBINFO_INIT "/debug /pdbtype:sept ${MSVC_INCREMENTAL_YES_FLAG}")
+    string(APPEND CMAKE_${t}_LINKER_FLAGS_RELWITHDEBINFO_INIT " /debug /pdbtype:sept ${MSVC_INCREMENTAL_YES_FLAG}")
   else ()
-    set(CMAKE_${t}_LINKER_FLAGS_DEBUG_INIT "/debug ${MSVC_INCREMENTAL_YES_FLAG}")
+    string(APPEND CMAKE_${t}_LINKER_FLAGS_DEBUG_INIT " /debug ${MSVC_INCREMENTAL_YES_FLAG}")
-    set(CMAKE_${t}_LINKER_FLAGS_RELWITHDEBINFO_INIT "/debug ${MSVC_INCREMENTAL_YES_FLAG}")
+    string(APPEND CMAKE_${t}_LINKER_FLAGS_RELWITHDEBINFO_INIT " /debug ${MSVC_INCREMENTAL_YES_FLAG}")
   endif ()
   # for release and minsize release default to no incremental linking
-  set(CMAKE_${t}_LINKER_FLAGS_MINSIZEREL_INIT "/INCREMENTAL:NO")
+  string(APPEND CMAKE_${t}_LINKER_FLAGS_MINSIZEREL_INIT " /INCREMENTAL:NO")
-  set(CMAKE_${t}_LINKER_FLAGS_RELEASE_INIT "/INCREMENTAL:NO")
+  string(APPEND CMAKE_${t}_LINKER_FLAGS_RELEASE_INIT " /INCREMENTAL:NO")
 endforeach()
 
 string(APPEND CMAKE_STATIC_LINKER_FLAGS_INIT " ${_MACHINE_ARCH_FLAG}")

Modules/Platform/Windows-OpenWatcom.cmake

@@ -32,14 +32,14 @@ else()
   set(CMAKE_LIB_QUIET "-q")
 endif()
 
-set(CMAKE_EXE_LINKER_FLAGS_INIT)
+string(APPEND CMAKE_EXE_LINKER_FLAGS_INIT " ")
 set(CMAKE_CREATE_WIN32_EXE "system nt_win" )
 set(CMAKE_CREATE_CONSOLE_EXE "system nt" )
-set(CMAKE_SHARED_LINKER_FLAGS_INIT "system nt_dll")
+string(APPEND CMAKE_SHARED_LINKER_FLAGS_INIT " system nt_dll")
-set(CMAKE_MODULE_LINKER_FLAGS_INIT "system nt_dll")
+string(APPEND CMAKE_MODULE_LINKER_FLAGS_INIT " system nt_dll")
 foreach(type SHARED MODULE EXE)
-  set(CMAKE_${type}_LINKER_FLAGS_DEBUG_INIT "debug all opt map")
+  string(APPEND CMAKE_${type}_LINKER_FLAGS_DEBUG_INIT " debug all opt map")
-  set(CMAKE_${type}_LINKER_FLAGS_RELWITHDEBINFO_INIT "debug all opt map")
+  string(APPEND CMAKE_${type}_LINKER_FLAGS_RELWITHDEBINFO_INIT " debug all opt map")
 endforeach()
 
 set(CMAKE_C_COMPILE_OPTIONS_DLL "-bd") # Note: This variable is a ';' separated list

Tests/RunCMake/ToolchainFile/LinkFlagsInit-stdout.txt

@@ -0,0 +1,60 @@
+-- CMAKE_EXE_LINKER_FLAGS='[^
+]*MY_EXE_FLAGS_INIT[^
+]*'
+-- CMAKE_EXE_LINKER_FLAGS_DEBUG='[^
+]*MY_EXE_FLAGS_DEBUG_INIT[^
+]*'
+-- CMAKE_EXE_LINKER_FLAGS_RELEASE='[^
+]*MY_EXE_FLAGS_RELEASE_INIT[^
+]*'
+-- CMAKE_EXE_LINKER_FLAGS_MINSIZEREL='[^
+]*MY_EXE_FLAGS_MINSIZEREL_INIT[^
+]*'
+-- CMAKE_EXE_LINKER_FLAGS_RELWITHDEBINFO='[^
+]*MY_EXE_FLAGS_RELWITHDEBINFO_INIT[^
+]*'
+-- CMAKE_SHARED_LINKER_FLAGS='[^
+]*MY_SHARED_FLAGS_INIT[^
+]*'
+-- CMAKE_SHARED_LINKER_FLAGS_DEBUG='[^
+]*MY_SHARED_FLAGS_DEBUG_INIT[^
+]*'
+-- CMAKE_SHARED_LINKER_FLAGS_RELEASE='[^
+]*MY_SHARED_FLAGS_RELEASE_INIT[^
+]*'
+-- CMAKE_SHARED_LINKER_FLAGS_MINSIZEREL='[^
+]*MY_SHARED_FLAGS_MINSIZEREL_INIT[^
+]*'
+-- CMAKE_SHARED_LINKER_FLAGS_RELWITHDEBINFO='[^
+]*MY_SHARED_FLAGS_RELWITHDEBINFO_INIT[^
+]*'
+-- CMAKE_MODULE_LINKER_FLAGS='[^
+]*MY_MODULE_FLAGS_INIT[^
+]*'
+-- CMAKE_MODULE_LINKER_FLAGS_DEBUG='[^
+]*MY_MODULE_FLAGS_DEBUG_INIT[^
+]*'
+-- CMAKE_MODULE_LINKER_FLAGS_RELEASE='[^
+]*MY_MODULE_FLAGS_RELEASE_INIT[^
+]*'
+-- CMAKE_MODULE_LINKER_FLAGS_MINSIZEREL='[^
+]*MY_MODULE_FLAGS_MINSIZEREL_INIT[^
+]*'
+-- CMAKE_MODULE_LINKER_FLAGS_RELWITHDEBINFO='[^
+]*MY_MODULE_FLAGS_RELWITHDEBINFO_INIT[^
+]*'
+-- CMAKE_STATIC_LINKER_FLAGS='[^
+]*MY_STATIC_FLAGS_INIT[^
+]*'
+-- CMAKE_STATIC_LINKER_FLAGS_DEBUG='[^
+]*MY_STATIC_FLAGS_DEBUG_INIT[^
+]*'
+-- CMAKE_STATIC_LINKER_FLAGS_RELEASE='[^
+]*MY_STATIC_FLAGS_RELEASE_INIT[^
+]*'
+-- CMAKE_STATIC_LINKER_FLAGS_MINSIZEREL='[^
+]*MY_STATIC_FLAGS_MINSIZEREL_INIT[^
+]*'
+-- CMAKE_STATIC_LINKER_FLAGS_RELWITHDEBINFO='[^
+]*MY_STATIC_FLAGS_RELWITHDEBINFO_INIT[^
+]*'

Tests/RunCMake/ToolchainFile/LinkFlagsInit-toolchain.cmake

@@ -0,0 +1,5 @@
+foreach(t EXE SHARED MODULE STATIC)
+  foreach(c "" _DEBUG _RELEASE _MINSIZEREL _RELWITHDEBINFO)
+    set(CMAKE_${t}_LINKER_FLAGS${c}_INIT MY_${t}_FLAGS${c}_INIT)
+  endforeach()
+endforeach()

Tests/RunCMake/ToolchainFile/LinkFlagsInit.cmake

@@ -0,0 +1,7 @@
+set(CMAKE_C_COMPILER_FORCED 1) # skip compiler test so we can check cached values
+enable_language(C)
+foreach(t EXE SHARED MODULE STATIC)
+  foreach(c "" _DEBUG _RELEASE _MINSIZEREL _RELWITHDEBINFO)
+    message(STATUS "CMAKE_${t}_LINKER_FLAGS${c}='${CMAKE_${t}_LINKER_FLAGS${c}}'")
+  endforeach()
+endforeach()

Tests/RunCMake/ToolchainFile/RunCMakeTest.cmake

@@ -8,3 +8,4 @@ endfunction()
 run_cmake_toolchain(CallEnableLanguage)
 run_cmake_toolchain(CallProject)
 run_cmake_toolchain(FlagsInit)
+run_cmake_toolchain(LinkFlagsInit)