From 5000f895fd87e6ace179edfb553a4fef09781ff5 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Thu, 28 Aug 2025 00:27:20 +0200 Subject: [PATCH] CheckIncludeFiles: Document version 3.11 for LANGUAGE option - The check_include_files(LANGUAGE) option was added in CMake 3.11. - Additionally, this syncs the documentation style for the other modules that check headers as they are commonly browsed together. - Fixed typo in CheckIncludeFile module example. --- Modules/CheckIncludeFile.cmake | 25 +++++++++++++++++-------- Modules/CheckIncludeFileCXX.cmake | 21 +++++++++++++++------ Modules/CheckIncludeFiles.cmake | 30 ++++++++++++++++++------------ 3 files changed, 50 insertions(+), 26 deletions(-) diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake index dab4f6878c..3bd46527c9 100644 --- a/Modules/CheckIncludeFile.cmake +++ b/Modules/CheckIncludeFile.cmake @@ -20,17 +20,26 @@ This module provides the following command: .. command:: check_include_file - Checks once whether a header file can be included in C code: + Checks once whether a header file exists and can be included in C code: .. code-block:: cmake check_include_file( []) - 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). + .. rubric:: The arguments are: + + ```` + A header file to be checked. + + ```` + The name of the variable to store the result of the check. This + variable will be created as an internal cache variable. + + ```` + (Optional) A :ref:`semicolon-separated list ` of + additional compilation flags to be added to the check. Alternatively, + flags can be also specified with the ``CMAKE_REQUIRED_FLAGS`` variable + below. .. rubric:: Variables Affecting the Check @@ -76,7 +85,7 @@ 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 +the C header ```` 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 @@ -95,7 +104,7 @@ features (values 500 or greater). set(CMAKE_REQUIRED_DEFINITIONS -D_XOPEN_SOURCE) endif() - check_include_files(ucontext.h HAVE_UCONTEXT_H) + check_include_file(ucontext.h HAVE_UCONTEXT_H) cmake_pop_check_state() See Also diff --git a/Modules/CheckIncludeFileCXX.cmake b/Modules/CheckIncludeFileCXX.cmake index 54b7f55845..e0eae7b9aa 100644 --- a/Modules/CheckIncludeFileCXX.cmake +++ b/Modules/CheckIncludeFileCXX.cmake @@ -20,17 +20,26 @@ This module provides the following command: .. command:: check_include_file_cxx - Checks once whether a header file can be included in C++ code: + Checks once whether a header file exists and can be included in C++ code: .. code-block:: cmake check_include_file_cxx( []) - 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). + .. rubric:: The arguments are: + + ```` + A header file to be checked. + + ```` + The name of the variable to store the result of the check. This + variable will be created as an internal cache variable. + + ```` + (Optional) A :ref:`semicolon-separated list ` of + additional compilation flags to be added to the check. Alternatively, + flags can be also specified with the ``CMAKE_REQUIRED_FLAGS`` variable + below. .. rubric:: Variables Affecting the Check diff --git a/Modules/CheckIncludeFiles.cmake b/Modules/CheckIncludeFiles.cmake index 7debbe66fa..98703402e9 100644 --- a/Modules/CheckIncludeFiles.cmake +++ b/Modules/CheckIncludeFiles.cmake @@ -20,24 +20,30 @@ 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: + Checks once whether one or more header files exist and can be included + together in C or C++ code: .. code-block:: cmake check_include_files( [LANGUAGE ]) - 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. + .. rubric:: The arguments are: - 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. + ```` + A :ref:`semicolon-separated list ` of header + files to be checked. + + ```` + The name of the variable to store the result of the check. This + variable will be created as an internal cache variable. + + ``LANGUAGE `` + .. versionadded:: 3.11 + + If set, the specified ```` compiler will be used to perform + the check. Acceptable values are ``C`` and ``CXX``. If this option is + not given, the C compiler will be used if enabled. If the C compiler + is not enabled, the C++ compiler will be used if enabled. .. rubric:: Variables Affecting the Check