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

可选关键字 CODEMODELCACHECMAKEFILESTOOLCHAINS 中的每一个都对应于项目可以请求的对象类型之一。configureLog 对象类型不能通过此命令设置,因为它必须在 CMake 开始读取顶层 CMakeLists.txt 文件之前设置。

对于每个可选关键字,<versions> 列表必须包含一个或多个形式为 majormajor.minor 的版本值,其中 majorminor 是整数。项目应按其首选顺序列出它们接受的版本,因为只会选择列表中第一个受支持的值。该命令将忽略主版本高于其支持的任何主版本(针对该对象类型)的版本。如果遇到无效的版本号,或者请求的版本中没有一个受支持,它将引发错误。

对于每种请求的对象类型,内部将添加一个等同于共享、无状态查询的查询。文件系统中不会创建查询文件。回复在生成时写入文件系统。

多次添加相同内容的查询,无论是从查询文件还是从多次调用 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
)