Help: CheckSource{Compiles,Runs}: fix typo and clarify

4 files changed, 62 insertions, 20 deletions

diff --git a/Modules/CheckFortranSourceCompiles.cmake b/Modules/CheckFortranSourceCompiles.cmake
index e134329..8dcc1d5 100644
--- a/Modules/CheckFortranSourceCompiles.cmake
+++ b/Modules/CheckFortranSourceCompiles.cmake
@@ -19,18 +19,22 @@ Check if given Fortran source compiles and links into an executable.
     )
 
   Checks that the source supplied in ``<code>`` can be compiled as a Fortran
-  source file and linked as an executable. The ``<code>`` must be a Fortran program
-  containing at least an ``end`` statement--for example:
+  source file and linked as an executable. The ``<code>`` must be a Fortran
+  ``program``.
 
   .. code-block:: cmake
 
-    check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
+    check_fortran_source_compiles("program test
+    error stop
+    end program"
+    HAVE_ERROR_STOP
+    SRC_EXT .F90)
 
   This command can help avoid costly build processes when a compiler lacks support
   for a necessary feature, or a particular vendor library is not compatible with
   the Fortran compiler version being used. This generate-time check may advise the
   user of such before the main build process. See also the
-  :command:`check_fortran_source_runs` command to actually run the compiled code.
+  :command:`check_fortran_source_runs` command to run the compiled code.
 
   The result will be stored in the internal cache
   variable ``<resultVar>``, with a boolean true value for success and boolean
diff --git a/Modules/CheckFortranSourceRuns.cmake b/Modules/CheckFortranSourceRuns.cmake
index 28f713f..985c765 100644
--- a/Modules/CheckFortranSourceRuns.cmake
+++ b/Modules/CheckFortranSourceRuns.cmake
@@ -18,12 +18,16 @@ subsequently be run.
         [SRC_EXT <extension>])
 
   Check that the source supplied in ``<code>`` can be compiled as a Fortran source
-  file, linked as an executable and then run. The ``<code>`` must be a Fortran program
-  containing at least an ``end`` statement--for example:
+  file, linked as an executable and then run. The ``<code>`` must be a Fortran
+  ``program``.
 
   .. code-block:: cmake
 
-    check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
+    check_fortran_source_runs("program test
+    real :: x[*]
+    call co_sum(x)
+    end program"
+    HAVE_COARRAY)
 
   This command can help avoid costly build processes when a compiler lacks support
   for a necessary feature, or a particular vendor library is not compatible with
diff --git a/Modules/CheckSourceCompiles.cmake b/Modules/CheckSourceCompiles.cmake
index ad74c3c..9788798 100644
--- a/Modules/CheckSourceCompiles.cmake
+++ b/Modules/CheckSourceCompiles.cmake
@@ -19,17 +19,34 @@ Check if given source compiles and links into an executable.
                           [SRC_EXT <extension>])
 
   Check that the source supplied in ``<code>`` can be compiled as a source
-  file for the requested language and linked as an executable (so it must
-  contain at least a ``main()`` function). The result will be stored in the
-  internal cache variable specified by ``<resultVar>``, with a boolean true
-  value for success and boolean false for failure. If ``FAIL_REGEX`` is
-  provided, then failure is determined by checking if anything in the output
-  matches any of the specified regular expressions.
+  file for the requested language and linked as an executable. The result
+  will be stored in the internal cache variable specified by ``<resultVar>``,
+  with a boolean true value for success and boolean false for failure. If
+  ``FAIL_REGEX`` is provided, then failure is determined by checking if
+  anything in the compiler output matches any of the specified regular
+  expressions.
 
   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.
 
+  The ``<code>`` must contain a valid main program. For example:
+
+  .. code-block:: cmake
+
+    check_source_compiles(C
+    "#include <stdlib.h>
+    #include <stdnoreturn.h>
+    noreturn void f(){ exit(0); }
+    int main(void) { f(); return 1; }"
+    HAVE_NORETURN)
+
+    check_source_compiles(Fortran
+    "program test
+    error stop
+    end program"
+    HAVE_ERROR_STOP)
+
   The underlying check is performed by the :command:`try_compile` command. The
   compile and link commands can be influenced by setting any of the following
   variables prior to calling ``check_source_compiles()``:
@@ -73,7 +90,6 @@ Check if given source compiles and links into an executable.
 
 #]=======================================================================]
 
-
 include_guard(GLOBAL)
 include(Internal/CheckSourceCompiles)
 
diff --git a/Modules/CheckSourceRuns.cmake b/Modules/CheckSourceRuns.cmake
index 8f1cf01..e2fa579 100644
--- a/Modules/CheckSourceRuns.cmake
+++ b/Modules/CheckSourceRuns.cmake
@@ -20,22 +20,40 @@ subsequently be run.
 
   Check that the source supplied in ``<code>`` can be compiled as a source
   file for the requested language, linked as an executable and then run.
-  The ``<code>`` must contain at least a ``main()`` function. If the ``<code>``
-  could be built and run successfully, the internal cache variable specified by
-  ``<resultVar>`` will be set to 1, otherwise it will be set to an value that
-  evaluates to boolean false (e.g. an empty string or an error message).
+  If the ``<code>`` could be built and run successfully, the internal cache variable
+  specified by ``<resultVar>`` will be set to 1, otherwise it will be set to
+  a value that evaluates to boolean false (e.g. an empty string or an error
+  message).
 
   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.
 
+  The ``<code>`` must contain a valid main program. For example:
+
+  .. code-block:: cmake
+
+    check_source_runs(C
+    "#include <stdlib.h>
+    #include <stdnoreturn.h>
+    noreturn void f(){ exit(0); }
+    int main(void) { f(); return 1; }"
+    HAVE_NORETURN)
+
+    check_source_runs(Fortran
+    "program test
+    real :: x[*]
+    call co_sum(x)
+    end program"
+    HAVE_COARRAY)
+
   The underlying check is performed by the :command:`try_run` command. The
   compile and link commands can be influenced by setting any of the following
-  variables prior to calling ``check_objc_source_runs()``:
+  variables prior to calling ``check_source_runs()``:
 
   ``CMAKE_REQUIRED_FLAGS``
     Additional flags to pass to the compiler. Note that the contents of
-    :variable:`CMAKE_OBJC_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated
+    :variable:`CMAKE_<LANG>_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated
     configuration-specific variable are automatically added to the compiler
     command before the contents of ``CMAKE_REQUIRED_FLAGS``.