Merge topic 'doc-unity-build'
13c8dbd5a6 Help: Document CMAKE_UNITY_BUILD/CMAKE_EXPORT_COMPILE_COMMANDS limitation
ed06d27c7f Help: Extend documentation of CMAKE_UNITY_BUILD variable
1d9155eb93 Help: Improve UNITY_BUILD documentation formatting
8aac65a361 Help: Document CMAKE_UNITY_BUILD in 3.16 release notes
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !3905
diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst
index beac5d4..2faad92 100644
--- a/Help/prop_tgt/UNITY_BUILD.rst
+++ b/Help/prop_tgt/UNITY_BUILD.rst
@@ -5,27 +5,33 @@
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 @@
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 a14effe..7992f2d 100644
--- a/Help/release/3.16.rst
+++ b/Help/release/3.16.rst
@@ -115,6 +115,10 @@
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 8776279..4548abc 100644
--- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
+++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
@@ -28,3 +28,7 @@
.. 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 3096954..bbcfd68 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.
