CheckIncludeFile — CMake 4.1.4 Documentation

# 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 can be included in C code:

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

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

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

## See Also

- The `CheckIncludeFileCXX` module to check for single C++ header.

- The `CheckIncludeFiles` module to check for one or more C or C++ headers at once.