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 для целевых объектов, которые будут exported, или, по крайней мере, использовать выражение генератора $<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.
• target_compile_definitions()
• target_compile_features()
• target_compile_options()
• target_include_directories()
• target_link_libraries()
• target_link_directories()
• target_link_options()
• target_sources()