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
)