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> (только IMPORTED цели поддерживают элементы 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.