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.