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>). Повторные вызовы для одной и той же <target> будут добавлять элементы в порядке вызова.

Проекты, как правило, должны избегать использования PUBLIC или INTERFACE для целей, которые будут exported, или, по крайней мере, использовать выражение генератора $<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.
• target_compile_definitions()
• target_compile_features()
• target_compile_options()
• target_include_directories()
• target_link_libraries()
• target_link_directories()
• target_link_options()
• target_sources()