Help Check*CompilerFlag harmonize text

This is like recently done for Check*Source{Compiles,Runs}

6 files changed, 98 insertions, 75 deletions

diff --git a/Modules/CheckCCompilerFlag.cmake b/Modules/CheckCCompilerFlag.cmake
index 696f7a3..0a658c4 100644
--- a/Modules/CheckCCompilerFlag.cmake
+++ b/Modules/CheckCCompilerFlag.cmake
@@ -5,7 +5,7 @@
 CheckCCompilerFlag
 ------------------
 
-Check whether the C compiler supports a given flag.
+Check once whether the C compiler supports a given flag.
 
 .. command:: check_c_compiler_flag
 
@@ -13,24 +13,25 @@ Check whether the C compiler supports a given flag.
 
     check_c_compiler_flag(<flag> <resultVar>)
 
-  Check that the ``<flag>`` is accepted by the compiler without
-  a diagnostic.  Stores the result in an internal cache entry
-  named ``<resultVar>``.
+Check once that the ``<flag>`` is accepted by the compiler without a diagnostic.
+The result is stored in the internal cache variable specified by
+``<resultVar>``, with boolean ``true`` for success and boolean ``false`` for
+failure.
 
-A positive result from this check indicates only that the compiler did not
-issue a diagnostic message when given the flag.  Whether the flag has any
-effect or even a specific one is beyond the scope of this module.
+``true`` indicates only that the compiler did not issue a diagnostic message
+when given the flag. Whether the flag has any effect is beyond the scope of
+this module.
 
-The check is only performed once, with the result cached in the variable named
-by ``<resultVar>``. Every subsequent CMake run will reuse this cached value
-rather than performing the check again, even if the ``<code>`` changes. In
-order to force the check to be re-evaluated, the variable named by
-``<resultVar>`` must be manually removed from the cache.
+Internally, :command:`try_compile` is used to perform the check. If
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
+the check compiles and links an executable program. If set to
+``STATIC_LIBRARY``, the check is compiled but not linked.
 
 See also :command:`check_compiler_flag` for a more general command syntax.
 
 The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_c_compiler_flag()``
+following variables prior to calling ``check_c_compiler_flag()``. Unknown flags
+in these variables can case a false negative result.
 
 .. include:: /module/CMAKE_REQUIRED_FLAGS.txt
 
diff --git a/Modules/CheckCXXCompilerFlag.cmake b/Modules/CheckCXXCompilerFlag.cmake
index 90cd488..1465b9f 100644
--- a/Modules/CheckCXXCompilerFlag.cmake
+++ b/Modules/CheckCXXCompilerFlag.cmake
@@ -5,7 +5,7 @@
 CheckCXXCompilerFlag
 ------------------------
 
-Check whether the CXX compiler supports a given flag.
+Check once whether the CXX compiler supports a given flag.
 
 .. command:: check_cxx_compiler_flag
 
@@ -13,20 +13,37 @@ Check whether the CXX compiler supports a given flag.
 
     check_cxx_compiler_flag(<flag> <var>)
 
-  Check that the ``<flag>`` is accepted by the compiler without
-  a diagnostic.  Stores the result in an internal cache entry
-  named ``<var>``.
+Check once that the ``<flag>`` is accepted by the compiler without a diagnostic.
+The result is stored in the internal cache variable specified by
+``<resultVar>``, with boolean ``true`` for success and boolean ``false`` for
+failure.
 
-A positive result from this check indicates only that the compiler did not
-issue a diagnostic message when given the flag.  Whether the flag has any
-effect or even a specific one is beyond the scope of this module.
+``true`` indicates only that the compiler did not issue a diagnostic message
+when given the flag. Whether the flag has any effect is beyond the scope of
+this module.
+
+Internally, :command:`try_compile` is used to perform the check. If
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
+the check compiles and links an executable program. If set to
+``STATIC_LIBRARY``, the check is compiled but not linked.
 
 See also :command:`check_compiler_flag` for a more general command syntax.
 
-.. note::
-  Since the :command:`try_compile` command forwards flags from variables
-  like :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`, unknown flags
-  in such variables may cause a false negative for this check.
+The compile and link commands can be influenced by setting any of the
+following variables prior to calling ``check_cxx_compiler_flag()``. Unknown flags
+in these variables can case a false negative result.
+
+.. include:: /module/CMAKE_REQUIRED_FLAGS.txt
+
+.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt
+
+.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt
+
+.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt
+
+.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt
+
+.. include:: /module/CMAKE_REQUIRED_QUIET.txt
 #]=======================================================================]
 
 include_guard(GLOBAL)
diff --git a/Modules/CheckCompilerFlag.cmake b/Modules/CheckCompilerFlag.cmake
index 0f2ec4c..6252767 100644
--- a/Modules/CheckCompilerFlag.cmake
+++ b/Modules/CheckCompilerFlag.cmake
@@ -7,7 +7,7 @@ CheckCompilerFlag
 
 .. versionadded:: 3.19
 
-Check whether the compiler supports a given flag.
+Check once whether the ``<lang>`` compiler supports a given flag.
 
 .. command:: check_compiler_flag
 
@@ -15,21 +15,23 @@ Check whether the compiler supports a given flag.
 
     check_compiler_flag(<lang> <flag> <resultVar>)
 
-Check that the ``<flag>`` is accepted by the compiler without a diagnostic.
-Stores the result in an internal cache entry named ``<resultVar>``.
+Check once that the ``<flag>`` is accepted by the ``<lang>`` compiler without
+a diagnostic. The result is stored in the internal cache variable specified by
+``<resultVar>``, with boolean ``true`` for success and boolean ``false`` for
+failure.
 
-A positive result from this check indicates only that the compiler did not
-issue a diagnostic message when given the flag.  Whether the flag has any
-effect or even a specific one is beyond the scope of this module.
+``true`` indicates only that the compiler did not issue a diagnostic message
+when given the flag. Whether the flag has any effect is beyond the scope of
+this module.
 
-The check is only performed once, with the result cached in the variable named
-by ``<resultVar>``. Every subsequent CMake run will reuse this cached value
-rather than performing the check again, even if the ``<code>`` changes. In
-order to force the check to be re-evaluated, the variable named by
-``<resultVar>`` must be manually removed from the cache.
+Internally, :command:`try_compile` is used to perform the check. If
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
+the check compiles and links an executable program. If set to
+``STATIC_LIBRARY``, the check is compiled but not linked.
 
 The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_compiler_flag()``
+following variables prior to calling ``check_compiler_flag()``. Unknown flags
+in these variables can case a false negative result.
 
 .. include:: /module/CMAKE_REQUIRED_FLAGS.txt
 
diff --git a/Modules/CheckFortranCompilerFlag.cmake b/Modules/CheckFortranCompilerFlag.cmake
index 94090ef..7ab1247 100644
--- a/Modules/CheckFortranCompilerFlag.cmake
+++ b/Modules/CheckFortranCompilerFlag.cmake
@@ -7,7 +7,7 @@ CheckFortranCompilerFlag
 
 .. versionadded:: 3.3
 
-Check whether the Fortran compiler supports a given flag.
+Check once whether the Fortran compiler supports a given flag.
 
 .. command:: check_fortran_compiler_flag
 
@@ -15,24 +15,25 @@ Check whether the Fortran compiler supports a given flag.
 
     check_fortran_compiler_flag(<flag> <resultVar>)
 
-  Check that the ``<flag>`` is accepted by the compiler without
-  a diagnostic.  Stores the result in an internal cache entry
-  named ``<resultVar>``.
+Check once that the ``<flag>`` is accepted by the compiler without a diagnostic.
+The result is stored in the internal cache variable specified by
+``<resultVar>``, with boolean ``true`` for success and boolean ``false`` for
+failure.
 
-A positive result from this check indicates only that the compiler did not
-issue a diagnostic message when given the flag.  Whether the flag has any
-effect or even a specific one is beyond the scope of this module.
+``true`` indicates only that the compiler did not issue a diagnostic message
+when given the flag. Whether the flag has any effect is beyond the scope of
+this module.
 
-The check is only performed once, with the result cached in the variable named
-by ``<resultVar>``. Every subsequent CMake run will reuse this cached value
-rather than performing the check again, even if the ``<code>`` changes. In
-order to force the check to be re-evaluated, the variable named by
-``<resultVar>`` must be manually removed from the cache.
+Internally, :command:`try_compile` is used to perform the check. If
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
+the check compiles and links an executable program. If set to
+``STATIC_LIBRARY``, the check is compiled but not linked.
 
 See also :command:`check_compiler_flag` for a more general command syntax.
 
 The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_fortran_compiler_flag()``
+following variables prior to calling ``check_fortran_compiler_flag()``. Unknown
+flags in these variables can case a false negative result.
 
 .. include:: /module/CMAKE_REQUIRED_FLAGS.txt
 
diff --git a/Modules/CheckOBJCCompilerFlag.cmake b/Modules/CheckOBJCCompilerFlag.cmake
index f87949b..102b137 100644
--- a/Modules/CheckOBJCCompilerFlag.cmake
+++ b/Modules/CheckOBJCCompilerFlag.cmake
@@ -7,7 +7,7 @@ CheckOBJCCompilerFlag
 
 .. versionadded:: 3.16
 
-Check whether the Objective-C compiler supports a given flag.
+Check once whether the Objective-C compiler supports a given flag.
 
 .. command:: check_objc_compiler_flag
 
@@ -15,24 +15,25 @@ Check whether the Objective-C compiler supports a given flag.
 
     check_objc_compiler_flag(<flag> <resultVar>)
 
-  Check that the ``<flag>`` is accepted by the compiler without
-  a diagnostic.  Stores the result in an internal cache entry
-  named ``<resultVar>``.
+Check once that the ``<flag>`` is accepted by the compiler without a diagnostic.
+The result is stored in the internal cache variable specified by
+``<resultVar>``, with boolean ``true`` for success and boolean ``false`` for
+failure.
 
-A positive result from this check indicates only that the compiler did not
-issue a diagnostic message when given the flag.  Whether the flag has any
-effect or even a specific one is beyond the scope of this module.
+``true`` indicates only that the compiler did not issue a diagnostic message
+when given the flag. Whether the flag has any effect is beyond the scope of
+this module.
 
-The check is only performed once, with the result cached in the variable named
-by ``<resultVar>``. Every subsequent CMake run will reuse this cached value
-rather than performing the check again, even if the ``<code>`` changes. In
-order to force the check to be re-evaluated, the variable named by
-``<resultVar>`` must be manually removed from the cache.
+Internally, :command:`try_compile` is used to perform the check. If
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
+the check compiles and links an executable program. If set to
+``STATIC_LIBRARY``, the check is compiled but not linked.
 
 See also :command:`check_compiler_flag` for a more general command syntax.
 
 The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_objc_compiler_flag()``
+following variables prior to calling ``check_objc_compiler_flag()``. Unknown
+flags in these variables can case a false negative result.
 
 .. include:: /module/CMAKE_REQUIRED_FLAGS.txt
 
diff --git a/Modules/CheckOBJCXXCompilerFlag.cmake b/Modules/CheckOBJCXXCompilerFlag.cmake
index 5091a75..21daa5c 100644
--- a/Modules/CheckOBJCXXCompilerFlag.cmake
+++ b/Modules/CheckOBJCXXCompilerFlag.cmake
@@ -7,7 +7,7 @@ CheckOBJCXXCompilerFlag
 
 .. versionadded:: 3.16
 
-Check whether the Objective-C++ compiler supports a given flag.
+Check once whether the Objective-C++ compiler supports a given flag.
 
 .. command:: check_objcxx_compiler_flag
 
@@ -15,24 +15,25 @@ Check whether the Objective-C++ compiler supports a given flag.
 
     check_objcxx_compiler_flag(<flag> <resultVar>)
 
-  Check that the ``<flag>`` is accepted by the compiler without
-  a diagnostic.  Stores the result in an internal cache entry
-  named ``<resultVar>``.
+Check once that the ``<flag>`` is accepted by the compiler without a diagnostic.
+The result is stored in the internal cache variable specified by
+``<resultVar>``, with boolean ``true`` for success and boolean ``false`` for
+failure.
 
-A positive result from this check indicates only that the compiler did not
-issue a diagnostic message when given the flag.  Whether the flag has any
-effect or even a specific one is beyond the scope of this module.
+``true`` indicates only that the compiler did not issue a diagnostic message
+when given the flag. Whether the flag has any effect is beyond the scope of
+this module.
 
-The check is only performed once, with the result cached in the variable named
-by ``<resultVar>``. Every subsequent CMake run will reuse this cached value
-rather than performing the check again, even if the ``<code>`` changes. In
-order to force the check to be re-evaluated, the variable named by
-``<resultVar>`` must be manually removed from the cache.
+Internally, :command:`try_compile` is used to perform the check. If
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
+the check compiles and links an executable program. If set to
+``STATIC_LIBRARY``, the check is compiled but not linked.
 
 See also :command:`check_compiler_flag` for a more general command syntax.
 
 The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_objcxx_compiler_flag()``
+following variables prior to calling ``check_objcxx_compiler_flag()``. Unknown
+flags in these variables can case a false negative result.
 
 .. include:: /module/CMAKE_REQUIRED_FLAGS.txt