cmake_file_api

3.27 版中新增。

支持与 CMake 文件 API 进行交互。

cmake_file_api(QUERY ...)

QUERY 子命令会为当前的 CMake 调用添加一个 API 文件查询。

cmake_file_api(
  QUERY
  API_VERSION <version>
  [CODEMODEL <versions>...]
  [CACHE <versions>...]
  [CMAKEFILES <versions>...]
  [TOOLCHAINS <versions>...]
)

务必提供 API_VERSION。目前，唯一受支持的 <version> 值为 1。有关回复内容和位置的详情，请参阅 API v1。

每个可选关键字 CODEMODEL、CACHE、CMAKEFILES 和 TOOLCHAINS 均对应一个可以通过项目请求的对象类型。configureLog 对象类型无法通过此命令进行设置，因为它必须在 CMake 开始读取顶层 CMakeLists.txt 文件前设置。

对于每个可选关键字，<versions> 列表必须包含一个或多个版本值，其形式为 major 或 major.minor，其中 major 和 minor 为整数。项目应对其接受的版本按偏好顺序排列，因为列表中仅会选择第一个受支持的值。此命令会忽略 major 版本高于它对此对象类型所支持的任何主版本的版本。如果它遇到无效版本号，或如果请求的版本中没有一个受到支持，它将引发错误。

对于请求的每种对象类型，一个等同于共享无状态查询的查询将在内部被添加。系统中不会创建任何查询文件。该应答将会在生成时写入文件系统。

多次添加相同内容的查询（无论是通过查询文件还是通过多次调用 cmake_file_api(QUERY)）均无错。

示例

一个项目可能想在构建时使用文件 API 的回复来实施某种验证任务。与依赖 CMake 之外的某些内容来创建一个查询文件不同，该项目可以使用 cmake_file_api(QUERY) 请求当前运行所需的的信息。然后，它可以在构建时创建一个自定义命令来运行，因为要求的信息应始终可用。

cmake_file_api(
  QUERY
  API_VERSION 1
  CODEMODEL 2.3
  TOOLCHAINS 1
)

add_custom_target(verify_project
  COMMAND ${CMAKE_COMMAND}
    -D BUILD_DIR=${CMAKE_BINARY_DIR}
    -D CONFIG=$<CONFIG>
    -P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake
)