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

Precompile headers: Update documentation

parent 57729301
target_precompile_headers
-------------------------
Add a list of header files to precompile.
.. code-block:: cmake
target_precompile_headers(<target>
<INTERFACE|PUBLIC|PRIVATE> [header1...]
[<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
target_precompile_headers(<target>
PUBLIC
"project_header.h"
PRIVATE
<unordered_map>
)
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
:prop_sf:`SKIP_PRECOMPILE_HEADERS`.
......@@ -112,6 +112,7 @@ These commands are available only in CMake projects.
/command/target_link_directories
/command/target_link_libraries
/command/target_link_options
/command/target_precompile_headers
/command/target_sources
/command/try_compile
/command/try_run
......
......@@ -181,6 +181,7 @@ Properties on Targets
/prop_tgt/DEFINE_SYMBOL
/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY
/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES
/prop_tgt/DISABLE_PRECOMPILE_HEADERS
/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION
/prop_tgt/EchoString
/prop_tgt/ENABLE_EXPORTS
......@@ -240,6 +241,7 @@ Properties on Targets
/prop_tgt/INTERFACE_LINK_DIRECTORIES
/prop_tgt/INTERFACE_LINK_LIBRARIES
/prop_tgt/INTERFACE_LINK_OPTIONS
/prop_tgt/INTERFACE_PRECOMPILE_HEADERS
/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE
/prop_tgt/INTERFACE_SOURCES
/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
......@@ -295,6 +297,7 @@ Properties on Targets
/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG
/prop_tgt/PDB_OUTPUT_DIRECTORY
/prop_tgt/POSITION_INDEPENDENT_CODE
/prop_tgt/PRECOMPILE_HEADERS
/prop_tgt/PREFIX
/prop_tgt/PRIVATE_HEADER
/prop_tgt/PROJECT_LABEL
......@@ -445,6 +448,7 @@ Properties on Source Files
/prop_sf/SKIP_AUTOMOC
/prop_sf/SKIP_AUTORCC
/prop_sf/SKIP_AUTOUIC
/prop_sf/SKIP_PRECOMPILE_HEADERS
/prop_sf/Swift_DEPENDENCIES_FILE
/prop_sf/Swift_DIAGNOSTICS_FILE
/prop_sf/SYMBOLIC
......
......@@ -355,6 +355,7 @@ Variables that Control the Build
/variable/CMAKE_CUDA_SEPARABLE_COMPILATION
/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS
/variable/CMAKE_DEBUG_POSTFIX
/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS
/variable/CMAKE_ENABLE_EXPORTS
/variable/CMAKE_EXE_LINKER_FLAGS
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
......
SKIP_PRECOMPILE_HEADERS
-----------------------
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.
DISABLE_PRECOMPILE_HEADERS
--------------------------
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
by :variable:`CMAKE_DISABLE_PRECOMPILE_HEADERS`.
INTERFACE_PRECOMPILE_HEADERS
----------------------------
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.
PRECOMPILE_HEADERS
------------------
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
files.
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
times.
CMAKE_DISABLE_PRECOMPILE_HEADERS
--------------------------------
Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets.
By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``.
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