mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-11 08:20:18 -06:00
Code Issues Packages Projects Releases Wiki Activity

CheckIncludeFile*: Sync documentation

Browse Source 
- 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.
This commit is contained in:
Peter Kokot
2025-05-26 03:12:53 +02:00
parent cfcff29087
commit b2e7736d81
6 changed files with 140 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
Help/policy/CMP0075.rst
View File

@@ -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

6
Help/release/3.11.rst
View File

@@ -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

6
Help/release/3.12.rst
View File

@@ -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`.

73
Modules/CheckIncludeFile.cmake
View File

@@ -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(<include> <variable> [<flags>])
Check if the given ``<include>`` file may be included in a ``C``
source file and store the result in an internal cache entry named
``<variable>``. 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 ``<include>`` 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 ``<variable>``. 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 ``<unistd.h>`` exists and storing the check
Example: Checking C Header
""""""""""""""""""""""""""
Checking whether the C header ``<unistd.h>`` 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)

40
Modules/CheckIncludeFileCXX.cmake
View File

@@ -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(<include> <variable> [<flags>])
Check if the given ``<include>`` file may be included in a ``CXX``
source file and store the result in an internal cache entry named
``<variable>``. 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 ``<include>`` 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 ``<variable>``. 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)

53
Modules/CheckIncludeFiles.cmake
View File

@@ -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("<includes>" <variable> [LANGUAGE <language>])
check_include_files(<includes> <variable> [LANGUAGE <language>])
Check if the given ``<includes>`` list may be included together
in a source file and store the result in an internal cache
entry named ``<variable>``. Specify the ``<includes>`` argument
as a :ref:`;-list <CMake Language Lists>` of header file names.
This command checks once whether the given ``<includes>`` 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
``<variable>``. Specify the ``<includes>`` argument as a
:ref:`semicolon-separated list <CMake Language Lists>` 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)