CMakePushCheckState

This module provides commands for managing the state of variables that influence how various CMake check commands (e.g., check_symbol_exists(), etc.) are performed.

在 CMake 專案中使用以下命令載入該模組：

include(CMakePushCheckState)

This module provides the following commands, which are useful for scoped configuration, for example, in CMake 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:

Affected Variables

The following CMake variables are saved, reset, and restored by this module's commands:

CMAKE_REQUIRED_FLAGS

一個以空格分隔的字串，包含要傳遞給編譯器的額外旗標。分號分隔列表將無法運作。CMAKE_<LANG>_FLAGS 及其關聯的特定組態 CMAKE_<LANG>_FLAGS_<CONFIG> 變數的內容會在該變數的內容之前自動預置到編譯器命令中。

CMAKE_REQUIRED_DEFINITIONS

一個編譯器定義的分號分隔列表，每個定義的形式為 -DFOO 或 -DFOO=bar。由檢查命令的結果變數引數所指定的名稱的定義也會自動新增。

CMAKE_REQUIRED_INCLUDES

一個要傳遞給編譯器的標頭搜尋路徑的分號分隔列表。這些將是唯一使用的標頭搜尋路徑；INCLUDE_DIRECTORIES 目錄屬性的內容將被忽略。

CMAKE_REQUIRED_LINK_OPTIONS

在 3.14 版被加入.

一個要新增到連結命令的選項的分號分隔列表（詳情請參見 try_compile()）。

CMAKE_REQUIRED_LIBRARIES

一個要新增到連結命令的程式庫的分號分隔列表。這些可以是系統程式庫的名稱，也可以是 Imported Targets`（詳情請參見 :command:`try_compile）。

CMAKE_REQUIRED_LINK_DIRECTORIES

在 3.31 版被加入.

一個要傳遞給連結器的程式庫搜尋路徑的分號分隔列表（詳情請參見 try_compile()）。

CMAKE_REQUIRED_QUIET

在 3.1 版被加入.

如果此變數的值為布林真值，則與檢查相關的所有狀態訊息都將被抑制。

CMAKE_EXTRA_INCLUDE_FILES

在 3.6 版被加入: Previously used already by the check_type_size() command; now also supported by this module.

A semicolon-separated list of extra header files to include when performing the check.

備註

Other CMake variables, such as CMAKE_<LANG>_FLAGS, propagate to all checks regardless of commands provided by this module, as those fundamental variables are designed to influence the global state of the build system.

命令

cmake_push_check_state

Pushes (saves) the current states of the above variables onto a stack:

cmake_push_check_state([RESET])

Use this command to preserve the current configuration before making temporary modifications for specific checks.

RESET

When this option is specified, the command 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()

Use this command 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()

Use this command 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().

範例

Example: Isolated Check With Compile Definitions

In the following example, a check for the C symbol memfd_create() is performed with an additional _GNU_SOURCE compile definition, without affecting global compile flags. The RESET option is used to ensure that any prior values of the check-related variables are explicitly cleared before the check.

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

Example: Nested Configuration Scopes

In the following example, variable states are pushed onto the stack multiple times, allowing for sequential or nested checks. 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()