Precompile headers: Update documentation

10 files changed, 121 insertions, 0 deletions

diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst
new file mode 100644
index 0000000..3e28265
--- /dev/null
+++ b/Help/command/target_precompile_headers.rst
@@ -0,0 +1,56 @@
+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`.
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index a3bc465..59ba897 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -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
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 62d23c7..03f18fc 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -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
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 9ad1195..668b2a2 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -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
diff --git a/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst
new file mode 100644
index 0000000..5f39f30
--- /dev/null
+++ b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst
@@ -0,0 +1,13 @@
+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.
diff --git a/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst
new file mode 100644
index 0000000..4cef023
--- /dev/null
+++ b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst
@@ -0,0 +1,8 @@
+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`.
diff --git a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst
new file mode 100644
index 0000000..8ff7e8b
--- /dev/null
+++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst
@@ -0,0 +1,14 @@
+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.
diff --git a/Help/prop_tgt/PRECOMPILE_HEADERS.rst b/Help/prop_tgt/PRECOMPILE_HEADERS.rst
new file mode 100644
index 0000000..9e70b65
--- /dev/null
+++ b/Help/prop_tgt/PRECOMPILE_HEADERS.rst
@@ -0,0 +1,12 @@
+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)>`.
diff --git a/Help/release/dev/precompile-headers.rst b/Help/release/dev/precompile-headers.rst
new file mode 100644
index 0000000..8b62da7
--- /dev/null
+++ b/Help/release/dev/precompile-headers.rst
@@ -0,0 +1,6 @@
+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.
diff --git a/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst
new file mode 100644
index 0000000..7c30ede
--- /dev/null
+++ b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst
@@ -0,0 +1,6 @@
+CMAKE_DISABLE_PRECOMPILE_HEADERS
+--------------------------------
+
+Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets.
+
+By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``.