Merge topic 'doc-refer'

759776dcdb Help: Check*SourceRuns make text more concise.
5d42177a06 Help: Check*SourceCompiles, Check*CompilerFlag refer to new command

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9743

Modules/CheckCCompilerFlag.cmake

@@ -27,6 +27,8 @@ 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_compiler_flag` for a more general command syntax.
+
 The compile and link commands can be influenced by setting any of the
 following variables prior to calling ``check_c_compiler_flag()``
 

Modules/CheckCSourceCompiles.cmake

@@ -28,6 +28,8 @@ Check once if C source code can be built.
   ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
   functions must be declared as usual.
 
+  See also :command:`check_source_compiles` for a more general command syntax.
+
   See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the

Modules/CheckCSourceRuns.cmake

@@ -5,7 +5,7 @@
 CheckCSourceRuns
 ----------------
 
-Check if given C source compiles and links into an executable and can
+Check once if given C source compiles and links into an executable and can
 subsequently be run.
 
 .. command:: check_c_source_runs
@@ -14,18 +14,16 @@ subsequently be run.
 
     check_c_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``<code>`` can be compiled as a C source
-  file, 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).
+  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.
 
-  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.
+  The result is stored in the internal cache variable specified by
+  ``<resultVar>``. Success of build and run is indicated by boolean ``true``.
+  Failure to build or run is indicated by boolean ``false`` such as an empty
+  string or an error message.
+
+  See also :command:`check_source_runs` for a more general command syntax.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_c_source_runs()``:

Modules/CheckCXXCompilerFlag.cmake

@@ -21,6 +21,8 @@ A positive result from this check indicates only that the compiler did not
 issue a diagnostic message when given the flag.  Whether the flag has any
 effect or even a specific one is beyond the scope of this module.
 
+See also :command:`check_compiler_flag` for a more general command syntax.
+
 .. note::
   Since the :command:`try_compile` command forwards flags from variables
   like :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`, unknown flags

Modules/CheckCXXSourceCompiles.cmake

@@ -28,6 +28,8 @@ Check once if C++ source code can be built.
   ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
   functions must be declared as usual.
 
+  See also :command:`check_source_compiles` for a more general command syntax.
+
   See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the

Modules/CheckCXXSourceRuns.cmake

@@ -5,7 +5,7 @@
 CheckCXXSourceRuns
 ------------------
 
-Check if given C++ source compiles and links into an executable and can
+Check once if given C++ source compiles and links into an executable and can
 subsequently be run.
 
 .. command:: check_cxx_source_runs
@@ -14,18 +14,16 @@ subsequently be run.
 
     check_cxx_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``<code>`` can be compiled as a C++ source
-  file, 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).
+  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.
 
-  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.
+  The result is stored in the internal cache variable specified by
+  ``<resultVar>``. Success of build and run is indicated by boolean ``true``.
+  Failure to build or run is indicated by boolean ``false`` such as an empty
+  string or an error message.
+
+  See also :command:`check_source_runs` for a more general command syntax.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_cxx_source_runs()``:

Modules/CheckFortranCompilerFlag.cmake

@@ -29,6 +29,8 @@ 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_compiler_flag` for a more general command syntax.
+
 The compile and link commands can be influenced by setting any of the
 following variables prior to calling ``check_fortran_compiler_flag()``
 

Modules/CheckFortranSourceCompiles.cmake

@@ -30,6 +30,8 @@ Check once if Fortran source code can be built.
   ``SRC_EXT`` option can be used to override this with ``.<extension>`` instead--
   ``.F90`` is a typical choice.
 
+  See also :command:`check_source_compiles` for a more general command syntax.
+
   See also :command:`check_source_runs` to run compiled source.
 
   Internally, :command:`try_compile` is used to compile the source. If

Modules/CheckFortranSourceRuns.cmake

@@ -7,7 +7,7 @@ CheckFortranSourceRuns
 
 .. versionadded:: 3.14
 
-Check if given Fortran source compiles and links into an executable and can
+Check once if given Fortran source compiles and links into an executable and can
 subsequently be run.
 
 .. command:: check_fortran_source_runs
@@ -17,9 +17,13 @@ subsequently be run.
     check_fortran_source_runs(<code> <resultVar>
         [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``.
+  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``.
+
+  The result is stored in the internal cache variable specified by
+  ``<resultVar>``. Success of build and run is indicated by boolean ``true``.
+  Failure to build or run is indicated by boolean ``false`` such as an empty
+  string or an error message.
 
   .. code-block:: cmake
 
@@ -29,25 +33,10 @@ subsequently be run.
     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
-  the Fortran compiler version being used. Some of these failures only occur at runtime
-  instead of linktime, and a trivial runtime example can catch the issue before the
-  main build process.
-
-  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).
-
   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.
 
-  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` for a more general command syntax.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_fortran_source_runs()``:

Modules/CheckOBJCCompilerFlag.cmake

@@ -29,6 +29,8 @@ 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_compiler_flag` for a more general command syntax.
+
 The compile and link commands can be influenced by setting any of the
 following variables prior to calling ``check_objc_compiler_flag()``
 

Modules/CheckOBJCSourceCompiles.cmake

@@ -30,6 +30,8 @@ Check once if Objective-C source can be built.
   ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
   functions must be declared as usual.
 
+  See also :command:`check_source_compiles` for a more general command syntax.
+
   See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the

Modules/CheckOBJCSourceRuns.cmake

@@ -7,8 +7,8 @@ CheckOBJCSourceRuns
 
 .. versionadded:: 3.16
 
-Check if given Objective-C source compiles and links into an executable and can
-subsequently be run.
+Check once if given Objective-C source compiles and links into an executable and
+can subsequently be run.
 
 .. command:: check_objc_source_runs
 
@@ -16,18 +16,16 @@ subsequently be run.
 
     check_objc_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``<code>`` can be compiled as a Objective-C source
-  file, 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).
+  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.
 
-  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.
+  The result is stored in the internal cache variable specified by
+  ``<resultVar>``. Success of build and run is indicated by boolean ``true``.
+  Failure to build or run is indicated by boolean ``false`` such as an empty
+  string or an error message.
+
+  See also :command:`check_source_runs` for a more general command syntax.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_objc_source_runs()``

Modules/CheckOBJCXXCompilerFlag.cmake

@@ -29,6 +29,8 @@ 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_compiler_flag` for a more general command syntax.
+
 The compile and link commands can be influenced by setting any of the
 following variables prior to calling ``check_objcxx_compiler_flag()``
 

Modules/CheckOBJCXXSourceCompiles.cmake

@@ -30,6 +30,8 @@ Check once if Objective-C++ source can be built.
   ``STATIC_LIBRARY``, the source is compiled but not linked. In any case, all
   functions must be declared as usual.
 
+  See also :command:`check_source_compiles` for a more general command syntax.
+
   See also :command:`check_source_runs` to run compiled source.
 
   The compile and link commands can be influenced by setting any of the

Modules/CheckOBJCXXSourceRuns.cmake

@@ -7,8 +7,8 @@ CheckOBJCXXSourceRuns
 
 .. versionadded:: 3.16
 
-Check if given Objective-C++ source compiles and links into an executable and can
-subsequently be run.
+Check once if given Objective-C++ source compiles and links into an executable
+and can subsequently be run.
 
 .. command:: check_objcxx_source_runs
 
@@ -16,18 +16,16 @@ subsequently be run.
 
     check_objcxx_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``<code>`` can be compiled as a Objective-C++ source
-  file, 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).
+  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.
 
-  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.
+  The result is stored in the internal cache variable specified by
+  ``<resultVar>``. Success of build and run is indicated by boolean ``true``.
+  Failure to build or run is indicated by boolean ``false`` such as an empty
+  string or an error message.
+
+  See also :command:`check_source_runs` for a more general command syntax.
 
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_objcxx_source_runs()``

Modules/CheckSourceRuns.cmake

@@ -18,12 +18,14 @@ subsequently be run.
     check_source_runs(<lang> <code> <resultVar>
                       [SRC_EXT <extension>])
 
-  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.
-  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).
+  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``.
+
+  The result is stored in the internal cache variable specified by
+  ``<resultVar>``. Success of build and run is indicated by boolean ``true``.
+  Failure to build or run is indicated by boolean ``false`` such as 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
@@ -47,12 +49,6 @@ subsequently be run.
     end program"
     HAVE_COARRAY)
 
-  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.
-
   The compile and link commands can be influenced by setting any of the
   following variables prior to calling ``check_source_runs()``