Merge branch 'doc-unity-build' into release-3.16

Merge-request: !3905

4 files changed, 37 insertions, 17 deletions

diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst
index beac5d4ae5..2faad92246 100644
--- a/Help/prop_tgt/UNITY_BUILD.rst
+++ b/Help/prop_tgt/UNITY_BUILD.rst
@@ -5,27 +5,33 @@ Should the target source files be processed into batches for
 faster compilation. This feature is known as "Unity build",
 or "Jumbo build".
 
-The `C` and `CXX` source files are grouped separately.
+The ``C`` and ``CXX`` source files are grouped separately.
 
 This property is initialized by the value of the
 :variable:`CMAKE_UNITY_BUILD` variable if it is set when
 a target is created.
 
-.. note ::
+.. note::
 
-   It's not recommended to directly set :prop_tgt:`UNITY_BUILD`
-   to `ON`, but to instead set :variable:`CMAKE_UNITY_BUILD` from
-   the command line. However, it IS recommended to set
-   :prop_tgt:`UNITY_BUILD` to `OFF` if you need to ensure that a
-   target doesn't get a unity build.
+  It's not recommended to directly set :prop_tgt:`UNITY_BUILD`
+  to ``ON``, but to instead set :variable:`CMAKE_UNITY_BUILD` from
+  the command line.  However, it IS recommended to set
+  :prop_tgt:`UNITY_BUILD` to ``OFF`` if you need to ensure that a
+  target doesn't get a unity build.
 
 The batch size can be specified by setting
 :prop_tgt:`UNITY_BUILD_BATCH_SIZE`.
 
 The batching of source files is done by adding new sources files
-wich will `#include` the source files, and exclude them from
-building by setting :prop_sf:`HEADER_FILE_ONLY` to `ON`.
+which will ``#include`` the source files, and exclude them from
+building by setting :prop_sf:`HEADER_FILE_ONLY` to ``ON``.
 
+.. note::
+
+  Marking the original sources with :prop_sf:`HEADER_FILE_ONLY`
+  is considered an implementation detail that may change in the
+  future because it does not work well in combination with
+  the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable.
 
 ODR (One definition rule) errors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -45,11 +51,11 @@ The source files that have :prop_sf:`COMPILE_OPTIONS`,
 With the :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and
 :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` one can specify code
 to be injected in the unity source file before and after every
-`#include` statement.
+``#include`` statement.
 
-.. note ::
+.. note::
 
-   The order of source files defined in the `CMakeLists.txt` will
-   be preserved into the generated unity source files. This can
-   be used to manually enforce a specific grouping based on the
-   :prop_tgt:`UNITY_BUILD_BATCH_SIZE`.
+  The order of source files defined in the ``CMakeLists.txt`` will
+  be preserved into the generated unity source files. This can
+  be used to manually enforce a specific grouping based on the
+  :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property.
diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst
index a14effe1c0..7992f2dbcf 100644
--- a/Help/release/3.16.rst
+++ b/Help/release/3.16.rst
@@ -115,6 +115,10 @@ Variables
   specify the resource encoding for the the :generator:`Eclipse CDT4` extra
   generator.
 
+* The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the
+  :prop_tgt:`UNITY_BUILD` target property to tell generators to batch
+  include source files for faster compilation times.
+
 Properties
 ----------
 
diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
index 8776279e8b..4548abcc73 100644
--- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
+++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
@@ -28,3 +28,7 @@ form.  The format of the JSON file looks like:
 .. note::
   This option is implemented only by :ref:`Makefile Generators`
   and the :generator:`Ninja`.  It is ignored on other generators.
+
+  This option currently does not work well in combination with
+  the :prop_tgt:`UNITY_BUILD` target property or the
+  :variable:`CMAKE_UNITY_BUILD` variable.
diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst
index 3096954c20..bbcfd68972 100644
--- a/Help/variable/CMAKE_UNITY_BUILD.rst
+++ b/Help/variable/CMAKE_UNITY_BUILD.rst
@@ -1,6 +1,12 @@
 CMAKE_UNITY_BUILD
 -----------------
 
-Default value for :prop_tgt:`UNITY_BUILD` of targets.
+Initializes the :prop_tgt:`UNITY_BUILD` target property on targets
+as they are created.  Set to ``ON`` to batch compilation of multiple
+sources within each target.  This feature is known as "Unity build",
+or "Jumbo build".  By default this variable is not set and so does
+not enable unity builds on targets.
 
-By default ``CMAKE_UNITY_BUILD`` is ``OFF``.
+.. note::
+  This option currently does not work well in combination with
+  the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable.