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(), и не должна быть целью ALIAS.

Ключевые слова 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.