CheckIncludeFile

This module provides a command to check C header file.

Load this module in a CMake project with:

include(CheckIncludeFile)

Commands

This module provides the following command:

check_include_file

Checks once whether a header file exists and can be included in C code:

check_include_file(<include> <variable> [<flags>])

The arguments are:

<include>: A header file to be checked.
<variable>: The name of the variable to store the result of the check. This variable will be created as an internal cache variable.
<flags>: (Optional) A space-separated string of additional compilation flags to be added to the check. Alternatively, flags can be also specified with the CMAKE_REQUIRED_FLAGS variable below.

Variables Affecting the Check

The following variables may be set before calling this command to modify the way the check is run:

CMAKE_REQUIRED_FLAGS: A space-separated string of additional flags to pass to the compiler. A semicolon-separated list will not work. The contents of CMAKE_<LANG>_FLAGS and its associated configuration-specific CMAKE_<LANG>_FLAGS_<CONFIG> variables are automatically prepended to the compiler command before the contents of this variable.

CMAKE_REQUIRED_DEFINITIONS: A semicolon-separated list of compiler definitions, each of the form -DFOO or -DFOO=bar. A definition for the name specified by the result variable argument of the check command is also added automatically.

CMAKE_REQUIRED_INCLUDES: A semicolon-separated list of header search paths to pass to the compiler. These will be the only header search paths used; the contents of the INCLUDE_DIRECTORIES directory property will be ignored.

CMAKE_REQUIRED_LINK_OPTIONS: Added in version 3.14.

A semicolon-separated list of options to add to the link command (see try_compile() for further details).

CMAKE_REQUIRED_LIBRARIES: A semicolon-separated list of libraries to add to the link command. These can be the names of system libraries, or they can be Imported Targets (see try_compile() for further details).

CMAKE_REQUIRED_LINK_DIRECTORIES: Added in version 3.31.

A semicolon-separated list of library search paths to pass to the linker (see try_compile() for further details).

CMAKE_REQUIRED_QUIET: Added in version 3.1.

If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed.

Added in version 3.12: The CMAKE_REQUIRED_LIBRARIES variable, if policy CMP0075 is set to NEW.

Examples

Example: Checking C Header

Checking whether the C header <unistd.h> exists and storing the check result in the HAVE_UNISTD_H cache variable:

include(CheckIncludeFile)

check_include_file(unistd.h HAVE_UNISTD_H)

Example: Isolated Check

In the following example, this module is used in combination with the 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).

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_file(ucontext.h HAVE_UCONTEXT_H)
cmake_pop_check_state()