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 для целевых объектов, которые будут экспортированы, или они должны хотя бы использовать выражение генератора $<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.