Commit 498e3e67 authored by Brad King's avatar Brad King Committed by Kitware Robot

Merge topic 'docs-pch-reorg'

cc88ede7 Help: Provide guidance on INTERFACE for target_precompile_headers()
dae9a808 Help: Reorganise target_precompile_headers() docs for readability
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !4045
parents b60563fe cc88ede7
......@@ -3,33 +3,21 @@ target_precompile_headers
Add a list of header files to precompile.
Precompiling header files can speed up compilation by creating a partially
processed version of some header files, and then using that version during
compilations rather than repeatedly parsing the original headers.
Main Form
^^^^^^^^^
.. code-block:: cmake
target_precompile_headers(<target>
<INTERFACE|PUBLIC|PRIVATE> [header1...]
[<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
target_precompile_headers(<target> REUSE_FROM <other_target>)
Adds header files to :prop_tgt:`PRECOMPILE_HEADERS` or
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties.
The second signature will reuse an already precompiled header file artefact
from another target. This is done by setting the
:prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` to ``<other_target>`` value.
The ``<other_target>`` will become a dependency of ``<target>``.
.. note::
The second signature will require the same set of compiler options,
compiler flags, compiler definitions for both ``<target>``, and
``<other_target>``. Compilers (e.g. GCC) will issue a warning if the
precompiled header file cannot be used (``-Winvalid-pch``).
Precompiling header files can speed up compilation by creating a partially
processed version of some header files, and then using that version during
compilations rather than repeatedly parsing the original headers.
The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``.
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.
......@@ -38,25 +26,50 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``.
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
Repeated calls for the same ``<target>`` append items in the order called.
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``
(: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
file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to
all source files, so sources do not need to have ``#include "pch.h"``.
Header file names specified with angle brackets (e.g. ``<unordered_map>``) or
explicit double quotes (escaped for the :manual:`cmake-language(7)`,
e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
must be available for the compiler to find them. Other header file names
(e.g. ``project_header.h``) are interpreted as being relative to the current
source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
included by absolute path.
Arguments to ``target_precompile_headers`` may use "generator expressions"
Arguments to ``target_precompile_headers()`` may use "generator expressions"
with the syntax ``$<...>``.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-compile-features(7)` manual for
information on compile features and a list of supported compilers.
The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
useful for specifying a language-specific header to precompile for
only one language (e.g. ``CXX`` and not ``C``).
Usage
^^^^^
only one language (e.g. ``CXX`` and not ``C``). For example:
.. code-block:: cmake
target_precompile_headers(<target>
target_precompile_headers(myTarget
PUBLIC
project_header.h
"$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>"
......@@ -65,20 +78,6 @@ Usage
<unordered_map>
)
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
file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to
all source files, so sources do not need to have ``#include "pch.h"``.
Header file names specified with angle brackets (e.g. ``<unordered_map>``) or
explicit double quotes (escaped for the :manual:`cmake-language(7)`,
e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
must be available for the compiler to find them. Other header file names
(e.g. ``project_header.h``) are interpreted as being relative to the current
source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
included by absolute path.
When specifying angle brackets inside a :manual:`generator expression
<cmake-generator-expressions(7)>`, be sure to encode the closing ``>``
as ``$<ANGLE-R>``. For example:
......@@ -88,13 +87,38 @@ as ``$<ANGLE-R>``. For example:
target_precompile_headers(mylib PRIVATE
"$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
"$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
)
)
Reusing Precompile Headers
^^^^^^^^^^^^^^^^^^^^^^^^^^
The command also supports a second signature which can be used to specify that
one target re-uses a precompiled header file artefact from another target
instead of generating its own:
.. code-block:: cmake
target_precompile_headers(<target> REUSE_FROM <other_target>)
This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to
``<other_target>`` and adds a dependency such that ``<target>`` will depend
on ``<other_target>``. CMake will halt with an error if the
:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when
the ``REUSE_FROM`` form is used.
.. note::
The ``REUSE_FROM`` form requires the same set of compiler options,
compiler flags and compiler definitions for both ``<target>`` and
``<other_target>``. Some compilers (e.g. GCC) may issue a warning if the
precompiled header file cannot be used (``-Winvalid-pch``).
See Also
^^^^^^^^
For disabling precompile headers for specific targets there is the
property :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`.
To disable precompile headers for specific targets, see the
:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property.
For skipping certain source files there is the source file property
:prop_sf:`SKIP_PRECOMPILE_HEADERS`.
To prevent precompile headers from being used when compiling a specific
source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property.
......@@ -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)`
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment