target_precompile_headers

Добавить список файлов заголовков для предварительной компиляции.

Предварительная компиляция файлов заголовков может ускорить компиляцию, создавая частично обработанную версию некоторых файлов заголовков и затем используя эту версию во время компиляции вместо многократного парсинга исходных заголовков.

Основная форма

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 элементы будут заполнять свойство PRECOMPILE_HEADERS цели <target>. Элементы PUBLIC и INTERFACE будут заполнять свойство INTERFACE_PRECOMPILE_HEADERS цели <target> (только для импортированных целей поддерживаются элементы INTERFACE). Повторные вызовы для той же <target> будут добавлять элементы в порядке вызова.

Проекты обычно должны избегать использования 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"]]) будут обрабатываться как есть, а каталоги включения должны быть доступны для компилятора, чтобы он мог их найти. Другие имена файлов заголовков (например, 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>. CMake остановится с ошибкой, если свойство PRECOMPILE_HEADERS для <target> уже установлено при использовании формы REUSE_FROM.

См. также

Чтобы отключить заголовки предварительной компиляции для конкретных целей, см. свойство цели DISABLE_PRECOMPILE_HEADERS.

Чтобы предотвратить использование заголовков предварительной компиляции при компиляции конкретного исходного файла, см. свойство исходного файла SKIP_PRECOMPILE_HEADERS.