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