From c5980ad8688c63f39a265da67ce8ce7490a0ceb2 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Sun, 25 May 2025 23:40:07 +0200 Subject: [PATCH] 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 | 64 +++++++-- Modules/CheckCXXSourceRuns.cmake | 73 ++++++++-- Modules/CheckFortranSourceRuns.cmake | 80 +++++++---- Modules/CheckOBJCSourceRuns.cmake | 66 +++++++-- Modules/CheckOBJCXXSourceRuns.cmake | 68 ++++++++-- Modules/CheckSourceRuns.cmake | 192 ++++++++++++++++++++++----- 6 files changed, 428 insertions(+), 115 deletions(-) diff --git a/Modules/CheckCSourceRuns.cmake b/Modules/CheckCSourceRuns.cmake index 84f6e04ac3..f1188a3c18 100644 --- a/Modules/CheckCSourceRuns.cmake +++ b/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 + Checks once whether the given C source code compiles and links into an + executable that can subsequently be run: + .. code-block:: cmake - check_c_source_runs( ) + check_c_source_runs( ) - Check once that the source supplied in ```` can be built, linked as an - executable, and then run. The ```` must contain at least a ``main()`` - function. + The C source supplied in ```` must contain at least a ``main()`` + function. The result of the check is stored in the internal cache variable + specified by ````. 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 result is stored in the internal cache variable specified by - ````. 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. + .. rubric:: Variables Affecting the Check - 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()``: + 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 + #include + 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) diff --git a/Modules/CheckCXXSourceRuns.cmake b/Modules/CheckCXXSourceRuns.cmake index 2d5d0cfdc6..47559f3d3d 100644 --- a/Modules/CheckCXXSourceRuns.cmake +++ b/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 + Checks once whether the given C++ source code compiles and links into an + executable that can subsequently be run: + .. code-block:: cmake - check_cxx_source_runs( ) + check_cxx_source_runs( ) - Check once that the source supplied in ```` can be built, linked as an - executable, and then run. The ```` must contain at least a ``main()`` - function. + The C++ source supplied in ```` must contain at least a ``main()`` + function. The result of the check is stored in the internal cache variable + specified by ````. 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 result is stored in the internal cache variable specified by - ````. 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. + .. rubric:: Variables Affecting the Check - 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()``: + 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 + #include + + int main() + { + std::vector 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) diff --git a/Modules/CheckFortranSourceRuns.cmake b/Modules/CheckFortranSourceRuns.cmake index 2f63b37045..3801a1e980 100644 --- a/Modules/CheckFortranSourceRuns.cmake +++ b/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. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckFortranSourceRuns) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_fortran_source_runs - .. code-block:: cmake - - check_fortran_source_runs( - [SRC_EXT ]) - - Check once that the source supplied in ```` can be built, linked as an - executable, and then run. The ```` must contain a Fortran ``program``. - - The result is stored in the internal cache variable specified by - ````. 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( [SRC_EXT ]) - By default, the test source file will be given a ``.F90`` file extension. The - ``SRC_EXT`` option can be used to override this with ``.`` instead. + The Fortran source supplied in ```` must contain a Fortran ``program`` + unit. The result of the check is stored in the internal cache variable + specified by ````. 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. + The options are: - The compile and link commands can be influenced by setting any of the - following variables prior to calling ``check_fortran_source_runs()``: + ``SRC_EXT `` + 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 ``.`` 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 @@ -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) diff --git a/Modules/CheckOBJCSourceRuns.cmake b/Modules/CheckOBJCSourceRuns.cmake index 268765f103..773c64a9cb 100644 --- a/Modules/CheckOBJCSourceRuns.cmake +++ b/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 + Checks once whether the given Objective-C source code compiles and links + into an executable that can subsequently be run: + .. code-block:: cmake - check_objc_source_runs( ) + check_objc_source_runs( ) - Check once that the source supplied in ```` can be built, linked as an - executable, and then run. The ```` must contain at least a ``main()`` - function. + The Objective-C source supplied in ```` must contain at least a + ``main()`` function. The result of the check is stored in the internal + cache variable specified by ````. 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 result is stored in the internal cache variable specified by - ````. 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. + .. rubric:: Variables Affecting the Check - 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()`` + 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 + 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) diff --git a/Modules/CheckOBJCXXSourceRuns.cmake b/Modules/CheckOBJCXXSourceRuns.cmake index eec663bde3..209a73b570 100644 --- a/Modules/CheckOBJCXXSourceRuns.cmake +++ b/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 + Checks once whether the given Objective-C++ source code compiles and links + into an executable that can subsequently be run: + .. code-block:: cmake - check_objcxx_source_runs( ) + check_objcxx_source_runs( ) - Check once that the source supplied in ```` can be built, linked as an - executable, and then run. The ```` must contain at least a ``main()`` - function. + The Objective-C++ source supplied in ```` must contain at least a + ``main()`` function. The result of the check is stored in the internal + cache variable specified by ````. 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 result is stored in the internal cache variable specified by - ````. 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. + .. rubric:: Variables Affecting the Check - 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()`` + 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 + #import + int main() + { + std::vector 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) diff --git a/Modules/CheckSourceRuns.cmake b/Modules/CheckSourceRuns.cmake index e86ef9bfda..0874a1f43e 100644 --- a/Modules/CheckSourceRuns.cmake +++ b/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 - .. code-block:: cmake - - check_source_runs( - [SRC_EXT ]) - - Check once that the ```` source supplied in ```` can be built, - linked as an executable, and then run. The ```` must contain at least - a ``main()`` function, or in Fortran a ``program``. - - The result is stored in the internal cache variable specified by - ````. 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. - - 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 ``.`` instead. - - The ```` must contain a valid main program. For example: + Checks once whether the given source code compiles and links into an + executable that can subsequently be run: .. code-block:: cmake - check_source_runs(C - "#include - #include - noreturn void f(){ exit(0); } - int main(void) { f(); return 1; }" - HAVE_NORETURN) + check_source_runs( [SRC_EXT ]) - check_source_runs(Fortran - "program test - real :: x[*] - call co_sum(x) - end program" - HAVE_COARRAY) + This command checks once that the ```` source code supplied in + ```` can be built, linked as an executable, and then run. The + result of the check is stored in the internal cache variable specified by + ````. - The compile and link commands can be influenced by setting any of the - following variables prior to calling ``check_source_runs()`` + The arguments are: + + ```` + The programming language of the source ```` to check. Supported + languages are: ``C``, ``CXX``, ``CUDA``, ``Fortran``, ``HIP``, ``OBJC``, + and ``OBJCXX``. + + .. versionadded:: 3.21 + Support for ``HIP`` language. + + ```` + 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). + + ```` + 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. + + ``SRC_EXT `` + 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 ``.`` 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 @@ -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 + #include + 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 + #include + + int main() + { + std::vector 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 + 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)