From cc88ede7a37f8180f670c0d6036ba40cf005c7b9 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Wed, 13 Nov 2019 23:25:15 +1100 Subject: Help: Provide guidance on INTERFACE for target_precompile_headers() Fixes: #19953 --- Help/command/target_precompile_headers.rst | 14 ++++++++++++++ Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst | 2 ++ 2 files changed, 16 insertions(+) diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index 1be453d..569c7eb 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 ` only support ``INTERFACE`` items). Repeated calls for the same ```` will append items in the order called. +Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets +that will be :ref:`exported `, or they should at least use +the ``$`` 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 ` 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 8ff7e8b..e285407 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)` -- cgit v0.12