Help: Clarify how language-specific flag environment values are used

Previous the wording could be interpreted to mean that the environment
variables like `CXXFLAGS` are used exclusively to initialize the
corresponding cache entries like `CMAKE_CXX_FLAGS`.  State clearly
that the value will be used in combination with builtin defaults.

Issue: #23956

11 files changed, 66 insertions, 57 deletions

diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst
index 2e1c6d2948..2af4b58576 100644
--- a/Help/envvar/ASM_DIALECTFLAGS.rst
+++ b/Help/envvar/ASM_DIALECTFLAGS.rst
@@ -3,13 +3,16 @@ ASM<DIALECT>FLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling a specific dialect of an
-assembly language. ``ASM<DIALECT>FLAGS`` can be ``ASMFLAGS``, ``ASM_NASMFLAGS``,
-``ASM_MASMFLAGS`` or ``ASM-ATTFLAGS``. Will only be used by CMake on the
-first configuration to determine ``ASM_<DIALECT>`` default compilation
-flags, after which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache
-as ``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>``.  For any configuration
-run (including the first), the environment variable will be ignored, if the
-``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`` variable is defined.
+Add default compilation flags to be used when compiling a specific dialect
+of an assembly language.  ``ASM<DIALECT>FLAGS`` can be one of:
+
+* ``ASMFLAGS``
+* ``ASM_NASMFLAGS``
+* ``ASM_MASMFLAGS``
+* ``ASM-ATTFLAGS``
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``ASM<DIALECT>``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_ASM<DIALECT>_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/CFLAGS.rst b/Help/envvar/CFLAGS.rst
index 190b4f47c8..a6b2452075 100644
--- a/Help/envvar/CFLAGS.rst
+++ b/Help/envvar/CFLAGS.rst
@@ -3,11 +3,10 @@ CFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``C`` files. Will only be
-used by CMake on the first configuration to determine ``CC`` default compilation
-flags, after which the value for ``CFLAGS`` is stored in the cache
-as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run
-(including the first), the environment variable will be ignored if the
-:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``C`` files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``C``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/CSFLAGS.rst b/Help/envvar/CSFLAGS.rst
index 784328a735..6e909fe4b1 100644
--- a/Help/envvar/CSFLAGS.rst
+++ b/Help/envvar/CSFLAGS.rst
@@ -5,11 +5,10 @@ CSFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``CSharp`` files. Will only be
-used by CMake on the first configuration to determine ``CSharp`` default
-compilation flags, after which the value for ``CSFLAGS`` is stored in the cache
-as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
-run (including the first), the environment variable will be ignored if the
-:variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``CSharp`` files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``CSharp``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_CSharp_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/CUDAFLAGS.rst b/Help/envvar/CUDAFLAGS.rst
index af577a0a60..46a91df86d 100644
--- a/Help/envvar/CUDAFLAGS.rst
+++ b/Help/envvar/CUDAFLAGS.rst
@@ -5,11 +5,10 @@ CUDAFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``CUDA`` files. Will only be
-used by CMake on the first configuration to determine ``CUDA`` default
-compilation flags, after which the value for ``CUDAFLAGS`` is stored in the
-cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
-run (including the first), the environment variable will be ignored if
-the :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``CUDA`` files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``CUDA``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_CUDA_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/CXXFLAGS.rst b/Help/envvar/CXXFLAGS.rst
index 460a347c54..f67431f0a5 100644
--- a/Help/envvar/CXXFLAGS.rst
+++ b/Help/envvar/CXXFLAGS.rst
@@ -3,11 +3,10 @@ CXXFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``CXX`` (C++) files. Will
-only be used by CMake on the first configuration to determine ``CXX`` default
-compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache
-as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run (
-including the first), the environment variable will be ignored if
-the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``CXX`` (C++) files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``CXX``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_CXX_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/FFLAGS.rst b/Help/envvar/FFLAGS.rst
index 53bffb67f6..23bc8d2648 100644
--- a/Help/envvar/FFLAGS.rst
+++ b/Help/envvar/FFLAGS.rst
@@ -3,11 +3,10 @@ FFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``Fortran`` files. Will only
-be used by CMake on the first configuration to determine ``Fortran`` default
-compilation flags, after which the value for ``FFLAGS`` is stored in the cache
-as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
-run (including the first), the environment variable will be ignored if
-the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``Fortran`` files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``Fortran``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_Fortran_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/HIPFLAGS.rst b/Help/envvar/HIPFLAGS.rst
index 0df3416e28..31e2390534 100644
--- a/Help/envvar/HIPFLAGS.rst
+++ b/Help/envvar/HIPFLAGS.rst
@@ -5,11 +5,10 @@ HIPFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``HIP`` files. Will only be
-used by CMake on the first configuration to determine ``HIP`` default
-compilation flags, after which the value for ``HIPFLAGS`` is stored in the
-cache as :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
-run (including the first), the environment variable will be ignored if
-the :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``HIP`` files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``HIP``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_HIP_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/ISPCFLAGS.rst b/Help/envvar/ISPCFLAGS.rst
index 21df037758..b7a2bd5958 100644
--- a/Help/envvar/ISPCFLAGS.rst
+++ b/Help/envvar/ISPCFLAGS.rst
@@ -5,11 +5,10 @@ ISPCFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``ISPC`` files. Will only be
-used by CMake on the first configuration to determine ``ISPC`` default
-compilation flags, after which the value for ``ISPCFLAGS`` is stored in the
-cache as :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
-run (including the first), the environment variable will be ignored if
-the :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``ISPC`` files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``ISPC``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_ISPC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/envvar/LANG_FLAGS.txt b/Help/envvar/LANG_FLAGS.txt
new file mode 100644
index 0000000000..d01a56d2f2
--- /dev/null
+++ b/Help/envvar/LANG_FLAGS.txt
@@ -0,0 +1,6 @@
+CMake uses this environment variable value, in combination with its own
+builtin default flags for the toolchain, to initialize and store the
+|CMAKE_LANG_FLAGS| cache entry.
+This occurs the first time a build tree is configured for language |LANG|.
+For any configuration run (including the first), the environment variable
+will be ignored if the |CMAKE_LANG_FLAGS| variable is already defined.
diff --git a/Help/envvar/RCFLAGS.rst b/Help/envvar/RCFLAGS.rst
index bc43cb212c..7df83a72ce 100644
--- a/Help/envvar/RCFLAGS.rst
+++ b/Help/envvar/RCFLAGS.rst
@@ -3,11 +3,10 @@ RCFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``resource`` files. Will
-only be used by CMake on the first configuration to determine ``resource``
-default compilation flags, after which the value for ``RCFLAGS`` is stored in
-the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any
-configuration run (including the first), the environment variable will be ignored
-if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+Add default compilation flags to be used when compiling ``RC`` (resource) files.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``RC``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_RC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.
diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst
index 2784397ac2..4b39b1deff 100644
--- a/Help/variable/CMAKE_LANG_FLAGS.rst
+++ b/Help/variable/CMAKE_LANG_FLAGS.rst
@@ -5,7 +5,9 @@ Flags for all build types.
 
 ``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`.
 
-This is initialized for each language from environment variables:
+For each language, if this variable is not defined, it is initialized
+and stored in the cache using values from environment variables in
+combination with CMake's builtin defaults for the toolchain:
 
 * ``CMAKE_C_FLAGS``:
   Initialized by the :envvar:`CFLAGS` environment variable.
@@ -15,6 +17,12 @@ This is initialized for each language from environment variables:
   Initialized by the :envvar:`CUDAFLAGS` environment variable.
 * ``CMAKE_Fortran_FLAGS``:
   Initialized by the :envvar:`FFLAGS` environment variable.
+* ``CMAKE_CSharp_FLAGS``:
+  Initialized by the :envvar:`CSFLAGS` environment variable.
+* ``CMAKE_HIP_FLAGS``:
+  Initialized by the :envvar:`HIPFLAGS` environment variable.
+* ``CMAKE_ISPC_FLAGS``:
+  Initialized by the :envvar:`ISPCFLAGS` environment variable.
 
 This value is a command-line string fragment. Therefore, multiple options
 should be separated by spaces, and options with spaces should be quoted.