Help: Provide guidance on INTERFACE for target_precompile_headers()

Fixes: #19953

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