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

Changes:

- Added intro code blocks showing how to include these modules.
- Added examples sections.
- Used "command" instead of "macro".
- Commands sections added to have a clearer overview of the modules at
  first encounter.
- Reworded commands arguments a bit.
- Added a rubric title for variables that affect the checks.
- CheckFortranSourceCompiles: Added CMake version when SRC_EXT option
  was introduced.
- Listed CMAKE_TRY_COMPILE_TARGET_TYPE variable in the rubric together
  with CMAKE_REQUIRED_* variables and added an include RST file for it.
- Used lowercase style for check_fortran_source_compiles().

Help/guide/tutorial/Adding System Introspection.rst

@@ -35,7 +35,7 @@ exercise, complete ``TODO 1`` through ``TODO 5``.
 
 Start by editing ``MathFunctions/CMakeLists.txt``. Include the
 :module:`CheckCXXSourceCompiles` module. Then, use
-``check_cxx_source_compiles`` to determine whether ``log`` and ``exp`` are
+``check_cxx_source_compiles()`` to determine whether ``log`` and ``exp`` are
 available from ``cmath``. If they are available, use
 :command:`target_compile_definitions` to specify ``HAVE_LOG`` and ``HAVE_EXP``
 as compile definitions.

Help/module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst

@@ -0,0 +1,6 @@
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
+  Internally, the :command:`try_compile` command is used to perform the
+  check, and this variable controls the type of target it creates.  If this
+  variable is set to ``EXECUTABLE`` (the default), the check compiles and
+  links the test source code as an executable program.  If set to
+  ``STATIC_LIBRARY``, the test source code is compiled but not linked.

Help/release/3.1.rst

@@ -191,7 +191,7 @@ Modules
   meant for a prefix other than :variable:`CMAKE_INSTALL_PREFIX`.
 
 * The :module:`CheckFortranSourceCompiles` module was added to
-  provide a ``CHECK_Fortran_SOURCE_COMPILES`` macro.
+  provide a ``check_fortran_source_compiles()`` command.
 
 * The :module:`ExternalData` module learned to tolerate a ``DATA{}``
   reference to a missing source file with a warning instead of

Help/release/3.7.rst

@@ -158,8 +158,8 @@ Modules
 * An :module:`AndroidTestUtilities` module was added to manage transfer
   of test data to an Android device.
 
-* The :module:`CheckFortranSourceCompiles` module macro
-  ``CHECK_Fortran_SOURCE_COMPILES`` gained a ``SRC_EXT`` option
+* The :module:`CheckFortranSourceCompiles` module command
+  ``check_fortran_source_compiles()`` gained a ``SRC_EXT`` option
   to specify a custom test Fortran source file extension.
 
 * The :module:`ExternalProject` module gained ``HTTP_USERNAME`` and

Modules/CheckCSourceCompiles.cmake

@@ -5,35 +5,51 @@
 CheckCSourceCompiles
 --------------------
 
-Check once if C source code can be built.
+This module provides a command to check whether a C source can be built.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCSourceCompiles)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_c_source_compiles
 
+  Checks once whether the given C source code can be built:
+
   .. code-block:: cmake
 
-    check_c_source_compiles(<code> <resultVar>
-                            [FAIL_REGEX <regex1> [<regex2>...]])
+    check_c_source_compiles(<code> <variable> [FAIL_REGEX <regexes>...])
+
+  This command checks once that the source supplied in ``<code>`` can be
+  compiled (and linked into an executable).  The result of the check is
+  stored in the internal cache variable specified by ``<variable>``.
 
-  Check once that the source supplied in ``<code>`` can be built. The result is
-  stored in the internal cache variable specified by ``<resultVar>``, with
-  boolean ``true`` for success and boolean ``false`` for failure.
+  The arguments are:
 
-  If ``FAIL_REGEX`` is provided, then failure is determined by checking
-  if anything in the compiler output matches any of the specified regular
-  expressions.
+  ``<code>``
+    C source code to check.  This must be an entire program, as written in
+    a file containing the body block.  All symbols used in the source code
+    are expected to be declared as usual in their corresponding headers.
 
-  Internally, :command:`try_compile` is used to compile the source. If
-  :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
-  the source is compiled and linked as an executable program. If set to
-  ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
-  functions must be declared as usual.
+  ``<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.
 
-  See also :command:`check_source_compiles` for a more general command syntax.
+  ``FAIL_REGEX <regexes>...``
+    If one or more regular expression patterns are provided, then failure is
+    determined by checking if anything in the compiler output matches any of
+    the specified regular expressions.
 
-  See also :command:`check_source_runs` to run compiled source.
+  .. rubric:: Variables Affecting the Check
 
-  The compile and link commands can be influenced by setting any of the
-  following variables prior to calling ``check_c_source_compiles()``:
+  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 +65,35 @@ Check once if C source code can be built.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+Checking whether C source code containing SSE2 intrinsic can be compiled
+and linked:
+
+.. code-block:: cmake
+
+  include(CheckCSourceCompiles)
+
+  check_c_source_compiles("
+    #include <emmintrin.h>
+    int main(void)
+    {
+      __m128d a = _mm_setzero_pd();
+      (void)a;
+      return 0;
+    }
+  " PROJECT_HAVE_SSE2_INTRINSICS)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceCompiles` module for a more general command to
+  check whether source can be built.
+* The :module:`CheckSourceRuns` module to check whether source can be built
+  and run.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckCXXSourceCompiles.cmake

@@ -5,35 +5,51 @@
 CheckCXXSourceCompiles
 ----------------------
 
-Check once if C++ source code can be built.
+This module provides a command to check whether a C++ source can be built.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCXXSourceCompiles)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_cxx_source_compiles
 
+  Checks once whether the given C++ source code can be built:
+
   .. code-block:: cmake
 
-    check_cxx_source_compiles(<code> <resultVar>
-                              [FAIL_REGEX <regex1> [<regex2>...]])
+    check_cxx_source_compiles(<code> <variable> [FAIL_REGEX <regexes>...])
+
+  This command checks once that the source supplied in ``<code>`` can be
+  compiled (and linked into an executable).  The result of the check is
+  stored in the internal cache variable specified by ``<variable>``.
 
-  Check once that the source supplied in ``<code>`` can be built. The result is
-  stored in the internal cache variable specified by ``<resultVar>``, with
-  boolean ``true`` for success and boolean ``false`` for failure.
+  The arguments are:
 
-  If ``FAIL_REGEX`` is provided, then failure is determined by checking
-  if anything in the compiler output matches any of the specified regular
-  expressions.
+  ``<code>``
+    C++ source code to check.  This must be an entire program, as written
+    in a file containing the body block.  All symbols used in the source code
+    are expected to be declared as usual in their corresponding headers.
 
-  Internally, :command:`try_compile` is used to compile the source. If
-  :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
-  the source is compiled and linked as an executable program. If set to
-  ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
-  functions must be declared as usual.
+  ``<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.
 
-  See also :command:`check_source_compiles` for a more general command syntax.
+  ``FAIL_REGEX <regexes>...``
+    If one or more regular expression patterns are provided, then failure is
+    determined by checking if anything in the compiler output matches any of
+    the specified regular expressions.
 
-  See also :command:`check_source_runs` to run compiled source.
+  .. rubric:: Variables Affecting the Check
 
-  The compile and link commands can be influenced by setting any of the
-  following variables prior to calling ``check_cxx_source_compiles()``:
+  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 +65,35 @@ Check once if C++ source code can be built.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+The following example demonstrates how to check whether the C++ compiler
+supports a specific language feature.  In this case, the check verifies if
+the compiler supports ``C++11`` lambda expressions.  The result is stored
+in the internal cache variable ``HAVE_CXX11_LAMBDAS``:
+
+.. code-block:: cmake
+
+  include(CheckCXXSourceCompiles)
+
+  check_cxx_source_compiles("
+    int main()
+    {
+      auto lambda = []() { return 42; };
+      return lambda();
+    }
+  " HAVE_CXX11_LAMBDAS)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceCompiles` module for a more general command to
+  check whether source can be built.
+* The :module:`CheckSourceRuns` module to check whether source can be built
+  and run.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckFortranSourceCompiles.cmake

@@ -7,41 +7,65 @@ CheckFortranSourceCompiles
 
 .. versionadded:: 3.1
 
-Check once if Fortran source code can be built.
+This module provides a command to check whether a Fortran source can be
+built.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckFortranSourceCompiles)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_fortran_source_compiles
 
+  Checks once whether the given Fortran source code can be built:
+
   .. code-block:: cmake
 
-    check_fortran_source_compiles(<code> <resultVar>
-        [FAIL_REGEX <regex>...]
-        [SRC_EXT <extension>]
+    check_fortran_source_compiles(
+      <code>
+      <variable>
+      [FAIL_REGEX <regexes>...]
+      [SRC_EXT <extension>]
     )
 
-  Check once that the source supplied in ``<code>`` can be built. 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 source supplied in ``<code>`` can be
+  compiled (and linked into an executable).  The result of the check is
+  stored in the internal cache variable specified by ``<variable>``.
+
+  The arguments are:
+
+  ``<code>``
+    Fortran source code to check.  This must be an entire program, as
+    written in a file containing the body block.  All symbols used in the
+    source code are expected to be declared as usual in their corresponding
+    headers.
 
-  If ``FAIL_REGEX`` is provided, then failure is determined by checking
-  if anything in the compiler output matches any of the specified regular
-  expressions.
+  ``<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.
 
-  By default, the test source file will be given a ``.F`` file extension. The
-  ``SRC_EXT`` option can be used to override this with ``.<extension>`` instead--
-  ``.F90`` is a typical choice.
+  ``FAIL_REGEX <regexes>...``
+    If this option is provided with one or more regular expressions, then
+    failure is determined by checking if anything in the compiler output
+    matches any of the specified regular expressions.
 
-  See also :command:`check_source_compiles` for a more general command syntax.
+  ``SRC_EXT <extension>``
+    .. versionadded:: 3.7
 
-  See also :command:`check_source_runs` to run compiled source.
+    By default, the test source file used for the check will be given a
+    ``.F`` file extension.  This option can be used to override this with
+    ``.<extension>`` instead - ``.F90`` is a typical choice.
 
-  Internally, :command:`try_compile` is used to compile the source. If
-  :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
-  the source is compiled and linked as an executable program. If set to
-  ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
-  functions must be declared as usual.
+  .. rubric:: Variables Affecting the Check
 
-  The compile and link commands can be influenced by setting any of the
-  following variables prior to calling ``check_fortran_source_compiles()``:
+  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
 
@@ -57,6 +81,33 @@ Check once if Fortran source code can be built.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+Checking whether the Fortran compiler supports the ``pure`` procedure
+attribute:
+
+.. code-block:: cmake
+
+  include(CheckFortranSourceCompiles)
+
+  check_fortran_source_compiles("
+    pure subroutine foo()
+    end subroutine
+    program test
+      call foo()
+    end
+  " HAVE_PURE SRC_EXT "F90")
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceCompiles` module for a more general command to
+  check whether source can be built.
+* The :module:`CheckSourceRuns` module to check whether source can be built
+  and run.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckOBJCSourceCompiles.cmake

@@ -7,35 +7,52 @@ CheckOBJCSourceCompiles
 
 .. versionadded:: 3.16
 
-Check once if Objective-C source can be built.
+This module provides a command to check whether an Objective-C source can
+be built.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckOBJCSourceCompiles)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_objc_source_compiles
 
+  Checks once whether the given Objective-C source code can be built:
+
   .. code-block:: cmake
 
-    check_objc_source_compiles(<code> <resultVar>
-                               [FAIL_REGEX <regex1> [<regex2>...]])
+    check_objc_source_compiles(<code> <variable> [FAIL_REGEX <regexes>...])
+
+  This command checks once that the source supplied in ``<code>`` can be
+  compiled (and linked into an executable).  The result of the check is
+  stored in the internal cache variable specified by ``<variable>``.
 
-  Check once that the source supplied in ``<code>`` can be built. The result is
-  stored in the internal cache variable specified by ``<resultVar>``, with
-  boolean ``true`` for success and boolean ``false`` for failure.
+  The arguments are:
 
-  If ``FAIL_REGEX`` is provided, then failure is determined by checking
-  if anything in the compiler output matches any of the specified regular
-  expressions.
+  ``<code>``
+    Source code to check.  This must be an entire program, as written in a
+    file containing the body block.  All symbols used in the source code
+    are expected to be declared as usual in their corresponding headers.
 
-  Internally, :command:`try_compile` is used to compile the source. If
-  :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
-  the source is compiled and linked as an executable program. If set to
-  ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
-  functions must be declared as usual.
+  ``<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.
 
-  See also :command:`check_source_compiles` for a more general command syntax.
+  ``FAIL_REGEX <regexes>...``
+    If this option is provided with one or more regular expressions, then
+    failure is determined by checking if anything in the compiler output
+    matches any of the specified regular expressions.
 
-  See also :command:`check_source_runs` to run compiled source.
+  .. rubric:: Variables Affecting the Check
 
-  The compile and link commands can be influenced by setting any of the
-  following variables prior to calling ``check_objc_source_compiles()``
+  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
 
@@ -51,6 +68,35 @@ Check once if Objective-C source can be built.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+In the following example, this module is used to check whether the provided
+Objective-C source code compiles and links.  Result of the check is stored in
+the internal cache variable ``HAVE_WORKING_CODE``.
+
+.. code-block:: cmake
+
+  include(CheckOBJCSourceCompiles)
+
+  check_objc_source_compiles("
+    #import <Foundation/Foundation.h>
+    int main()
+    {
+      NSObject *foo;
+      return 0;
+    }
+  " HAVE_WORKING_CODE)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceCompiles` module for a more general command to
+  check whether source can be built.
+* The :module:`CheckSourceRuns` module to check whether source can be built
+  and run.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckOBJCXXSourceCompiles.cmake

@@ -7,35 +7,53 @@ CheckOBJCXXSourceCompiles
 
 .. versionadded:: 3.16
 
-Check once if Objective-C++ source can be built.
+This module provides a command to check whether an Objective-C++ source can
+be built.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckOBJCXXSourceCompiles)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_objcxx_source_compiles
 
+  Checks once whether the given Objective-C++ source code can be built:
+
   .. code-block:: cmake
 
-    check_objcxx_source_compiles(<code> <resultVar>
-                                 [FAIL_REGEX <regex1> [<regex2>...]])
+    check_objcxx_source_compiles(<code> <variable> [FAIL_REGEX <regexes>...])
+
+  This command checks once that the source supplied in ``<code>`` can be
+  compiled (and linked into an executable).  The result of the check is
+  stored in the internal cache variable specified by ``<variable>``.
 
-  Check once that the source supplied in ``<code>`` can be built. The result is
-  stored in the internal cache variable specified by ``<resultVar>``, with
-  boolean ``true`` for success and boolean ``false`` for failure.
+  The arguments are:
 
-  If ``FAIL_REGEX`` is provided, then failure is determined by checking
-  if anything in the compiler output matches any of the specified regular
-  expressions.
+  ``<code>``
+    Objective-C++ source code to check.  This must be an entire program, as
+    written in a file containing the body block.  All symbols used in the
+    source code are expected to be declared as usual in their corresponding
+    headers.
 
-  Internally, :command:`try_compile` is used to compile the source. If
-  :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
-  the source is compiled and linked as an executable program. If set to
-  ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
-  functions must be declared as usual.
+  ``<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.
 
-  See also :command:`check_source_compiles` for a more general command syntax.
+  ``FAIL_REGEX <regexes>...``
+    If this option is provided with one or more regular expressions, then
+    failure is determined by checking if anything in the compiler output
+    matches any of the specified regular expressions.
 
-  See also :command:`check_source_runs` to run compiled source.
+  .. rubric:: Variables Affecting the Check
 
-  The compile and link commands can be influenced by setting any of the
-  following variables prior to calling ``check_objcxx_source_compiles()``
+  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
 
@@ -51,6 +69,37 @@ Check once if Objective-C++ source can be built.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+In the following example, this module is used to check whether the provided
+Objective-C++ source code can be compiled and linked.  Result of the check
+is stored in the internal cache variable ``HAVE_WORKING_CODE``.
+
+.. code-block:: cmake
+
+  include(CheckOBJCXXSourceCompiles)
+
+  check_objcxx_source_compiles("
+    #include <vector>
+    #import <Foundation/Foundation.h>
+    int main()
+    {
+      std::vector<int> v;
+      NSObject *foo;
+      return 0;
+    }
+  " HAVE_WORKING_CODE)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceCompiles` module for a more general command to
+  check whether source can be built.
+* The :module:`CheckSourceRuns` module to check whether source can be built
+  and run.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckSourceCompiles.cmake

@@ -8,63 +8,77 @@ CheckSourceCompiles
 
 .. versionadded:: 3.19
 
-Check once if source code can be built for a given language.
+This module provides a command that checks whether a source code can be
+built for a given language.
 
-.. command:: check_source_compiles
+Load this module in a CMake project with:
 
-  .. code-block:: cmake
+.. code-block:: cmake
 
-    check_source_compiles(<lang> <code> <resultVar>
-                          [FAIL_REGEX <regex1> [<regex2>...]]
-                          [SRC_EXT <extension>])
+  include(CheckSourceCompiles)
 
-  Check once that the source supplied in ``<code>`` can be built for code
-  language ``<lang>``. The result is stored in the internal cache variable
-  specified by ``<resultVar>``, with boolean ``true`` for success and
-  boolean ``false`` for failure.
+Commands
+^^^^^^^^
 
-  If ``FAIL_REGEX`` is provided, then failure is determined by checking
-  if anything in the compiler output matches any of the specified regular
-  expressions.
+This module provides the following command:
 
-  By default, the test source file will be given a file extension that matches
-  the requested language. The ``SRC_EXT`` option can be used to override this
-  with ``.<extension>`` instead.
+.. command:: check_source_compiles
 
-  The C example checks if the compiler supports the ``noreturn`` attribute:
+  Checks once whether the given source code can be built for the given
+  language:
 
   .. code-block:: cmake
 
-    set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY")
+    check_source_compiles(
+      <lang>
+      <code>
+      <variable>
+      [FAIL_REGEX <regexes>...]
+      [SRC_EXT <extension>]
+    )
 
-    check_source_compiles(C
-    "#if !__has_c_attribute(noreturn)
-    #error \"No noreturn attribute\"
-    #endif"
-    HAVE_NORETURN)
+  This command checks once that the source supplied in ``<code>`` can be
+  compiled (and linked into an executable) for code language ``<lang>``.
+  The result of the check is stored in the internal cache variable specified
+  by ``<variable>``.
 
-  The Fortran example checks if the compiler supports the ``pure`` procedure
-  attribute:
+  The arguments are:
 
-  .. code-block:: cmake
+  ``<lang>``
+    Language of the source code to check.  Supported languages are:
+    ``C``, ``CXX``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, ``OBJC``,
+    ``OBJCXX``, and ``Swift``.
 
-    set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY")
+    .. versionadded:: 3.21
+      Support for ``HIP`` language.
+
+    .. versionadded:: 3.26
+      Support for ``Swift`` language.
 
-    check_source_compiles(Fortran
-    "pure subroutine foo()
-    end subroutine"
-    HAVE_PURE)
+  ``<code>``
+    The source code to check.  This must be an entire program, as written
+    in a file containing the body block.  All symbols used in the source code
+    are expected to be declared as usual in their corresponding headers.
 
-  Internally, :command:`try_compile` is used to compile the source. If
-  :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``EXECUTABLE`` (default),
-  the source is compiled and linked as an executable program. If set to
-  ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
-  functions must be declared as usual.
+  ``<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.
 
-  See also :command:`check_source_runs` to run compiled source.
+  ``FAIL_REGEX <regexes>...``
+    If one or more regular expression patterns are provided, then failure is
+    determined by checking if anything in the compiler output matches any of
+    the specified regular expressions.
 
-  The compile and link commands can be influenced by setting any of the
-  following variables prior to calling ``check_source_compiles()``:
+  ``SRC_EXT <extension>``
+    By default, the internal test source file used for the check will be
+    given a file extension that matches the requested language (e.g., ``.c``
+    for C, ``.cxx`` for C++, ``.F90`` for Fortran, etc.).  This option can
+    be used to override this with the ``.<extension>`` instead.
+
+  .. 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
 
@@ -80,6 +94,108 @@ Check once if source code can be built for a given language.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+  .. include:: /module/include/CMAKE_TRY_COMPILE_TARGET_TYPE.rst
+
+Examples
+^^^^^^^^
+
+Example: Basic Usage
+""""""""""""""""""""
+
+The following example demonstrates how to check whether the C++ compiler
+supports a specific language feature using this module.  In this case, the
+check verifies if the compiler supports ``C++11`` lambda expressions.  The
+result is stored in the internal cache variable ``HAVE_CXX11_LAMBDAS``:
+
+.. code-block:: cmake
+
+  include(CheckSourceCompiles)
+
+  check_source_compiles(CXX "
+    int main()
+    {
+      auto lambda = []() { return 42; };
+      return lambda();
+    }
+  " HAVE_CXX11_LAMBDAS)
+
+Example: Checking Code With Bracket Argument
+""""""""""""""""""""""""""""""""""""""""""""
+
+The following example shows how to check whether the C compiler supports the
+``noreturn`` attribute.  Code is supplied using the :ref:`Bracket Argument`
+for easier embedded quotes handling:
+
+.. code-block:: cmake
+  :force:
+
+  include(CheckSourceCompiles)
+
+  check_source_compiles(C [[
+    #if !__has_c_attribute(noreturn)
+    #  error "No noreturn attribute"
+    #endif
+    int main(void) { return 0; }
+  ]] HAVE_NORETURN)
+
+Example: Performing a Check Without Linking
+"""""""""""""""""""""""""""""""""""""""""""
+
+In the following example, this module is used to perform a compile-only
+check of Fortran source code, whether the compiler supports the ``pure``
+procedure attribute:
+
+.. code-block:: cmake
+
+  include(CheckSourceCompiles)
+
+  block()
+    set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY")
+
+    check_source_compiles(
+      Fortran
+      "pure subroutine foo()
+      end subroutine"
+      HAVE_PURE
+    )
+  endblock()
+
+Example: Isolated Check
+"""""""""""""""""""""""
+
+In the following example, this module is used in combination with the
+:module:`CMakePushCheckState` module to modify required libraries when
+checking whether the PostgreSQL ``PGVerbosity`` enum contains
+``PQERRORS_SQLSTATE`` (available as of PostgreSQL version 12):
+
+.. code-block:: cmake
+
+  include(CheckSourceCompiles)
+  include(CMakePushCheckState)
+
+  find_package(PostgreSQL)
+
+  if(TARGET PostgreSQL::PostgreSQL)
+    cmake_push_check_state(RESET)
+      set(CMAKE_REQUIRED_LIBRARIES PostgreSQL::PostgreSQL)
+
+      check_source_compiles(C "
+        #include <libpq-fe.h>
+        int main(void)
+        {
+          PGVerbosity e = PQERRORS_SQLSTATE;
+          (void)e;
+          return 0;
+        }
+      " HAVE_PQERRORS_SQLSTATE)
+    cmake_pop_check_state()
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceRuns` module to check whether the source code can
+  be built and also run.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Tests/FortranModules/CMakeLists.txt

@@ -19,7 +19,7 @@ endif()
 
 if(NOT DEFINED CMake_TEST_Fortran_SUBMODULES)
   include(CheckFortranSourceCompiles)
-  CHECK_Fortran_SOURCE_COMPILES([[
+  check_fortran_source_compiles([[
 module parent
   interface
     module function id(x)

Tests/FortranOnly/CMakeLists.txt

@@ -63,7 +63,7 @@ add_dependencies(checksayhello sayhello)
 
 include(CheckFortranSourceCompiles)
 unset(HAVE_PRINT CACHE)
-CHECK_Fortran_SOURCE_COMPILES([[
+check_fortran_source_compiles([[
       PROGRAM TEST_HAVE_PRINT
         PRINT *, 'Hello'
       END