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.