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() 等命令建立，且不得為 別名目標。

INTERFACE、PUBLIC 和 PRIVATE 關鍵字是必需的，用來指定後續引數的 範圍。PRIVATE 和 PUBLIC 項目會填入 <target> 的 PRECOMPILE_HEADERS 屬性。PUBLIC 和 INTERFACE 項目會填入 <target> 的 INTERFACE_PRECOMPILE_HEADERS 屬性 (只有 匯入目標 支援 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)。

另請參閱