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.

10 files changed, 101 insertions, 0 deletions

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index e134a1a..1138b82 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/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
diff --git a/Help/release/dev/toolchain-flag-init.rst b/Help/release/dev/toolchain-flag-init.rst
index 251484b..37e363d 100644
--- a/Help/release/dev/toolchain-flag-init.rst
+++ b/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.
diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst
new file mode 100644
index 0000000..592a369
--- /dev/null
+++ b/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`.
diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst
new file mode 100644
index 0000000..0b8afe4
--- /dev/null
+++ b/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`.
diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst
new file mode 100644
index 0000000..3279014
--- /dev/null
+++ b/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`.
diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst
new file mode 100644
index 0000000..91b39f6
--- /dev/null
+++ b/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`.
diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst
new file mode 100644
index 0000000..185df38
--- /dev/null
+++ b/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`.
diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst
new file mode 100644
index 0000000..cb819a7
--- /dev/null
+++ b/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`.
diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst
new file mode 100644
index 0000000..a49d1cb
--- /dev/null
+++ b/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`.
diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst
new file mode 100644
index 0000000..113ca71
--- /dev/null
+++ b/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`.