CMakePushCheckState — CMake 4.0.2-dirty Documentation

# CMakePushCheckState

This module provides macros for managing the state of variables that influence how various CMake check commands (e.g., `check_symbol_exists()`, etc.) are performed. These macros save, reset, and restore the following variables:

- `CMAKE_REQUIRED_FLAGS`

- `CMAKE_REQUIRED_DEFINITIONS`

- `CMAKE_REQUIRED_INCLUDES`

- `CMAKE_REQUIRED_LINK_OPTIONS`

- `CMAKE_REQUIRED_LIBRARIES`

- `CMAKE_REQUIRED_LINK_DIRECTORIES`

- `CMAKE_REQUIRED_QUIET`

- `CMAKE_EXTRA_INCLUDE_FILES`

## Macros

cmake_push_check_state

  Saves (pushes) the current states of the above variables onto a stack. This is typically used to preserve the current configuration before making temporary modifications for specific checks.

      cmake_push_check_state([RESET])

  `RESET`

    When this option is specified, the macro not only saves the current states of the listed variables but also resets them to empty, allowing them to be reconfigured from a clean state.

cmake_reset_check_state

  Resets (clears) the contents of the variables listed above to empty states.

      cmake_reset_check_state()

  This macro can be used, for example, when performing multiple sequential checks that require entirely new configurations, ensuring no previous configuration unintentionally carries over.

cmake_pop_check_state

  Restores the states of the variables listed above to their values at the time of the most recent `cmake_push_check_state()` call.

      cmake_pop_check_state()

  This macro is used to revert temporary changes made during a check. To prevent unexpected behavior, pair each `cmake_push_check_state()` with a corresponding `cmake_pop_check_state()`.

These macros are useful for scoped configuration, for example, in Find modules or when performing checks in a controlled environment, ensuring that temporary modifications are isolated to the scope of the check and do not propagate into other parts of the build system.

Note

Other CMake variables, such as `CMAKE_<LANG>_FLAGS`, propagate to all checks regardless of these macros, as those fundamental variables are designed to influence the global state of the build system.

## Examples

    include(CMakePushCheckState)

    # Save and reset the current state
    cmake_push_check_state(RESET)

    # Perform check with specific compile definitions
    set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE)
    include(CheckSymbolExists)
    check_symbol_exists(memfd_create "sys/mman.h" HAVE_MEMFD_CREATE)

    # Restore the original state
    cmake_pop_check_state()

Variable states can be pushed onto the stack multiple times, allowing for nested or sequential configurations. Each `cmake_pop_check_state()` restores the most recent pushed states.

    include(CMakePushCheckState)

    # Save and reset the current state
    cmake_push_check_state(RESET)

    # Perform the first check with additional libraries
    set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_DL_LIBS})
    include(CheckSymbolExists)
    check_symbol_exists(dlopen "dlfcn.h" HAVE_DLOPEN)

    # Save current state
    cmake_push_check_state()

    # Perform the second check with libraries and additional compile definitions
    set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE)
    check_symbol_exists(dladdr "dlfcn.h" HAVE_DLADDR)

    message(STATUS "${CMAKE_REQUIRED_DEFINITIONS}")
    # Output: -D_GNU_SOURCE

    # Restore the previous state
    cmake_pop_check_state()

    message(STATUS "${CMAKE_REQUIRED_DEFINITIONS}")
    # Output here is empty

    # Reset variables to prepare for the next check
    cmake_reset_check_state()

    # Perform the next check only with additional compile definitions
    set(CMAKE_REQUIRED_DEFINITIONS -D_GNU_SOURCE)
    check_symbol_exists(dl_iterate_phdr "link.h" HAVE_DL_ITERATE_PHDR)

    # Restore the original state
    cmake_pop_check_state()