Help: check_*source_compiles and CMAKE_TRY_COMPILE_TARGET_TYPE

Ref: #26103

6 files changed, 101 insertions, 98 deletions

diff --git a/Modules/CheckCSourceCompiles.cmake b/Modules/CheckCSourceCompiles.cmake
index 79aca93..c01b6cf 100644
--- a/Modules/CheckCSourceCompiles.cmake
+++ b/Modules/CheckCSourceCompiles.cmake
@@ -5,7 +5,7 @@
 CheckCSourceCompiles
 --------------------
 
-Check if given C source compiles and links into an executable.
+Check once if C source code can be built.
 
 .. command:: check_c_source_compiles
 
@@ -14,19 +14,21 @@ Check if given C source compiles and links into an executable.
     check_c_source_compiles(<code> <resultVar>
                             [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``<code>`` can be compiled as a C source
-  file 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
+  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.
+
+  If ``FAIL_REGEX`` is provided, then failure is determined by checking
+  if anything in the compiler output matches any of the specified regular
   expressions.
 
-  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 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.
+
+  See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_c_source_compiles()``:
diff --git a/Modules/CheckCXXSourceCompiles.cmake b/Modules/CheckCXXSourceCompiles.cmake
index 7531236..7c03c4a 100644
--- a/Modules/CheckCXXSourceCompiles.cmake
+++ b/Modules/CheckCXXSourceCompiles.cmake
@@ -5,7 +5,7 @@
 CheckCXXSourceCompiles
 ----------------------
 
-Check if given C++ source compiles and links into an executable.
+Check once if C++ source code can be built.
 
 .. command:: check_cxx_source_compiles
 
@@ -14,19 +14,21 @@ Check if given C++ source compiles and links into an executable.
     check_cxx_source_compiles(<code> <resultVar>
                               [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``<code>`` can be compiled as a C++ source
-  file 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
+  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.
+
+  If ``FAIL_REGEX`` is provided, then failure is determined by checking
+  if anything in the compiler output matches any of the specified regular
   expressions.
 
-  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 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.
+
+  See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_cxx_source_compiles()``:
diff --git a/Modules/CheckFortranSourceCompiles.cmake b/Modules/CheckFortranSourceCompiles.cmake
index ed374ef..4cbe67a 100644
--- a/Modules/CheckFortranSourceCompiles.cmake
+++ b/Modules/CheckFortranSourceCompiles.cmake
@@ -7,7 +7,7 @@ CheckFortranSourceCompiles
 
 .. versionadded:: 3.1
 
-Check if given Fortran source compiles and links into an executable.
+Check once if Fortran source code can be built.
 
 .. command:: check_fortran_source_compiles
 
@@ -18,40 +18,25 @@ Check if given Fortran source compiles and links into an executable.
         [SRC_EXT <extension>]
     )
 
-  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``.
-
-  .. code-block:: cmake
-
-    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 run the compiled code.
-
-  The result will be stored in the internal cache
-  variable ``<resultVar>``, with a boolean true value for success and boolean
-  false for failure.
+  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.
 
   If ``FAIL_REGEX`` is provided, then failure is determined by checking
-  if anything in the output matches any of the specified regular expressions.
+  if anything in the compiler output matches any of the specified regular
+  expressions.
 
   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.
 
-  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.
+  See also :command:`check_source_runs` to run compiled source.
+
+  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.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_fortran_source_compiles()``:
diff --git a/Modules/CheckOBJCSourceCompiles.cmake b/Modules/CheckOBJCSourceCompiles.cmake
index bc0cac1..c6e09db 100644
--- a/Modules/CheckOBJCSourceCompiles.cmake
+++ b/Modules/CheckOBJCSourceCompiles.cmake
@@ -7,7 +7,7 @@ CheckOBJCSourceCompiles
 
 .. versionadded:: 3.16
 
-Check if given Objective-C source compiles and links into an executable.
+Check once if Objective-C source can be built.
 
 .. command:: check_objc_source_compiles
 
@@ -16,19 +16,21 @@ Check if given Objective-C source compiles and links into an executable.
     check_objc_source_compiles(<code> <resultVar>
                                [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``<code>`` can be compiled as a Objectie-C source
-  file 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
+  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.
+
+  If ``FAIL_REGEX`` is provided, then failure is determined by checking
+  if anything in the compiler output matches any of the specified regular
   expressions.
 
-  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 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.
+
+  See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_objc_source_compiles()``
diff --git a/Modules/CheckOBJCXXSourceCompiles.cmake b/Modules/CheckOBJCXXSourceCompiles.cmake
index 366d7d5..4a18c21 100644
--- a/Modules/CheckOBJCXXSourceCompiles.cmake
+++ b/Modules/CheckOBJCXXSourceCompiles.cmake
@@ -7,7 +7,7 @@ CheckOBJCXXSourceCompiles
 
 .. versionadded:: 3.16
 
-Check if given Objective-C++ source compiles and links into an executable.
+Check once if Objective-C++ source can be built.
 
 .. command:: check_objcxx_source_compiles
 
@@ -16,19 +16,21 @@ Check if given Objective-C++ source compiles and links into an executable.
     check_objcxx_source_compiles(<code> <resultVar>
                                  [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``<code>`` can be compiled as a Objective-C++ source
-  file 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
+  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.
+
+  If ``FAIL_REGEX`` is provided, then failure is determined by checking
+  if anything in the compiler output matches any of the specified regular
   expressions.
 
-  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 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.
+
+  See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_objcxx_source_compiles()``
diff --git a/Modules/CheckSourceCompiles.cmake b/Modules/CheckSourceCompiles.cmake
index af905a4..b79726a 100644
--- a/Modules/CheckSourceCompiles.cmake
+++ b/Modules/CheckSourceCompiles.cmake
@@ -8,7 +8,7 @@ CheckSourceCompiles
 
 .. versionadded:: 3.19
 
-Check if given source compiles and links into an executable.
+Check once if source code can be built for a given language.
 
 .. command:: check_source_compiles
 
@@ -18,40 +18,50 @@ Check if given source compiles and links into an executable.
                           [FAIL_REGEX <regex1> [<regex2>...]]
                           [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. 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
+  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.
+
+  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:
+  The C example checks if the compiler supports the ``noreturn`` attribute:
 
   .. code-block:: cmake
 
+    set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY")
+
     check_source_compiles(C
-    "#include <stdlib.h>
-    #include <stdnoreturn.h>
-    noreturn void f(){ exit(0); }
-    int main(void) { f(); return 1; }"
+    "#if !__has_c_attribute(noreturn)
+    #error \"No noreturn attribute\"
+    #endif"
     HAVE_NORETURN)
 
+  The Fortran example checks if the compiler supports the ``pure`` procedure
+  attribute:
+
+  .. code-block:: cmake
+
+    set(CMAKE_TRY_COMPILE_TARGET_TYPE "STATIC_LIBRARY")
+
     check_source_compiles(Fortran
-    "program test
-    error stop
-    end program"
-    HAVE_ERROR_STOP)
-
-  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.
+    "pure subroutine foo()
+    end subroutine"
+    HAVE_PURE)
+
+  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.
+
+  See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_source_compiles()``: