mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-12-31 19:00:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Provide guidance on INTERFACE for target_precompile_headers()

Browse Source 
Fixes: #19953
This commit is contained in:
Craig Scott
2019-11-13 23:25:15 +11:00
parent dae9a808fe
commit cc88ede7a3
2 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
Help/command/target_precompile_headers.rst
View File

@@ -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

2
Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst
View File

@@ -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)`