diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/target_precompile_headers.rst | 14 | ||||
| -rw-r--r-- | Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst | 2 |
2 files changed, 16 insertions, 0 deletions
diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index 1be453dbbd..569c7eb112 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst @@ -30,6 +30,20 @@ items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of (:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). Repeated calls for the same ``<target>`` will append items in the order called. +Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets +that will be :ref:`exported <install(EXPORT)>`, or they should at least use +the ``$<BUILD_INTERFACE:...>`` generator expression to prevent precompile +headers from appearing in an installed exported target. Consumers of a target +should typically be in control of what precompile headers they use, not have +precompile headers forced on them by the targets being consumed (since +precompile headers are not typically usage requirements). A notable exception +to this is where an :ref:`interface library <Interface Libraries>` is created +to define a commonly used set of precompile headers in one place and then other +targets link to that interface library privately. In this case, the interface +library exists specifically to propagate the precompile headers to its +consumers and the consumer is effectively still in control, since it decides +whether to link to the interface library or not. + The list of header files is used to generate a header file named ``cmake_pch.h|xx`` which is used to generate the precompiled header file (``.pch``, ``.gch``, ``.pchi``) artifact. The ``cmake_pch.h|xx`` header diff --git a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst index 8ff7e8ba1d..e2854074c1 100644 --- a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst +++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst @@ -7,6 +7,8 @@ Targets may populate this property to publish the header files for consuming targets to precompile. The :command:`target_precompile_headers` command populates this property with values given to the ``PUBLIC`` and ``INTERFACE`` keywords. Projects may also get and set the property directly. +See the discussion in :command:`target_precompile_headers` for guidance on +appropriate use of this property for installed or exported targets. Contents of ``INTERFACE_PRECOMPILE_HEADERS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` |