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 для целевых объектов, которые будут 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()