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.
• target_compile_definitions()
• target_compile_features()
• target_compile_options()
• target_include_directories()
• target_link_libraries()
• target_link_directories()
• target_link_options()
• target_sources()