Help/command/target_precompile_headers.rst

   1 target_precompile_headers
   2 -------------------------
   3
   4 .. versionadded:: 3.16
   5
   6 Add a list of header files to precompile.
   7
   8 Precompiling header files can speed up compilation by creating a partially
   9 processed version of some header files, and then using that version during
  10 compilations rather than repeatedly parsing the original headers.
  11
  12 Main Form
  13 ^^^^^^^^^
  14
  15 .. code-block:: cmake
  16
  17   target_precompile_headers(<target>
  18     <INTERFACE|PUBLIC|PRIVATE> [header1...]
  19     [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
  20
  21 The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or
  22 :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``.
  23 The 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
  27 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
  28 specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
  29 ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS`
  30 property of ``<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).
  33 Repeated calls for the same ``<target>`` will append items in the order called.
  34
  35 Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets
  36 that will be :ref:`exported <install(EXPORT)>`, or they should at least use
  37 the :genex:`$<BUILD_INTERFACE:...>` generator expression to prevent precompile
  38 headers from appearing in an installed exported target.  Consumers of a target
  39 should typically be in control of what precompile headers they use, not have
  40 precompile headers forced on them by the targets being consumed (since
  41 precompile headers are not typically usage requirements).  A notable exception
  42 to this is where an :ref:`interface library <Interface Libraries>` is created
  43 to define a commonly used set of precompile headers in one place and then other
  44 targets link to that interface library privately.  In this case, the interface
  45 library exists specifically to propagate the precompile headers to its
  46 consumers and the consumer is effectively still in control, since it decides
  47 whether to link to the interface library or not.
  48
  49 The 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
  52 file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to
  53 all source files, so sources do not need to have ``#include "pch.h"``.
  54
  55 Header file names specified with angle brackets (e.g. ``<unordered_map>``) or
  56 explicit double quotes (escaped for the :manual:`cmake-language(7)`,
  57 e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
  58 must 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
  60 source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
  61 included 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
  73 Arguments to ``target_precompile_headers()`` may use "generator expressions"
  74 with the syntax ``$<...>``.
  75 See the :manual:`cmake-generator-expressions(7)` manual for available
  76 expressions.
  77 The :genex:`$<COMPILE_LANGUAGE:...>` generator expression is particularly
  78 useful for specifying a language-specific header to precompile for
  79 only one language (e.g. ``CXX`` and not ``C``).  In this case, header
  80 file names that are not explicitly in double quotes or angle brackets
  81 must be specified by absolute path.  Also, when specifying angle brackets
  82 inside 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
  94 Reusing Precompile Headers
  95 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  96
  97 The command also supports a second signature which can be used to specify that
  98 one target re-uses a precompiled header file artifact from another target
  99 instead of generating its own:
 100
 101 .. code-block:: cmake
 102
 103   target_precompile_headers(<target> REUSE_FROM <other_target>)
 104
 105 This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to
 106 ``<other_target>`` and adds a dependency such that ``<target>`` will depend
 107 on ``<other_target>``.  CMake will halt with an error if the
 108 :prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when
 109 the ``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
 118 See Also
 119 ^^^^^^^^
 120
 121 To disable precompile headers for specific targets, see the
 122 :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property.
 123
 124 To prevent precompile headers from being used when compiling a specific
 125 source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property.