1target_precompile_headers 2------------------------- 3 4.. versionadded:: 3.16 5 6Add a list of header files to precompile. 7 8Precompiling header files can speed up compilation by creating a partially 9processed version of some header files, and then using that version during 10compilations rather than repeatedly parsing the original headers. 11 12Main Form 13^^^^^^^^^ 14 15.. code-block:: cmake 16 17 target_precompile_headers(<target> 18 <INTERFACE|PUBLIC|PRIVATE> [header1...] 19 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) 20 21The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or 22:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``. 23The named ``<target>`` must have been created by a command such as 24:command:`add_executable` or :command:`add_library` and must not be an 25:ref:`ALIAS target <Alias Targets>`. 26 27The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to 28specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` 29items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of 30``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the 31:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>`` 32(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). 33Repeated calls for the same ``<target>`` will append items in the order called. 34 35Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets 36that will be :ref:`exported <install(EXPORT)>`, or they should at least use 37the :genex:`$<BUILD_INTERFACE:...>` generator expression to prevent precompile 38headers from appearing in an installed exported target. Consumers of a target 39should typically be in control of what precompile headers they use, not have 40precompile headers forced on them by the targets being consumed (since 41precompile headers are not typically usage requirements). A notable exception 42to this is where an :ref:`interface library <Interface Libraries>` is created 43to define a commonly used set of precompile headers in one place and then other 44targets link to that interface library privately. In this case, the interface 45library exists specifically to propagate the precompile headers to its 46consumers and the consumer is effectively still in control, since it decides 47whether to link to the interface library or not. 48 49The list of header files is used to generate a header file named 50``cmake_pch.h|xx`` which is used to generate the precompiled header file 51(``.pch``, ``.gch``, ``.pchi``) artifact. The ``cmake_pch.h|xx`` header 52file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to 53all source files, so sources do not need to have ``#include "pch.h"``. 54 55Header file names specified with angle brackets (e.g. ``<unordered_map>``) or 56explicit double quotes (escaped for the :manual:`cmake-language(7)`, 57e.g. ``[["other_header.h"]]``) will be treated as is, and include directories 58must be available for the compiler to find them. Other header file names 59(e.g. ``project_header.h``) are interpreted as being relative to the current 60source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be 61included by absolute path. For example: 62 63.. code-block:: cmake 64 65 target_precompile_headers(myTarget 66 PUBLIC 67 project_header.h 68 PRIVATE 69 [["other_header.h"]] 70 <unordered_map> 71 ) 72 73Arguments to ``target_precompile_headers()`` may use "generator expressions" 74with the syntax ``$<...>``. 75See the :manual:`cmake-generator-expressions(7)` manual for available 76expressions. 77The :genex:`$<COMPILE_LANGUAGE:...>` generator expression is particularly 78useful for specifying a language-specific header to precompile for 79only one language (e.g. ``CXX`` and not ``C``). In this case, header 80file names that are not explicitly in double quotes or angle brackets 81must be specified by absolute path. Also, when specifying angle brackets 82inside a generator expression, be sure to encode the closing ``>`` as 83``$<ANGLE-R>``. For example: 84 85.. code-block:: cmake 86 87 target_precompile_headers(mylib PRIVATE 88 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>" 89 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>" 90 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>" 91 ) 92 93 94Reusing Precompile Headers 95^^^^^^^^^^^^^^^^^^^^^^^^^^ 96 97The command also supports a second signature which can be used to specify that 98one target re-uses a precompiled header file artifact from another target 99instead of generating its own: 100 101.. code-block:: cmake 102 103 target_precompile_headers(<target> REUSE_FROM <other_target>) 104 105This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to 106``<other_target>`` and adds a dependency such that ``<target>`` will depend 107on ``<other_target>``. CMake will halt with an error if the 108:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when 109the ``REUSE_FROM`` form is used. 110 111.. note:: 112 113 The ``REUSE_FROM`` form requires the same set of compiler options, 114 compiler flags and compiler definitions for both ``<target>`` and 115 ``<other_target>``. Some compilers (e.g. GCC) may issue a warning if the 116 precompiled header file cannot be used (``-Winvalid-pch``). 117 118See Also 119^^^^^^^^ 120 121To disable precompile headers for specific targets, see the 122:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property. 123 124To prevent precompile headers from being used when compiling a specific 125source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property. 126