Check*SourceRuns: Update documentation

This updates the following modules:
- CheckCSourceRuns
- CheckCXXSourceRuns
- CheckFortranSourceRuns
- CheckOBJCSourceRuns
- CheckOBJCXXSourceRuns
- CheckSourceRuns

Changes:
- Added intro code blocks showing how to include these modules.
- Used word "command" instead of "macro".
- Added "Commands" sections to have a clearer overview of the modules at
  first encounter.
- Reworded commands descriptions and arguments a bit.
- Added a rubric title for variables that affect the checks.
- Added "Examples" sections.
- Added "See Also" sections.
- Added few more examples in the CheckSourceRuns module to show how to
  use this module with different languages, `CMAKE_REQUIRED_*` variables,
  and mentioned bracket argument syntax a bit.

Modules/CheckCSourceRuns.cmake

@@ -5,28 +5,40 @@
 CheckCSourceRuns
 ----------------
 
-Check once if given C source compiles and links into an executable and can
-subsequently be run.
+This module provides a command to check whether a C source can be built and
+run.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCSourceRuns)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_c_source_runs
 
-  .. code-block:: cmake
+  Checks once whether the given C source code compiles and links into an
+  executable that can subsequently be run:
 
-    check_c_source_runs(<code> <resultVar>)
+  .. code-block:: cmake
 
-  Check once that the source supplied in ``<code>`` can be built, linked as an
-  executable, and then run. The ``<code>`` must contain at least a ``main()``
-  function.
+    check_c_source_runs(<code> <variable>)
 
-  The result is stored in the internal cache variable specified by
-  ``<resultVar>``. If the code builds and runs with exit code ``0``, success is
-  indicated by boolean ``true``. Failure to build or run is indicated by boolean
-  ``false``, such as an empty string or an error message.
+  The C source supplied in ``<code>`` must contain at least a ``main()``
+  function.  The result of the check is stored in the internal cache variable
+  specified by ``<variable>``.  If the code builds and runs with exit code
+  ``0``, success is indicated by a boolean true value.  Failure to build or
+  run is indicated by a boolean false value, such as an empty string or an
+  error message.
 
-  See also :command:`check_source_runs` for a more general command syntax.
+  .. 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_runs()``:
+  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
 
@@ -42,6 +54,30 @@ subsequently be run.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+Examples
+^^^^^^^^
+
+The following example demonstrates how to use this module to check whether
+the C source code is supported and operational at runtime.  The result of
+the check is stored in the internal cache variable ``HAVE_NORETURN``.
+
+.. code-block:: cmake
+
+  include(CheckCSourceRuns)
+
+  check_c_source_runs("
+    #include <stdlib.h>
+    #include <stdnoreturn.h>
+    noreturn void f(){ exit(0); }
+    int main(void) { f(); return 1; }
+  " HAVE_NORETURN)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceRuns` module for a more general command syntax.
+* The :module:`CheckSourceCompiles` module to check whether a source code
+  can be built.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckCXXSourceRuns.cmake

@@ -5,28 +5,40 @@
 CheckCXXSourceRuns
 ------------------
 
-Check once if given C++ source compiles and links into an executable and can
-subsequently be run.
+This module provides a command to check whether a C++ source can be built
+and run.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckCXXSourceRuns)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_cxx_source_runs
 
-  .. code-block:: cmake
+  Checks once whether the given C++ source code compiles and links into an
+  executable that can subsequently be run:
 
-    check_cxx_source_runs(<code> <resultVar>)
+  .. code-block:: cmake
 
-  Check once that the source supplied in ``<code>`` can be built, linked as an
-  executable, and then run. The ``<code>`` must contain at least a ``main()``
-  function.
+    check_cxx_source_runs(<code> <variable>)
 
-  The result is stored in the internal cache variable specified by
-  ``<resultVar>``. If the code builds and runs with exit code ``0``, success is
-  indicated by boolean ``true``. Failure to build or run is indicated by boolean
-  ``false``, such as an empty string or an error message.
+  The C++ source supplied in ``<code>`` must contain at least a ``main()``
+  function.  The result of the check is stored in the internal cache variable
+  specified by ``<variable>``.  If the code builds and runs with exit code
+  ``0``, success is indicated by a boolean true value.  Failure to build or
+  run is indicated by a boolean false value, such as an empty string or an
+  error message.
 
-  See also :command:`check_source_runs` for a more general command syntax.
+  .. 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_runs()``:
+  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
 
@@ -42,6 +54,39 @@ subsequently be run.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+Examples
+^^^^^^^^
+
+The following example demonstrates how to check whether the C++ standard
+library is functional and ``std::vector`` works at runtime.  If the source
+compiles, links, and runs successfully, internal cache variable
+``HAVE_WORKING_STD_VECTOR`` will be set to boolean true value.  Code is
+supplied using :ref:`Bracket Argument` for easier embedded quotes handling:
+
+.. code-block:: cmake
+  :force:
+
+  include(CheckCXXSourceRuns)
+
+  check_cxx_source_runs([[
+    #include <iostream>
+    #include <vector>
+
+    int main()
+    {
+      std::vector<int> v = {1, 2, 3};
+      if (v.size() != 3) return 1;
+      std::cout << "Vector works correctly." << std::endl;
+      return 0;
+    }
+  ]] HAVE_WORKING_STD_VECTOR)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceRuns` module for a more general command syntax.
+* The :module:`CheckSourceCompiles` module to check whether a source code
+  can be built.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckFortranSourceRuns.cmake

@@ -7,39 +7,47 @@ CheckFortranSourceRuns
 
 .. versionadded:: 3.14
 
-Check once if given Fortran source compiles and links into an executable and can
-subsequently be run.
+This module provides a command to check whether a Fortran source can be built
+and run.
 
-.. command:: check_fortran_source_runs
+Load this module in a CMake project with:
 
-  .. code-block:: cmake
+.. code-block:: cmake
+
+  include(CheckFortranSourceRuns)
 
-    check_fortran_source_runs(<code> <resultVar>
-        [SRC_EXT <extension>])
+Commands
+^^^^^^^^
 
-  Check once that the source supplied in ``<code>`` can be built, linked as an
-  executable, and then run. The ``<code>`` must contain a Fortran ``program``.
+This module provides the following command:
+
+.. command:: check_fortran_source_runs
 
-  The result is stored in the internal cache variable specified by
-  ``<resultVar>``. If the code builds and runs with exit code ``0``, success is
-  indicated by boolean ``true``. Failure to build or run is indicated by boolean
-  ``false``, such as an empty string or an error message.
+  Checks once whether the given Fortran source compiles and links into an
+  executable that can subsequently be run.
 
   .. code-block:: cmake
 
-    check_fortran_source_runs("program test
-    real :: x[*]
-    call co_sum(x)
-    end program"
-    HAVE_COARRAY)
+    check_fortran_source_runs(<code> <variable> [SRC_EXT <extension>])
+
+  The Fortran source supplied in ``<code>`` must contain a Fortran ``program``
+  unit.  The result of the check is stored in the internal cache variable
+  specified by ``<variable>``.  If the code builds and runs with exit code
+  ``0``, success is indicated by a boolean true value.  Failure to build or
+  run is indicated by a boolean false value, such as an empty string or an
+  error message.
+
+  The options are:
 
-  By default, the test source file will be given a ``.F90`` file extension. The
-  ``SRC_EXT`` option can be used to override this with ``.<extension>`` instead.
+  ``SRC_EXT <extension>``
+    By default, the internal test source file used for the check will be
+    given a ``.F90`` file extension.  This option can be used to change the
+    extension to ``.<extension>`` instead.
 
-  See also :command:`check_source_runs` for a more general command syntax.
+  .. 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_runs()``:
+  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
 
@@ -55,6 +63,30 @@ subsequently be run.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+Examples
+^^^^^^^^
+
+The following example shows how to use this module to check whether a Fortran
+source code runs and store the result of the check in an internal cache
+variable ``HAVE_COARRAY``:
+
+.. code-block:: cmake
+
+  include(CheckFortranSourceRuns)
+
+  check_fortran_source_runs([[
+    program test
+    real :: x[*]
+    call co_sum(x)
+    end program
+  ]] HAVE_COARRAY)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceRuns` module for a more general command syntax.
+* The :module:`CheckSourceCompiles` module to check whether a source code
+  can be built.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckOBJCSourceRuns.cmake

@@ -7,28 +7,40 @@ CheckOBJCSourceRuns
 
 .. versionadded:: 3.16
 
-Check once if given Objective-C source compiles and links into an executable and
-can subsequently be run.
+This module provides a command to check whether an Objective-C source can
+be built and run.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckOBJCSourceRuns)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_objc_source_runs
 
-  .. code-block:: cmake
+  Checks once whether the given Objective-C source code compiles and links
+  into an executable that can subsequently be run:
 
-    check_objc_source_runs(<code> <resultVar>)
+  .. code-block:: cmake
 
-  Check once that the source supplied in ``<code>`` can be built, linked as an
-  executable, and then run. The ``<code>`` must contain at least a ``main()``
-  function.
+    check_objc_source_runs(<code> <variable>)
 
-  The result is stored in the internal cache variable specified by
-  ``<resultVar>``. If the code builds and runs with exit code ``0``, success is
-  indicated by boolean ``true``. Failure to build or run is indicated by boolean
-  ``false``, such as an empty string or an error message.
+  The Objective-C source supplied in ``<code>`` must contain at least a
+  ``main()`` function.  The result of the check is stored in the internal
+  cache variable specified by ``<variable>``.  If the code builds and runs
+  with exit code ``0``, success is indicated by a boolean true value.
+  Failure to build or run is indicated by a boolean false value, such as an
+  empty string or an error message.
 
-  See also :command:`check_source_runs` for a more general command syntax.
+  .. 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_runs()``
+  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
 
@@ -44,6 +56,32 @@ can subsequently be run.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+Examples
+^^^^^^^^
+
+In the following example, this module is used to check whether the provided
+Objective-C source code builds and runs.  Result of the check is stored in
+an internal cache variable ``HAVE_WORKING_CODE``.
+
+.. code-block:: cmake
+
+  include(CheckOBJCSourceRuns)
+
+  check_objc_source_runs("
+    #import <Foundation/Foundation.h>
+    int main()
+    {
+      NSObject *foo;
+      return 0;
+    }
+  " HAVE_WORKING_CODE)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceRuns` module for a more general command syntax.
+* The :module:`CheckSourceCompiles` module to check whether a source code
+  can be built.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckOBJCXXSourceRuns.cmake

@@ -7,28 +7,40 @@ CheckOBJCXXSourceRuns
 
 .. versionadded:: 3.16
 
-Check once if given Objective-C++ source compiles and links into an executable
-and can subsequently be run.
+This module provides a command to check whether an Objective-C++ source can
+be built and run.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckOBJCXXSourceRuns)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_objcxx_source_runs
 
-  .. code-block:: cmake
+  Checks once whether the given Objective-C++ source code compiles and links
+  into an executable that can subsequently be run:
 
-    check_objcxx_source_runs(<code> <resultVar>)
+  .. code-block:: cmake
 
-  Check once that the source supplied in ``<code>`` can be built, linked as an
-  executable, and then run. The ``<code>`` must contain at least a ``main()``
-  function.
+    check_objcxx_source_runs(<code> <variable>)
 
-  The result is stored in the internal cache variable specified by
-  ``<resultVar>``. If the code builds and runs with exit code ``0``, success is
-  indicated by boolean ``true``. Failure to build or run is indicated by boolean
-  ``false``, such as an empty string or an error message.
+  The Objective-C++ source supplied in ``<code>`` must contain at least a
+  ``main()`` function.  The result of the check is stored in the internal
+  cache variable specified by ``<variable>``.  If the code builds and runs
+  with exit code ``0``, success is indicated by a boolean true value.
+  Failure to build or run is indicated by a boolean false value, such as an
+  empty string or an error message.
 
-  See also :command:`check_source_runs` for a more general command syntax.
+  .. 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_runs()``
+  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
 
@@ -44,6 +56,34 @@ and can subsequently be run.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+Examples
+^^^^^^^^
+
+In the following example, this module is used to check whether the provided
+Objective-C++ source code builds and runs.  Result of the check is stored in
+an internal cache variable ``HAVE_WORKING_CODE``.
+
+.. code-block:: cmake
+
+  include(CheckOBJCXXSourceRuns)
+
+  check_objcxx_source_runs("
+    #include <vector>
+    #import <Foundation/Foundation.h>
+    int main()
+    {
+      std::vector<int> v;
+      NSObject *foo;
+      return 0;
+    }
+  " HAVE_WORKING_CODE)
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceRuns` module for a more general command syntax.
+* The :module:`CheckSourceCompiles` module to check whether a source code
+  can be built.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckSourceRuns.cmake

@@ -8,49 +8,65 @@ CheckSourceRuns
 
 .. versionadded:: 3.19
 
-Check if given source compiles and links into an executable and can
-subsequently be run.
+This module provides a command to check whether a source code can be built
+and run.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckSourceRuns)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_source_runs
 
+  Checks once whether the given source code compiles and links into an
+  executable that can subsequently be run:
+
   .. code-block:: cmake
 
-    check_source_runs(<lang> <code> <resultVar>
-                      [SRC_EXT <extension>])
+    check_source_runs(<lang> <code> <variable> [SRC_EXT <extension>])
 
-  Check once that the ``<lang>`` source supplied in ``<code>`` can be built,
-  linked as an executable, and then run. The ``<code>`` must contain at least
-  a ``main()`` function, or in Fortran a ``program``.
+  This command checks once that the ``<lang>`` source code supplied in
+  ``<code>`` can be built, linked as an executable, and then run.  The
+  result of the check is stored in the internal cache variable specified by
+  ``<variable>``.
 
-  The result is stored in the internal cache variable specified by
-  ``<resultVar>``. If the code builds and runs with exit code ``0``, success is
-  indicated by boolean ``true``. Failure to build or run is indicated by boolean
-  ``false``, such as an empty string or an error message.
+  The arguments are:
 
-  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.
+  ``<lang>``
+    The programming language of the source ``<code>`` to check.  Supported
+    languages are: ``C``, ``CXX``, ``CUDA``, ``Fortran``, ``HIP``, ``OBJC``,
+    and ``OBJCXX``.
 
-  The ``<code>`` must contain a valid main program. For example:
+    .. versionadded:: 3.21
+      Support for ``HIP`` language.
 
-  .. code-block:: cmake
+  ``<code>``
+    The source code to be tested.  It must contain a valid source program.
+    For example, it must contain at least a ``main()`` function (in C/C++),
+    or a ``program`` unit (in Fortran).
 
-    check_source_runs(C
-    "#include <stdlib.h>
-    #include <stdnoreturn.h>
-    noreturn void f(){ exit(0); }
-    int main(void) { f(); return 1; }"
-    HAVE_NORETURN)
+  ``<variable>``
+    Name of the internal cache variable with the result of the check.  If
+    the code builds and runs with exit code ``0``, success is indicated by
+    a boolean true value.  Failure to build or run is indicated by a boolean
+    false value, such as an empty string or an error message.
 
-    check_source_runs(Fortran
-    "program test
-    real :: x[*]
-    call co_sum(x)
-    end program"
-    HAVE_COARRAY)
+  ``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 compile and link commands can be influenced by setting any of the
-  following variables prior to calling ``check_source_runs()``
+  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
 
@@ -66,6 +82,112 @@ subsequently be run.
 
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+Examples
+^^^^^^^^
+
+Example: Basic Usage
+""""""""""""""""""""
+
+The following example demonstrates how to use this module to check whether
+the C source code is supported and operational at runtime.  The result of
+the check is stored in the internal cache variable ``HAVE_NORETURN``.
+
+.. code-block:: cmake
+
+  include(CheckSourceRuns)
+
+  check_source_runs(C "
+    #include <stdlib.h>
+    #include <stdnoreturn.h>
+    noreturn void f(){ exit(0); }
+    int main(void) { f(); return 1; }
+  " HAVE_NORETURN)
+
+Example: Checking Fortran Code
+""""""""""""""""""""""""""""""
+
+Checking if Fortran source code runs successfully:
+
+.. code-block:: cmake
+
+  include(CheckSourceRuns)
+
+  check_source_runs(Fortran "
+    program test
+    real :: x[*]
+    call co_sum(x)
+    end program
+  " HAVE_COARRAY)
+
+Example: Checking C++ Code With Bracket Argument
+""""""""""""""""""""""""""""""""""""""""""""""""
+
+The following example demonstrates how to check whether the C++ standard
+library is functional and ``std::vector`` works at runtime.  If the source
+compiles, links, and runs successfully, internal cache variable
+``HAVE_WORKING_STD_VECTOR`` will be set to boolean true value.  Code is
+supplied using :ref:`Bracket Argument` for easier embedded quotes handling:
+
+.. code-block:: cmake
+  :force:
+
+  include(CheckSourceRuns)
+
+  check_source_runs(CXX [[
+    #include <iostream>
+    #include <vector>
+
+    int main()
+    {
+      std::vector<int> v = {1, 2, 3};
+      if (v.size() != 3) return 1;
+      std::cout << "Vector works correctly." << std::endl;
+      return 0;
+    }
+  ]] HAVE_WORKING_STD_VECTOR)
+
+Example: Isolated Check
+"""""""""""""""""""""""
+
+In the following example, this module is used in combination with the
+:module:`CMakePushCheckState` module to modify required compile definitions
+and libraries when checking whether the C function ``sched_getcpu()`` is
+supported and operational at runtime.  For example, on some systems, the
+``sched_getcpu()`` function may be available at compile time but not actually
+implemented by the kernel.  In such cases, it returns ``-1`` and sets
+``errno`` to ``ENOSYS``.  This check verifies that ``sched_getcpu()`` runs
+successfully and stores a boolean result in the internal cache variable
+``HAVE_SCHED_GETCPU``.
+
+.. code-block:: cmake
+
+  include(CheckSourceRuns)
+  include(CMakePushCheckState)
+
+  cmake_push_check_state(RESET)
+    set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE)
+
+    if(CMAKE_SYSTEM_NAME STREQUAL "Haiku")
+      set(CMAKE_REQUIRED_LIBRARIES gnu)
+    endif()
+
+    check_source_runs(C "
+      #include <sched.h>
+      int main(void)
+      {
+        if (sched_getcpu() == -1) {
+          return 1;
+        }
+        return 0;
+      }
+    " HAVE_SCHED_GETCPU)
+  cmake_pop_check_state()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSourceCompiles` module to check whether a source code
+  can be built.
 #]=======================================================================]
 
 include_guard(GLOBAL)