Honor CMAKE_<LANG>_FLAGS[_<CONFIG>]_INIT set in toolchain files

Document these variables.

Change our convention for setting these variables from:

    set(CMAKE_C_FLAGS_INIT "...")

to

    string(APPEND CMAKE_C_FLAGS_INIT " ...")

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

Automate the conversion with:

    sed -i 's/set *(\(CMAKE_\(C\|CXX\|Fortran\|RC\|ASM\|${[^}]\+}\)_FLAGS\(_[^_]\+\)\?_INIT \+"\)/string(APPEND \1 /' \
      Modules/Compiler/*.cmake Modules/Platform/*.cmake

and follow up with some manual fixes (e.g. to cases that already
meant to append).  Also revert the automated changes to contexts
that are not protected from running multiple times.

8 files changed, 71 insertions, 2 deletions

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 36d00dc..e134a1a 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -344,10 +344,15 @@ Variables for Languages
    /variable/CMAKE_LANG_CREATE_SHARED_MODULE
    /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY
    /variable/CMAKE_LANG_FLAGS_DEBUG
+   /variable/CMAKE_LANG_FLAGS_DEBUG_INIT
    /variable/CMAKE_LANG_FLAGS_MINSIZEREL
+   /variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT
    /variable/CMAKE_LANG_FLAGS_RELEASE
+   /variable/CMAKE_LANG_FLAGS_RELEASE_INIT
    /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
+   /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
    /variable/CMAKE_LANG_FLAGS
+   /variable/CMAKE_LANG_FLAGS_INIT
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE
diff --git a/Help/release/dev/toolchain-flag-init.rst b/Help/release/dev/toolchain-flag-init.rst
new file mode 100644
index 0000000..251484b
--- /dev/null
+++ b/Help/release/dev/toolchain-flag-init.rst
@@ -0,0 +1,7 @@
+toolchain-flag-init
+-------------------
+
+* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set a
+  :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.
diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst
new file mode 100644
index 0000000..dcddb2e
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst
@@ -0,0 +1,10 @@
+CMAKE_<LANG>_FLAGS_DEBUG_INIT
+-----------------------------
+
+Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_DEBUG` cache
+entry the first time a build tree is configured for language ``<LANG>``.
+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_<LANG>_FLAGS_INIT`.
diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst
new file mode 100644
index 0000000..1d32cc3
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst
@@ -0,0 +1,15 @@
+CMAKE_<LANG>_FLAGS_INIT
+-----------------------
+
+Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS` cache entry
+the first time a build tree is configured for language ``<LANG>``.
+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 variables:
+
+* :variable:`CMAKE_<LANG>_FLAGS_DEBUG_INIT`
+* :variable:`CMAKE_<LANG>_FLAGS_RELEASE_INIT`
+* :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT`
+* :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT`
diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst
new file mode 100644
index 0000000..c0aedf4
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst
@@ -0,0 +1,10 @@
+CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT
+----------------------------------
+
+Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL`
+cache entry the first time a build tree is configured for language ``<LANG>``.
+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_<LANG>_FLAGS_INIT`.
diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst
new file mode 100644
index 0000000..59f92ff
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst
@@ -0,0 +1,10 @@
+CMAKE_<LANG>_FLAGS_RELEASE_INIT
+-------------------------------
+
+Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELEASE`
+cache entry the first time a build tree is configured for language ``<LANG>``.
+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_<LANG>_FLAGS_INIT`.
diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst
new file mode 100644
index 0000000..915f023
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst
@@ -0,0 +1,10 @@
+CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT
+--------------------------------------
+
+Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO`
+cache entry the first time a build tree is configured for language ``<LANG>``.
+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_<LANG>_FLAGS_INIT`.
diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst
index 9af0d97..622278e 100644
--- a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst
+++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst
@@ -14,8 +14,10 @@ variables that must be set before CMake builds its first test project
 to check that the compiler for a language works.  It should not be
 used to load a file in cases that a normal :command:`include` will work.  Use
 it only as a last resort for behavior that cannot be achieved any
-other way.  For example, one may set ``CMAKE_C_FLAGS_INIT`` to change the
-default value used to initialize :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`
+other way.  For example, one may set the
+:variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>` variable
+to change the default value used to initialize the
+:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable
 before it is cached.  The override file should NOT be used to set anything
 that could be set after languages are enabled, such as variables like
 :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY` that affect the placement of