Commit 8da78d4e authored by Cristian Adam's avatar Cristian Adam 💬 Committed by Brad King
Browse files

Precompile headers: Update documentation

parent 57729301
Pipeline #145030 passed with stage
Add a list of header files to precompile.
.. code-block:: cmake
[<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
Adds header files to :prop_tgt:`PRECOMPILE_HEADERS` or
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties.
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 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>`.
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.
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.
.. code-block:: cmake
Header files will be double quoted if they are not specified with double
quotes or angle brackets.
See Also
For disabling precompile headers for specific targets there is the
property :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`.
For skipping certain source files there is the source file property
......@@ -112,6 +112,7 @@ These commands are available only in CMake projects.
......@@ -181,6 +181,7 @@ Properties on Targets
......@@ -240,6 +241,7 @@ Properties on Targets
......@@ -295,6 +297,7 @@ Properties on Targets
......@@ -445,6 +448,7 @@ Properties on Source Files
......@@ -355,6 +355,7 @@ Variables that Control the Build
Is this source file skipped by :prop_tgt:`PRECOMPILE_HEADERS` feature.
This property helps with build problems that one would run into
when using the :prop_tgt:`PRECOMPILE_HEADERS` feature.
One example would be the usage of Objective-C (*.m) files, and
Objective-C++ (*.mm) files, which lead to compilation failure
because they are treated (in case of Ninja / Makefile generator)
as C, and CXX respectively. The precompile headers are not
compatible between languages.
Disables the precompilation of header files specified by
:prop_tgt:`PRECOMPILE_HEADERS` property.
If the property is not set, CMake will use the value provided
List of interface header files to precompile into consuming targets.
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.
Contents of ``INTERFACE_PRECOMPILE_HEADERS`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
List of header files to precompile.
This property holds a :ref:`semicolon-separated list <CMake Language Lists>`
of header files to precompile specified so far for its target.
Use the :command:`target_precompile_headers` command to append more header
This property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Precompile Headers
* The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to tell
generators to use a list of precompile headers for faster compilation
Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets.
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