Ninja 多配置

在 3.17 版本中添加。

生成多个 build-<Config>.ninja 文件。

此生成器与 Ninja 生成器非常相似,但存在一些关键差异。本文档将仅讨论这些差异。

Ninja 生成器不同,Ninja Multi-Config 使用 CMAKE_CONFIGURATION_TYPES 一次生成多个配置,而不是仅使用 CMAKE_BUILD_TYPE 生成一个配置。每个配置都会生成一个 build-<Config>.ninja 文件(其中 <Config> 是配置名称)。这些文件旨在通过 ninja -f build-<Config>.ninja 运行。还会生成一个 build.ninja 文件,该文件使用 CMAKE_DEFAULT_BUILD_TYPECMAKE_CONFIGURATION_TYPES 中的第一个项目。

cmake --build . --config <Config> 将始终使用 build-<Config>.ninja 进行构建。如果未指定 --config 参数,则 cmake --build . 将使用 build.ninja

每个 build-<Config>.ninja 文件都包含 <target> 目标以及 <target>:<Config> 目标,其中 <Config>build-<Config>.ninja 中指定的配置相同。此外,如果启用交叉配置模式,build-<Config>.ninja 可能包含 <target>:<OtherConfig> 目标,其中 <OtherConfig> 是交叉配置,以及 <target>:all,后者在所有交叉配置中构建目标。如何启用交叉配置模式请参见下文。

Ninja Multi-Config 生成器识别以下变量

CMAKE_CONFIGURATION_TYPES

指定要构建的配置总集。与其他多配置生成器不同,此变量的默认值为 Debug;Release;RelWithDebInfo

CMAKE_CROSS_CONFIGS

指定一个由 分号分隔的列表,列出所有 build-<Config>.ninja 文件中可用的配置。

CMAKE_DEFAULT_BUILD_TYPE

指定 build.ninja 文件中默认使用的配置。

CMAKE_DEFAULT_CONFIGS

如果未指定 :<Config> 后缀,则指定在 build.ninja 中为目标构建的配置的 分号分隔列表

考虑以下示例

cmake_minimum_required(VERSION 3.16)
project(MultiConfigNinja C)

add_executable(generator generator.c)
add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
add_library(generated ${CMAKE_BINARY_DIR}/generated.c)

现在假设您使用 Ninja Multi-Config 配置项目并运行以下命令之一

ninja -f build-Debug.ninja generated
# OR
cmake --build . --config Debug --target generated

这将构建 generatorDebug 配置,该配置将用于生成 generated.c,而 generated.c 将用于构建 generatedDebug 配置。

但是如果 CMAKE_CROSS_CONFIGS 设置为 all,并且您运行以下命令代替

ninja -f build-Release.ninja generated:Debug
# OR
cmake --build . --config Release --target generated:Debug

这将构建 generatorRelease 配置,该配置将用于生成 generated.c,而 generated.c 将用于构建 generatedDebug 配置。这对于运行生成器实用程序的发布优化版本同时仍构建使用生成的代码构建的目标的调试版本很有用。

自定义命令

在 3.20 版本中添加。

Ninja Multi-Config 生成器通过其交叉配置模式为 add_custom_command()add_custom_target() 添加了额外的功能。COMMANDDEPENDSWORKING_DIRECTORY 参数可以在“命令配置”(使用中的 build-<Config>.ninja 文件的“本机”配置)或“输出配置”(用于评估 OUTPUTBYPRODUCTS 的配置)的上下文中进行评估。

如果 OUTPUTBYPRODUCTS 命名了一个多配置共用的路径(例如,它不使用任何生成器表达式),则所有参数默认在命令配置中进行评估。如果所有 OUTPUTBYPRODUCTS 路径对于每个配置都是唯一的(例如,通过使用 $<CONFIG> 生成器表达式),则 COMMAND 的第一个参数仍默认在命令配置中进行评估,而所有后续参数以及 DEPENDSWORKING_DIRECTORY 的参数则在输出配置中进行评估。这些默认值可以通过 $<OUTPUT_CONFIG:...>$<COMMAND_CONFIG:...> 生成器表达式覆盖。请注意,如果目标在 DEPENDS 中或作为 COMMAND 的第一个参数按名称指定,则即使将其包装在 $<OUTPUT_CONFIG:...> 中,它也始终在命令配置中进行评估(因为其纯名称不是生成器表达式)。

例如,考虑以下内容

add_custom_command(
  OUTPUT "$<CONFIG>.txt"
  COMMAND
    generator "$<CONFIG>.txt"
              "$<OUTPUT_CONFIG:$<CONFIG>>"
              "$<COMMAND_CONFIG:$<CONFIG>>"
  DEPENDS
    tgt1
    "$<TARGET_FILE:tgt2>"
    "$<OUTPUT_CONFIG:$<TARGET_FILE:tgt3>>"
    "$<COMMAND_CONFIG:$<TARGET_FILE:tgt4>>"
  )

假设 generatortgt1tgt2tgt3tgt4 都是可执行目标,并假设 $<CONFIG>.txt 是在 Release 命令配置中使用 Debug 输出配置构建的。generator 目标的 Release 构建将以 Debug.txt Debug Release 作为参数调用。该命令依赖于 tgt1tgt4Release 构建,以及 tgt2tgt3Debug 构建。

目标的 PRE_BUILDPRE_LINKPOST_BUILD 自定义命令只在其“本机”配置(build-Release.ninja 文件中的 Release 配置)中运行,除非它们没有 BYPRODUCTS 或者它们的 BYPRODUCTS 是每个配置唯一的。考虑以下示例

add_executable(exe main.c)
add_custom_command(
  TARGET exe
  POST_BUILD
  COMMAND
    ${CMAKE_COMMAND} -E echo "Running no-byproduct command"
  )
add_custom_command(
  TARGET exe
  POST_BUILD
  COMMAND
    ${CMAKE_COMMAND} -E echo
    "Running separate-byproduct command for $<CONFIG>"
  BYPRODUCTS $<CONFIG>.txt
  )
add_custom_command(
  TARGET exe
  POST_BUILD
  COMMAND
    ${CMAKE_COMMAND} -E echo
    "Running common-byproduct command for $<CONFIG>"
  BYPRODUCTS exe.txt
  )

在此示例中,如果您在 build-Release.ninja 中构建 exe:Debug,则第一个和第二个自定义命令会运行,因为它们的副产品是每个配置唯一的,但最后一个自定义命令不会运行。但是,如果您在 build-Release.ninja 中构建 exe:Release,则所有三个自定义命令都会运行。