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

@@ -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()`` command in the :module:`CheckIncludeFile` module, the
-* ``check_include_file_cxx`` macro in 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
+in the include file check commands.  The ``NEW`` behavior of this policy is to
-honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check macros.
+honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check commands.
 
 .. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.12
 .. |WARNS_OR_DOES_NOT_WARN| replace:: warns

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,
+* The :module:`CheckIncludeFile` module ``check_include_file()`` command,
-  :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro,
+  :module:`CheckIncludeFileCXX` module ``check_include_file_cxx()`` command,
-  and :module:`CheckIncludeFiles` module ``check_include_files`` macro
+  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

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

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(<include> <variable> [<flags>])
 
-  Check if the given ``<include>`` file may be included in a ``C``
+  This command checks once whether the given ``<include>`` header file
-  source file and store the result in an internal cache entry named
+  exists and can be included in a C source file.  The result of the check
-  ``<variable>``.  The optional third argument may be used to add
+  is stored in an internal cache variable named ``<variable>``.  The
-  compilation flags to the check (or use ``CMAKE_REQUIRED_FLAGS`` below).
+  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
+  .. rubric:: Variables Affecting the Check
-the way the check is run:
+
+  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:`CheckIncludeFileCXX` module to check for single C++ header.
-* The :module:`CheckIncludeFiles` module to check for one or more ``C`` or
+* The :module:`CheckIncludeFiles` module to check for one or more C or
-  ``C++`` headers at once.
+  C++ headers at once.
 #]=======================================================================]
 
 include_guard(GLOBAL)

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(<include> <variable> [<flags>])
 
-  Check if the given ``<include>`` file may be included in a ``CXX``
+  This command checks once whether the given ``<include>`` header file
-  source file and store the result in an internal cache entry named
+  exists and can be included in a ``CXX`` source file.  The result of the
-  ``<variable>``.  The optional third argument may be used to add
+  check is stored in an internal cache variable named ``<variable>``.  The
-  compilation flags to the check (or use ``CMAKE_REQUIRED_FLAGS`` below).
+  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
+  .. rubric:: Variables Affecting the Check
-the way the check is run:
+
+  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:`CheckIncludeFile` module to check for single C header.
-* The :module:`CheckIncludeFiles` module to check for one or more ``C`` or
+* The :module:`CheckIncludeFiles` module to check for one or more C or
-  ``C++`` headers at once.
+  C++ headers at once.
 #]=======================================================================]
 
 include_guard(GLOBAL)

Modules/CheckIncludeFiles.cmake

@@ -5,27 +5,44 @@
 CheckIncludeFiles
 -----------------
 
-Provides a macro to check if a list of one or more header files can
+This module provides a command to check one or more C/C++ header files.
-be included together.
+
+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
+  This command checks once whether the given ``<includes>`` list of header
-  in a source file and store the result in an internal cache
+  files exist and can be included together in a C or C++ source file.  The
-  entry named ``<variable>``.  Specify the ``<includes>`` argument
+  result of the check is stored in an internal cache variable named
-  as a :ref:`;-list <CMake Language Lists>` of header file names.
+  ``<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
+  check.  Acceptable values are ``C`` and ``CXX``.  If not set, the C
-  will be used if enabled. If the C compiler is not enabled, the C++
+  compiler will be used if enabled.  If the C compiler is not enabled, the
-  compiler will be used if enabled.
+  C++ compiler will be used if enabled.
 
-The following variables may be set before calling this macro to modify
+  .. rubric:: Variables Affecting the Check
-the way the check is run:
+
+  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
+Checking one or more C headers and storing the check result in cache
-in cache variables:
+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:`CheckIncludeFile` module to check for a single C header.
-* The :module:`CheckIncludeFileCXX` module to check for single ``C++`` header.
+* The :module:`CheckIncludeFileCXX` module to check for a single C++ header.
 #]=======================================================================]
 
 include_guard(GLOBAL)