target_precompile_headers

3.16 版新增。

添加一个头文件列表以进行预编译。

预编译头文件可以通过创建一些头文件的部分处理版本来加快编译速度，然后在编译期间使用该版本，而不是重复解析原始头文件。

主要形式

target_precompile_headers(<target>
  <INTERFACE|PUBLIC|PRIVATE> [header1...]
  [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])

该命令将头文件添加到 <target> 的 PRECOMPILE_HEADERS 和/或 INTERFACE_PRECOMPILE_HEADERS 目标属性中。命名的 <target> 必须由诸如 add_executable() 或 add_library() 的命令创建，并且不能是 ALIAS 目标。

INTERFACE、PUBLIC 和 PRIVATE 关键字是指定后续参数范围所必需的。PRIVATE 和 PUBLIC 项将填充 <target> 的 PRECOMPILE_HEADERS 属性。PUBLIC 和 INTERFACE 项将填充 <target> 的 INTERFACE_PRECOMPILE_HEADERS 属性（IMPORTED 目标仅支持 INTERFACE 项）。对同一 <target> 的重复调用将按调用顺序追加项。

项目通常应避免对将要导出的目标使用 PUBLIC 或 INTERFACE，或者至少应使用 $<BUILD_INTERFACE:...> 生成器表达式来防止预编译头文件出现在已安装的导出目标中。目标的使用者通常应该能够控制他们使用的预编译头文件，而不是被强制使用被消费目标提供的预编译头文件（因为预编译头文件通常不是使用要求）。一个值得注意的例外是创建一个接口库，以在一个地方定义一组常用的预编译头文件，然后其他目标私下链接到该接口库。在这种情况下，接口库的存在专门是为了将其预编译头文件传播给其使用者，并且使用者实际上仍然处于控制之中，因为它可以决定是否链接到该接口库。

头文件列表用于生成一个名为 cmake_pch.h|xx 的头文件，该文件用于生成预编译头文件（.pch、.gch、.pchi）制品。cmake_pch.h|xx 头文件将被强制包含（GCC 为 -include，MSVC 为 /FI）到所有源文件中，因此源文件不需要包含 #include "pch.h"。

用尖括号（例如 <unordered_map>）或显式双引号（为cmake-language(7) 转义，例如 [["other_header.h"]]）指定的头文件名将按原样处理，并且必须有可用的包含目录供编译器查找它们。其他头文件名（例如 project_header.h）被解释为相对于当前源目录（例如 CMAKE_CURRENT_SOURCE_DIR）并以绝对路径包含。例如

target_precompile_headers(myTarget
  PUBLIC
    project_header.h
  PRIVATE
    [["other_header.h"]]
    <unordered_map>
)

target_precompile_headers 的参数可以使用语法 $<...> 的生成器表达式。有关可用表达式，请参阅cmake-generator-expressions(7) 手册。 $<COMPILE_LANGUAGE:...> 生成器表达式对于指定仅用于一种语言（例如 CXX 而不是 C）的特定语言头文件进行预编译特别有用。在这种情况下，未显式用双引号或尖括号指定的头文件名必须指定为绝对路径。此外，在生成器表达式中指定尖括号时，请务必将右尖括号 > 编码为 $<ANGLE-R>。例如

target_precompile_headers(mylib PRIVATE
  "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
  "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
  "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
)

重用预编译头文件

该命令还支持第二种签名，可用于指定一个目标重用另一个目标的预编译头文件制品，而不是生成自己的制品

target_precompile_headers(<target> REUSE_FROM <other_target>)

此形式将 PRECOMPILE_HEADERS_REUSE_FROM 属性设置为 <other_target>，并添加一个依赖项，使 <target> 依赖于 <other_target>。如果在使用 REUSE_FROM 形式时，<target> 的 PRECOMPILE_HEADERS 属性已设置，CMake 将会报错。

注意

REUSE_FROM 形式要求 <target> 和 <other_target> 具有相同的编译器选项、编译器标志和编译器定义集。某些编译器（例如 GCC）如果预编译头文件无法使用，可能会发出警告（-Winvalid-pch）。

另请参阅