Check{,C,CXX,Fortran,OBJC,OBJCXX}CompilerFlag: Update documentation

- Added intro code blocks showing how to include these modules.
- Used word "command" instead of "macro".
- Added examples sections.
- Updated and synced descriptions of commands and arguments.
- Added a rubric title for variables that affect the checks.
- Listed CMAKE_TRY_COMPILE_TARGET_TYPE variable in the rubric together
  with CMAKE_REQUIRED_* variables.
- Added link to CheckCompilerFlag module in the target_compile_options()
  docs.
- Used lowercase style for check_fortran_compiler_flag() command.
- Added a link to `$<COMPILE_LANGUAGE:languages>` generator expression
  so it can be linked from other pages (See commit
  2e37a20f02 for more info on the initial
  style used).
- Fixed the GENEX_NOTE inclusion (starting with line after the 2nd line)
  where part of the sentence was rendered in the output.

Help/command/add_compile_options.rst

@@ -41,7 +41,8 @@ this command is in a compiler-specific conditional clause:
   endif()
 
 To set per-language options, use the :genex:`$<COMPILE_LANGUAGE>`
-or :genex:`$<COMPILE_LANGUAGE:languages>` generator expressions.
+or :genex:`$<COMPILE_LANGUAGE:languages> <COMPILE_LANGUAGE:languages>`
+generator expressions.
 
 See Also
 ^^^^^^^^

Help/command/target_compile_features.rst

@@ -34,7 +34,7 @@ The named ``<target>`` must have been created by a command such as
 .. |more_see_also| replace:: See the :manual:`cmake-compile-features(7)`
    manual for information on compile features and a list of supported compilers.
 .. include:: include/GENEX_NOTE.rst
-   :start-line: 1
+   :start-line: 2
 
 See Also
 ^^^^^^^^

Help/command/target_compile_options.rst

@@ -69,3 +69,6 @@ See Also
 * :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
   add language-wide flags passed to all invocations of the compiler.
   This includes invocations that drive compiling and those that drive linking.
+
+* The :module:`CheckCompilerFlag` module to check whether the compiler
+  supports a given flag.

Help/command/target_precompile_headers.rst

@@ -71,7 +71,8 @@ included by absolute path.  For example:
   )
 
 .. |command_name| replace:: ``target_precompile_headers``
-.. |more_see_also| replace:: The :genex:`$<COMPILE_LANGUAGE:...>` generator
+.. |more_see_also| replace:: The :genex:`$<COMPILE_LANGUAGE:...>
+   <COMPILE_LANGUAGE:languages>` generator
    expression is particularly useful for specifying a language-specific header
    to precompile for only one language (e.g. ``CXX`` and not ``C``).  In this
    case, header file names that are not explicitly in double quotes or angle
@@ -79,7 +80,7 @@ included by absolute path.  For example:
    brackets inside a generator expression, be sure to encode the closing
    ``>`` as :genex:`$<ANGLE-R>`.  For example:
 .. include:: include/GENEX_NOTE.rst
-   :start-line: 1
+   :start-line: 2
 
 .. code-block:: cmake
 

Help/manual/cmake-generator-expressions.7.rst

@@ -1288,14 +1288,12 @@ related to most of the expressions in this sub-section.
   .. versionadded:: 3.3
 
   The compile language of source files when evaluating compile options.
-  See :ref:`the related boolean expression
-  <Boolean COMPILE_LANGUAGE Generator Expression>`
-  ``$<COMPILE_LANGUAGE:language>``
+  See the related boolean expression
+  :genex:`$<COMPILE_LANGUAGE:languages> <COMPILE_LANGUAGE:languages>`
   for notes about the portability of this generator expression.
 
-.. _`Boolean COMPILE_LANGUAGE Generator Expression`:
-
 .. genex:: $<COMPILE_LANGUAGE:languages>
+  :target: COMPILE_LANGUAGE:languages
 
   .. versionadded:: 3.3
 

Modules/CheckCCompilerFlag.cmake

@@ -5,33 +5,51 @@
 CheckCCompilerFlag
 ------------------
 
-Check once whether the C compiler supports a given flag.
+This module provides a command to check whether the C compiler supports a
+given flag.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCCompilerFlag)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_c_compiler_flag
 
+  Checks once whether the C compiler supports a given flag:
+
   .. code-block:: cmake
 
-    check_c_compiler_flag(<flag> <resultVar>)
+    check_c_compiler_flag(<flag> <variable>)
 
-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.
+  This command checks once that the ``<flag>`` is accepted by the C compiler
+  without producing a diagnostic message.  Multiple flags can be specified
+  in one argument as a string using a :ref:`semicolon-separated list
+  <CMake Language Lists>`.
 
-``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 result of the check is stored in the internal cache variable specified
+  by ``<variable>``, with boolean true for success and boolean false for
+  failure.
 
-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.
+  A successful result only indicates that the compiler did not report an
+  error when given the flag.  Whether the flag has any effect, or the
+  intended one, is outside the scope of this module.
 
-See also :command:`check_compiler_flag` for a more general command syntax.
+  .. note::
 
-The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_c_compiler_flag()``. Unknown flags
-in these variables can case a false negative result.
+    Since the underlying :command:`try_compile` command also uses flags from
+    variables like :variable:`CMAKE_<LANG>_FLAGS`, unknown or unsupported
+    flags in those variables may result in a false negative for this check.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -47,6 +65,37 @@ in these variables can case a false negative result.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+The following example demonstrates how to use this module to check support
+for the C compiler flag ``-fno-optimize-strlen``, which disables
+optimizations related to the ``strlen()`` C function in GCC and Clang
+compilers.  The result of the check is stored in the internal cache
+variable ``HAVE_FNO_OPTIMIZE_STRLEN``, and the flag is conditionally enabled
+using the :command:`target_compile_options` command.  The
+:genex:`$<COMPILE_LANGUAGE:...> <COMPILE_LANGUAGE:languages>` generator
+expression ensures that the flag is added only to ``C`` source files.
+
+.. code-block:: cmake
+
+  include(CheckCCompilerFlag)
+  check_c_compiler_flag(-fno-optimize-strlen HAVE_FNO_OPTIMIZE_STRLEN)
+
+  if(HAVE_FNO_OPTIMIZE_STRLEN)
+    target_compile_options(
+      example
+      PRIVATE $<$<COMPILE_LANGUAGE:C>:-fno-optimize-strlen>
+    )
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckCompilerFlag` module for a more general command to check
+  whether a compiler flag is supported.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckCXXCompilerFlag.cmake

@@ -5,33 +5,51 @@
 CheckCXXCompilerFlag
 ------------------------
 
-Check once whether the CXX compiler supports a given flag.
+This module provides a command to check whether the C++ compiler supports a
+given flag.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCXXCompilerFlag)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_cxx_compiler_flag
 
+  Checks once whether the C++ compiler supports a given flag:
+
   .. code-block:: cmake
 
-    check_cxx_compiler_flag(<flag> <resultVar>)
+    check_cxx_compiler_flag(<flag> <variable>)
 
-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.
+  This command checks once that the ``<flag>`` is accepted by the ``CXX``
+  compiler without producing a diagnostic message.  Multiple flags can be
+  specified in one argument as a string using a :ref:`semicolon-separated
+  list <CMake Language Lists>`.
 
-``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 result of the check is stored in the internal cache variable specified
+  by ``<variable>``, with boolean true for success and boolean false for
+  failure.
 
-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.
+  A successful result only indicates that the compiler did not report an
+  error when given the flag.  Whether the flag has any effect, or the
+  intended one, is outside the scope of this module.
 
-See also :command:`check_compiler_flag` for a more general command syntax.
+  .. note::
 
-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.
+    Since the underlying :command:`try_compile` command also uses flags from
+    variables like :variable:`CMAKE_<LANG>_FLAGS`, unknown or unsupported
+    flags in those variables may result in a false negative for this check.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -46,6 +64,36 @@ in these variables can case a false negative result.
   .. include:: /module/include/CMAKE_REQUIRED_LINK_DIRECTORIES.rst
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
+
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+The following example demonstrates how to use this module to check
+the C++ compiler flag ``-fsycl``.  The result of the check is stored in the
+internal cache variable ``HAVE_FSYCL_FLAG``, and the flag is conditionally
+enabled using the :command:`target_compile_options` command.  The
+:genex:`$<COMPILE_LANGUAGE:...> <COMPILE_LANGUAGE:languages>` generator
+expression ensures that the flag is added only to ``CXX`` source files.
+
+.. code-block:: cmake
+
+  include(CheckCXXCompilerFlag)
+  check_cxx_compiler_flag(-fsycl HAVE_FSYCL_FLAG)
+
+  if(HAVE_FSYCL_FLAG)
+    target_compile_options(
+      example
+      PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fsycl>
+    )
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckCompilerFlag` module for a more general command to check
+  whether a compiler flag is supported.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckCompilerFlag.cmake

@@ -7,31 +7,68 @@ CheckCompilerFlag
 
 .. versionadded:: 3.19
 
-Check once whether the ``<lang>`` compiler supports a given flag.
+This module provides a command to check whether the compiler supports a given
+flag.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCompilerFlag)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_compiler_flag
 
+  Checks once whether the compiler supports a given flag:
+
   .. code-block:: cmake
 
-    check_compiler_flag(<lang> <flag> <resultVar>)
+    check_compiler_flag(<lang> <flag> <variable>)
 
-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.
+  This command checks once that the ``<flag>`` is accepted by the ``<lang>``
+  compiler without producing a diagnostic message.  The result of the check
+  is stored in the internal cache variable specified by ``<variable>``.
 
-``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 arguments are:
 
-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.
+  ``<lang>``
+    The language of the compiler used for the check.  Supported languages
+    are: ``C``, ``CXX``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, ``OBJC``,
+    and ``OBJCXX``, and ``Swift``.
 
-The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_compiler_flag()``. Unknown flags
-in these variables can case a false negative result.
+    .. versionadded:: 3.21
+      Support for ``HIP`` language.
+
+    .. versionadded:: 3.26
+      Support for ``Swift`` language.
+
+  ``<flag>``
+    Compiler flag(s) to check.  Multiple flags can be specified in one
+    argument as a string using a :ref:`semicolon-separated list
+    <CMake Language Lists>`.
+
+  ``<variable>``
+    Variable name of an internal cache variable to store the result of the
+    check, with boolean true for success and boolean false for failure.
+
+  A successful result only indicates that the compiler did not report an
+  error when given the flag.  Whether the flag has any effect, or the
+  intended one, is outside the scope of this module.
+
+  .. note::
+
+    Since the underlying :command:`try_compile` command also uses flags from
+    variables like :variable:`CMAKE_<LANG>_FLAGS`, unknown or unsupported
+    flags in those variables may result in a false negative for this check.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -47,6 +84,37 @@ in these variables can case a false negative result.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+The following example demonstrates how to use this module to check support
+for the C compiler flag ``-fno-optimize-strlen``, which disables
+optimizations related to the ``strlen()`` C function in GCC and Clang
+compilers.  The result of the check is stored in the internal cache
+variable ``HAVE_FNO_OPTIMIZE_STRLEN``, and the flag is conditionally enabled
+using the :command:`target_compile_options` command.  The
+:genex:`$<COMPILE_LANGUAGE:...> <COMPILE_LANGUAGE:languages>` generator
+expression ensures that the flag is added only to ``C`` source files.
+
+.. code-block:: cmake
+
+  include(CheckCompilerFlag)
+  check_compiler_flag(C -fno-optimize-strlen HAVE_FNO_OPTIMIZE_STRLEN)
+
+  if(HAVE_FNO_OPTIMIZE_STRLEN)
+    target_compile_options(
+      example
+      PRIVATE $<$<COMPILE_LANGUAGE:C>:-fno-optimize-strlen>
+    )
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckLinkerFlag` module to check whether a linker flag is
+  supported by the compiler.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckFortranCompilerFlag.cmake

@@ -7,33 +7,51 @@ CheckFortranCompilerFlag
 
 .. versionadded:: 3.3
 
-Check once whether the Fortran compiler supports a given flag.
+This module provides a command to check whether the Fortran compiler supports
+a given flag.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckFortranCompilerFlag)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_fortran_compiler_flag
 
+  Checks once whether the Fortran compiler supports a given flag:
+
   .. code-block:: cmake
 
-    check_fortran_compiler_flag(<flag> <resultVar>)
+    check_fortran_compiler_flag(<flag> <variable>)
 
-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.
+  This command checks once that the ``<flag>`` is accepted by the Fortran
+  compiler without producing a diagnostic message.  Multiple flags can be
+  specified in one argument as a string using a :ref:`semicolon-separated list
+  <CMake Language Lists>`.
 
-``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 result of the check is stored in the internal cache variable specified
+  by ``<variable>``, with boolean true for success and boolean false for
+  failure.
 
-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.
+  A successful result only indicates that the compiler did not report an
+  error when given the flag.  Whether the flag has any effect, or the
+  intended one, is outside the scope of this module.
 
-See also :command:`check_compiler_flag` for a more general command syntax.
+  .. note::
 
-The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_fortran_compiler_flag()``. Unknown
-flags in these variables can case a false negative result.
+    Since the underlying :command:`try_compile` command also uses flags from
+    variables like :variable:`CMAKE_<LANG>_FLAGS`, unknown or unsupported
+    flags in those variables may result in a false negative for this check.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -49,6 +67,36 @@ flags in these variables can case a false negative result.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+The following example demonstrates how to use this module to check
+the Fortran compiler flag ``-fallow-argument-mismatch``.  The result of the
+check is stored in the internal cache variable ``HAVE_FORTRAN_FLAG``, and
+the flag is conditionally enabled using the :command:`target_compile_options`
+command.  The :genex:`$<COMPILE_LANGUAGE:...> <COMPILE_LANGUAGE:languages>`
+generator expression ensures that the flag is added only to ``Fortran``
+source files.
+
+.. code-block:: cmake
+
+  include(CheckFortranCompilerFlag)
+  check_fortran_compiler_flag(-fallow-argument-mismatch HAVE_FORTRAN_FLAG)
+
+  if(HAVE_FORTRAN_FLAG)
+    target_compile_options(
+      example
+      PRIVATE $<$<COMPILE_LANGUAGE:Fortran>:-fallow-argument-mismatch>
+    )
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckCompilerFlag` module for a more general command to check
+  whether a compiler flag is supported.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckLinkerFlag.cmake

@@ -142,6 +142,8 @@ See Also
 
 * The :variable:`CMAKE_LINKER_TYPE` variable to specify the linker, which
   will be used also by this module.
+* The :module:`CheckCompilerFlag` module to check whether a compiler flag
+  is supported.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckOBJCCompilerFlag.cmake

@@ -7,33 +7,51 @@ CheckOBJCCompilerFlag
 
 .. versionadded:: 3.16
 
-Check once whether the Objective-C compiler supports a given flag.
+This module provides a command to check whether the Objective-C compiler
+supports a given flag.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckOBJCCompilerFlag)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_objc_compiler_flag
 
+  Checks once whether the Objective-C compiler supports a given flag:
+
   .. code-block:: cmake
 
-    check_objc_compiler_flag(<flag> <resultVar>)
+    check_objc_compiler_flag(<flag> <variable>)
 
-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.
+  This command checks once that the ``<flag>`` is accepted by the ``OBJC``
+  compiler without producing a diagnostic message.  Multiple flags can be
+  specified in one argument as a string using a
+  :ref:`semicolon-separated list <CMake Language Lists>`.
 
-``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 result of the check is stored in the internal cache variable specified
+  by ``<variable>``, with boolean true for success and boolean false for
+  failure.
 
-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.
+  A successful result only indicates that the compiler did not report an
+  error when given the flag.  Whether the flag has any effect, or the
+  intended one, is outside the scope of this module.
 
-See also :command:`check_compiler_flag` for a more general command syntax.
+  .. note::
 
-The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_objc_compiler_flag()``. Unknown
-flags in these variables can case a false negative result.
+    Since the underlying :command:`try_compile` command also uses flags from
+    variables like :variable:`CMAKE_<LANG>_FLAGS`, unknown or unsupported
+    flags in those variables may result in a false negative for this check.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -49,6 +67,35 @@ flags in these variables can case a false negative result.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+The following example demonstrates how to use this module to check the
+Objective-C compiler flag ``-fobjc-arc``.  The result of the check is
+stored in the internal cache variable ``HAVE_OBJC_ARC``, and the flag is
+conditionally enabled using the :command:`target_compile_options` command.
+The :genex:`$<COMPILE_LANGUAGE:...> <COMPILE_LANGUAGE:languages>` generator
+expression ensures that the flag is added only to ``OBJC`` source files.
+
+.. code-block:: cmake
+
+  include(CheckOBJCCompilerFlag)
+  check_objc_compiler_flag(-fobjc-arc HAVE_OBJC_ARC)
+
+  if(HAVE_OBJC_ARC)
+    target_compile_options(
+      example
+      PRIVATE $<$<COMPILE_LANGUAGE:OBJC>:-fobjc-arc>
+    )
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckCompilerFlag` module for a more general command to check
+  whether a compiler flag is supported.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckOBJCXXCompilerFlag.cmake

@@ -7,33 +7,51 @@ CheckOBJCXXCompilerFlag
 
 .. versionadded:: 3.16
 
-Check once whether the Objective-C++ compiler supports a given flag.
+This module provides a command to check whether the Objective-C++ compiler
+supports a given flag.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckOBJCXXCompilerFlag)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_objcxx_compiler_flag
 
+  Checks once whether the Objective-C++ compiler supports a given flag:
+
   .. code-block:: cmake
 
-    check_objcxx_compiler_flag(<flag> <resultVar>)
+    check_objcxx_compiler_flag(<flag> <variable>)
 
-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.
+  This command checks once that the ``<flag>`` is accepted by the ``OBJCXX``
+  compiler without producing a diagnostic message.  Multiple flags can be
+  specified in one argument as a string using a
+  :ref:`semicolon-separated list <CMake Language Lists>`.
 
-``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 result of the check is stored in the internal cache variable specified
+  by ``<variable>``, with boolean true for success and boolean false for
+  failure.
 
-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.
+  A successful result only indicates that the compiler did not report an
+  error when given the flag.  Whether the flag has any effect, or the
+  intended one, is outside the scope of this module.
 
-See also :command:`check_compiler_flag` for a more general command syntax.
+  .. note::
 
-The compile and link commands can be influenced by setting any of the
-following variables prior to calling ``check_objcxx_compiler_flag()``. Unknown
-flags in these variables can case a false negative result.
+    Since the underlying :command:`try_compile` command also uses flags from
+    variables like :variable:`CMAKE_<LANG>_FLAGS`, unknown or unsupported
+    flags in those variables may result in a false negative for this check.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -49,6 +67,35 @@ flags in these variables can case a false negative result.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+The following example demonstrates how to use this module to check the
+Objective-C++ compiler flag ``-fobjc-arc``.  The result of the check is
+stored in the internal cache variable ``HAVE_OBJC_ARC``, and the flag is
+conditionally enabled using the :command:`target_compile_options` command.
+The :genex:`$<COMPILE_LANGUAGE:...> <COMPILE_LANGUAGE:languages>` generator
+expression ensures that the flag is added only to ``OBJCXX`` source files.
+
+.. code-block:: cmake
+
+  include(CheckOBJCXXCompilerFlag)
+  check_objcxx_compiler_flag(-fobjc-arc HAVE_OBJC_ARC)
+
+  if(HAVE_OBJC_ARC)
+  target_compile_options(
+      example
+      PRIVATE $<$<COMPILE_LANGUAGE:OBJCXX>:-fobjc-arc>
+    )
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckCompilerFlag` module for a more general command to check
+  whether a compiler flag is supported.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Tests/FortranOnly/CMakeLists.txt

@@ -93,7 +93,7 @@ endif()
 
 unset(Fortran_BOGUS_FLAG CACHE)
 include(CheckFortranCompilerFlag)
-CHECK_Fortran_COMPILER_FLAG(-_this_is_not_a_flag_ Fortran_BOGUS_FLAG)
+check_fortran_compiler_flag(-_this_is_not_a_flag_ Fortran_BOGUS_FLAG)
 if (Fortran_BOGUS_FLAG)
   message(SEND_ERROR "CHECK_Fortran_COMPILER_FLAG() succeeded, but should have failed")
 endif()