target_precompile_headers

Добавляет список файлов заголовков для предварительной компиляции.

Предварительная компиляция файлов заголовков может ускорить компиляцию: для некоторых файлов заголовков создаётся частично обработанная версия, которая затем используется при компиляции вместо повторного разбора исходных заголовков.

Основная форма

target_precompile_headers(<target>
  {INTERFACE|PUBLIC|PRIVATE} <header>...
  [{INTERFACE|PUBLIC|PRIVATE} <header>...]...)

Команда добавляет файлы заголовков в свойства цели 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> элементы добавляются в порядке вызова.

Как правило, проектам следует избегать использования 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()