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>). Повторные вызовы для той же <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()