From b2e7736d81dbdf80818805035020eb9f4d5181a1 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Mon, 26 May 2025 03:12:53 +0200 Subject: [PATCH] CheckIncludeFile*: Sync documentation - Added intro code blocks showing how to include these modules. - Used "command" instead of "macro". - Mentioned policy CMP0075. - Added additional example to CheckIncludeFile showing how to use CMAKE_REQUIRED_* variable. --- Help/policy/CMP0075.rst | 10 ++--- Help/release/3.11.rst | 6 +-- Help/release/3.12.rst | 6 +-- Modules/CheckIncludeFile.cmake | 73 ++++++++++++++++++++++++++----- Modules/CheckIncludeFileCXX.cmake | 40 ++++++++++++----- Modules/CheckIncludeFiles.cmake | 53 +++++++++++++++------- 6 files changed, 140 insertions(+), 48 deletions(-) diff --git a/Help/policy/CMP0075.rst b/Help/policy/CMP0075.rst index a1022eec5c..8d044742c5 100644 --- a/Help/policy/CMP0075.rst +++ b/Help/policy/CMP0075.rst @@ -7,18 +7,18 @@ Include file check macros honor ``CMAKE_REQUIRED_LIBRARIES``. In CMake 3.12 and above, the -* ``check_include_file`` macro in the :module:`CheckIncludeFile` module, the -* ``check_include_file_cxx`` macro in the +* ``check_include_file()`` command in the :module:`CheckIncludeFile` module, the +* ``check_include_file_cxx()`` command in the :module:`CheckIncludeFileCXX` module, and the -* ``check_include_files`` macro in the :module:`CheckIncludeFiles` module +* ``check_include_files()`` command in the :module:`CheckIncludeFiles` module now prefer to link the check executable to the libraries listed in the ``CMAKE_REQUIRED_LIBRARIES`` variable. This policy provides compatibility with projects that have not been updated to expect this behavior. The ``OLD`` behavior for this policy is to ignore ``CMAKE_REQUIRED_LIBRARIES`` -in the include file check macros. The ``NEW`` behavior of this policy is to -honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check macros. +in the include file check commands. The ``NEW`` behavior of this policy is to +honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check commands. .. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.12 .. |WARNS_OR_DOES_NOT_WARN| replace:: warns diff --git a/Help/release/3.11.rst b/Help/release/3.11.rst index 8fc27f694f..d618ff0a22 100644 --- a/Help/release/3.11.rst +++ b/Help/release/3.11.rst @@ -276,9 +276,9 @@ Changes made since CMake 3.11.0 include the following. 3.11.1 ------ -* The :module:`CheckIncludeFile` module ``check_include_file`` macro, - :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro, - and :module:`CheckIncludeFiles` module ``check_include_files`` macro +* The :module:`CheckIncludeFile` module ``check_include_file()`` command, + :module:`CheckIncludeFileCXX` module ``check_include_file_cxx()`` command, + and :module:`CheckIncludeFiles` module ``check_include_files()`` command were taught to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable in CMake 3.11.0. This has been reverted due to changing behavior of checks for existing projects. It may be restored in the future diff --git a/Help/release/3.12.rst b/Help/release/3.12.rst index dcdae1d1ba..0a8f6d553c 100644 --- a/Help/release/3.12.rst +++ b/Help/release/3.12.rst @@ -282,15 +282,15 @@ Other Changes :command:`install` documentation so that external packaging software can take advantage of CPack-style component installs. -* The :module:`CheckIncludeFile` module ``check_include_file`` macro +* The :module:`CheckIncludeFile` module ``check_include_file()`` command learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. See policy :policy:`CMP0075`. -* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro +* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx()`` command learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. See policy :policy:`CMP0075`. -* The :module:`CheckIncludeFiles` module ``check_include_files`` macro +* The :module:`CheckIncludeFiles` module ``check_include_files()`` command learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. See policy :policy:`CMP0075`. diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake index bb46cf4ddc..dab4f6878c 100644 --- a/Modules/CheckIncludeFile.cmake +++ b/Modules/CheckIncludeFile.cmake @@ -5,21 +5,37 @@ CheckIncludeFile ---------------- -Provides a macro to check if a header file can be included in ``C``. +This module provides a command to check C header file. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckIncludeFile) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_include_file + Checks once whether a header file can be included in C code: + .. code-block:: cmake check_include_file( []) - Check if the given ```` file may be included in a ``C`` - source file and store the result in an internal cache entry named - ````. The optional third argument may be used to add - compilation flags to the check (or use ``CMAKE_REQUIRED_FLAGS`` below). + This command checks once whether the given ```` header file + exists and can be included in a C source file. The result of the check + is stored in an internal cache variable named ````. The + optional third argument may be used to add additional compilation flags + to the check (or use the ``CMAKE_REQUIRED_FLAGS`` variable below). -The following variables may be set before calling this macro to modify -the way the check is run: + .. 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 @@ -35,10 +51,17 @@ the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst + .. versionadded:: 3.12 + The ``CMAKE_REQUIRED_LIBRARIES`` variable, if policy :policy:`CMP0075` is + set to ``NEW``. + Examples ^^^^^^^^ -Checking whether the ``C`` header ```` exists and storing the check +Example: Checking C Header +"""""""""""""""""""""""""" + +Checking whether the C header ```` exists and storing the check result in the ``HAVE_UNISTD_H`` cache variable: .. code-block:: cmake @@ -47,12 +70,40 @@ result in the ``HAVE_UNISTD_H`` cache variable: check_include_file(unistd.h HAVE_UNISTD_H) +Example: Isolated Check +""""""""""""""""""""""" + +In the following example, this module is used in combination with the +:module:`CMakePushCheckState` module to temporarily modify the required +compile definitions (via ``CMAKE_REQUIRED_DEFINITIONS``) and verify whether +the C header ``ucontext.h`` is available. The result is stored +in the internal cache variable ``HAVE_UCONTEXT_H``. + +For example, on macOS, the ``ucontext`` API is deprecated, and headers may +be hidden unless certain feature macros are defined. In particular, +defining ``_XOPEN_SOURCE`` (without a value) can expose the necessary +symbols without enabling broader POSIX or SUS (Single Unix Specification) +features (values 500 or greater). + +.. code-block:: cmake + + include(CheckIncludeFile) + include(CMakePushCheckState) + + cmake_push_check_state(RESET) + if(CMAKE_SYSTEM_NAME STREQUAL "Darwin") + set(CMAKE_REQUIRED_DEFINITIONS -D_XOPEN_SOURCE) + endif() + + check_include_files(ucontext.h HAVE_UCONTEXT_H) + cmake_pop_check_state() + See Also ^^^^^^^^ -* The :module:`CheckIncludeFileCXX` module to check for single ``C++`` header. -* The :module:`CheckIncludeFiles` module to check for one or more ``C`` or - ``C++`` headers at once. +* The :module:`CheckIncludeFileCXX` module to check for single C++ header. +* The :module:`CheckIncludeFiles` module to check for one or more C or + C++ headers at once. #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckIncludeFileCXX.cmake b/Modules/CheckIncludeFileCXX.cmake index d065f97ae8..54b7f55845 100644 --- a/Modules/CheckIncludeFileCXX.cmake +++ b/Modules/CheckIncludeFileCXX.cmake @@ -5,21 +5,37 @@ CheckIncludeFileCXX ------------------- -Provides a macro to check if a header file can be included in ``CXX``. +This module provides a command to check a C++ header file. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckIncludeFileCXX) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_include_file_cxx + Checks once whether a header file can be included in C++ code: + .. code-block:: cmake check_include_file_cxx( []) - Check if the given ```` file may be included in a ``CXX`` - source file and store the result in an internal cache entry named - ````. The optional third argument may be used to add - compilation flags to the check (or use ``CMAKE_REQUIRED_FLAGS`` below). + This command checks once whether the given ```` header file + exists and can be included in a ``CXX`` source file. The result of the + check is stored in an internal cache variable named ````. The + optional third argument may be used to add additional compilation flags + to the check (or use the ``CMAKE_REQUIRED_FLAGS`` variable below). -The following variables may be set before calling this macro to modify -the way the check is run: + .. 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 @@ -35,6 +51,10 @@ the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst + .. versionadded:: 3.12 + The ``CMAKE_REQUIRED_LIBRARIES`` variable, if policy :policy:`CMP0075` is + set to ``NEW``. + Examples ^^^^^^^^ @@ -50,9 +70,9 @@ check result in the ``HAVE_STDFLOAT_HEADER`` cache variable: See Also ^^^^^^^^ -* The :module:`CheckIncludeFile` module to check for single ``C`` header. -* The :module:`CheckIncludeFiles` module to check for one or more ``C`` or - ``C++`` headers at once. +* The :module:`CheckIncludeFile` module to check for single C header. +* The :module:`CheckIncludeFiles` module to check for one or more C or + C++ headers at once. #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckIncludeFiles.cmake b/Modules/CheckIncludeFiles.cmake index c91f65aa85..7debbe66fa 100644 --- a/Modules/CheckIncludeFiles.cmake +++ b/Modules/CheckIncludeFiles.cmake @@ -5,27 +5,44 @@ CheckIncludeFiles ----------------- -Provides a macro to check if a list of one or more header files can -be included together. +This module provides a command to check one or more C/C++ header files. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckIncludeFiles) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_include_files + Checks once whether one or more header files can be included together in + source code: + .. code-block:: cmake - check_include_files("" [LANGUAGE ]) + check_include_files( [LANGUAGE ]) - Check if the given ```` list may be included together - in a source file and store the result in an internal cache - entry named ````. Specify the ```` argument - as a :ref:`;-list ` of header file names. + This command checks once whether the given ```` list of header + files exist and can be included together in a C or C++ source file. The + result of the check is stored in an internal cache variable named + ````. Specify the ```` argument as a + :ref:`semicolon-separated list ` of header file + names. If ``LANGUAGE`` is set, the specified compiler will be used to perform the - check. Acceptable values are ``C`` and ``CXX``. If not set, the C compiler - will be used if enabled. If the C compiler is not enabled, the C++ - compiler will be used if enabled. + check. Acceptable values are ``C`` and ``CXX``. If not set, the C + compiler will be used if enabled. If the C compiler is not enabled, the + C++ compiler will be used if enabled. -The following variables may be set before calling this macro to modify -the way the check is run: + .. 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 @@ -41,11 +58,15 @@ the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst + .. versionadded:: 3.12 + The ``CMAKE_REQUIRED_LIBRARIES`` variable, if policy :policy:`CMP0075` is + set to ``NEW``. + Examples ^^^^^^^^ -Checking whether one or more ``C`` headers exist and storing the check result -in cache variables: +Checking one or more C headers and storing the check result in cache +variables: .. code-block:: cmake @@ -74,8 +95,8 @@ languages are enabled in the project: See Also ^^^^^^^^ -* The :module:`CheckIncludeFile` module to check for single ``C`` header. -* The :module:`CheckIncludeFileCXX` module to check for single ``C++`` header. +* The :module:`CheckIncludeFile` module to check for a single C header. +* The :module:`CheckIncludeFileCXX` module to check for a single C++ header. #]=======================================================================] include_guard(GLOBAL)