target_precompile_headers

在版本 3.16 中新增。

新增要預編譯的標頭檔列表。

預編譯標頭檔可以透過建立某些標頭檔的部分處理版本來加速編譯，然後在編譯期間使用該版本，而不是重複解析原始標頭。

主要形式

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

此命令將標頭檔新增到 PRECOMPILE_HEADERS 和/或 INTERFACE_PRECOMPILE_HEADERS 目標屬性 <target>。指定的 <target> 必須已由命令（例如 add_executable() 或 add_library()）建立，且不得為 ALIAS 目標。

INTERFACE、PUBLIC 和 PRIVATE 關鍵字是指定後續引數的 範圍 所必需的。PRIVATE 和 PUBLIC 項目將填充 <target> 的 PRECOMPILE_HEADERS 屬性。PUBLIC 和 INTERFACE 項目將填充 <target> 的 INTERFACE_PRECOMPILE_HEADERS 屬性（IMPORTED 目標 僅支援 INTERFACE 項目）。對同一個 <target> 重複呼叫將按照呼叫順序附加項目。

專案通常應避免對將被 exported 的目標使用 PUBLIC 或 INTERFACE，或者他們至少應使用 $<BUILD_INTERFACE:...> 產生器表達式，以防止預編譯標頭出現在已安裝的匯出目標中。目標的使用者通常應控制他們使用的預編譯標頭，而不是讓消耗的目標強制他們使用預編譯標頭（因為預編譯標頭通常不是使用需求）。一個值得注意的例外是，當建立 介面函式庫 以在一個位置定義一組常用的預編譯標頭，然後其他目標私下連結到該介面函式庫時。在這種情況下，介面函式庫的存在是專門為了將預編譯標頭傳播給其使用者，而使用者實際上仍然處於控制之中，因為它決定是否連結到介面函式庫。

標頭檔列表用於產生名為 cmake_pch.h|xx 的標頭檔，該標頭檔用於產生預編譯標頭檔 (.pch、.gch、.pchi) 成品。cmake_pch.h|xx 標頭檔將被強制包含 (-include 用於 GCC，/FI 用於 MSVC) 到所有原始檔，因此原始檔不需要有 #include "pch.h"。

以角括號（例如 <unordered_map>）或明確雙引號（針對 cmake-language(7) 進行轉義，例如 [["other_header.h"]]）指定的標頭檔名將按原樣處理，並且 include 目錄必須可用於編譯器才能找到它們。其他標頭檔名（例如 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> 具有相同的編譯器選項、編譯器標誌和編譯器定義。如果無法使用預編譯標頭檔 (-Winvalid-pch)，某些編譯器（例如 GCC）可能會發出警告。

參見