Merge topic 'unity-build'

7786a05c70 Unity build: Add XCode support
1353802af3 Unity build: Add unit tests
8dfeb5d278 Unity build: Add support for Visual Studio generator
7114c141e2 Unity build: Add support for Ninja and Makefile generators

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Stanislav Ershov <digital.stream.of.mind@gmail.com>
Acked-by: Evgeniy Dushistov <dushistov@mail.ru>
Acked-by: Viktor Kirilov <vik.kirilov@gmail.com>
Merge-request: !3611

10 files changed, 116 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 25d6b247da..19afb7d57d 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -323,6 +323,10 @@ Properties on Targets
    /prop_tgt/Swift_MODULE_DIRECTORY
    /prop_tgt/Swift_MODULE_NAME
    /prop_tgt/TYPE
+   /prop_tgt/UNITY_BUILD
+   /prop_tgt/UNITY_BUILD_BATCH_SIZE
+   /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE
+   /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE
    /prop_tgt/VERSION
    /prop_tgt/VISIBILITY_INLINES_HIDDEN
    /prop_tgt/VS_CONFIGURATION_TYPE
@@ -450,6 +454,7 @@ Properties on Source Files
    /prop_sf/SKIP_AUTORCC
    /prop_sf/SKIP_AUTOUIC
    /prop_sf/SKIP_PRECOMPILE_HEADERS
+   /prop_sf/SKIP_UNITY_BUILD_INCLUSION
    /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 08e2de44a6..2d473d8f5d 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -432,6 +432,8 @@ Variables that Control the Build
    /variable/CMAKE_TRY_COMPILE_CONFIGURATION
    /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
    /variable/CMAKE_TRY_COMPILE_TARGET_TYPE
+   /variable/CMAKE_UNITY_BUILD
+   /variable/CMAKE_UNITY_BUILD_BATCH_SIZE
    /variable/CMAKE_USE_RELATIVE_PATHS
    /variable/CMAKE_VISIBILITY_INLINES_HIDDEN
    /variable/CMAKE_VS_GLOBALS
diff --git a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst
new file mode 100644
index 0000000000..53f3970256
--- /dev/null
+++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst
@@ -0,0 +1,7 @@
+SKIP_UNITY_BUILD_INCLUSION
+--------------------------
+
+Is this source file skipped by :prop_tgt:`UNITY_BUILD` feature.
+
+This property helps with "ODR (One definition rule)" problems
+that one would run into when using an :prop_tgt:`UNITY_BUILD`.
diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst
new file mode 100644
index 0000000000..d326ee2466
--- /dev/null
+++ b/Help/prop_tgt/UNITY_BUILD.rst
@@ -0,0 +1,55 @@
+UNITY_BUILD
+-----------
+
+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.
+
+This property is initialized by the value of the
+:variable:`CMAKE_UNITY_BUILD` variable if it is set when
+a target is created.
+
+.. 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.
+
+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`.
+
+
+ODR (One definition rule) errors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since multiple source files are included into one source file,
+it can lead to ODR errors. This section contains properites
+which help fixing these errors.
+
+The source files marked by :prop_sf:`GENERATED` will be skipped
+from unity build. This applies also for the source files marked
+with :prop_sf:`SKIP_UNITY_BUILD_INCLUSION`.
+
+The source files that have :prop_sf:`COMPILE_OPTIONS`,
+:prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or
+:prop_sf:`INCLUDE_DIRECTORIES` will also be skipped.
+
+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.
+
+.. 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`.
diff --git a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst
new file mode 100644
index 0000000000..24266894b9
--- /dev/null
+++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst
@@ -0,0 +1,13 @@
+UNITY_BUILD_BATCH_SIZE
+----------------------
+
+Specifies how many source code files will be included into a
+:prop_tgt:`UNITY_BUILD` source file.
+
+If the property is not set, CMake will use the value provided
+by :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE`.
+
+By setting it to value `0` the generated unity source file will
+contain all the source files that would be otherwise be split
+into multiple batches. It is not recommended to do so, since it
+would affect performance.
diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst
new file mode 100644
index 0000000000..779528902f
--- /dev/null
+++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst
@@ -0,0 +1,8 @@
+UNITY_BUILD_CODE_AFTER_INCLUDE
+------------------------------
+
+Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD`
+feature just after the `#include` statement of the targeted source
+files.
+
+This could be something like `#undef NOMINMAX`.
diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst
new file mode 100644
index 0000000000..f33546328a
--- /dev/null
+++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst
@@ -0,0 +1,8 @@
+UNITY_BUILD_CODE_BEFORE_INCLUDE
+-------------------------------
+
+Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD`
+feature just before the `#include` statement of the targeted source
+files.
+
+This could be something like `#define NOMINMAX`.
diff --git a/Help/release/dev/unity-build.rst b/Help/release/dev/unity-build.rst
new file mode 100644
index 0000000000..293a3754d2
--- /dev/null
+++ b/Help/release/dev/unity-build.rst
@@ -0,0 +1,6 @@
+Unity build
+-----------
+
+* The :prop_tgt:`UNITY_BUILD` target property was added to tell
+  generators to batch include source files for faster compilation
+  times.
diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst
new file mode 100644
index 0000000000..3096954c20
--- /dev/null
+++ b/Help/variable/CMAKE_UNITY_BUILD.rst
@@ -0,0 +1,6 @@
+CMAKE_UNITY_BUILD
+-----------------
+
+Default value for :prop_tgt:`UNITY_BUILD` of targets.
+
+By default ``CMAKE_UNITY_BUILD`` is ``OFF``.
diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst
new file mode 100644
index 0000000000..3ab2344caa
--- /dev/null
+++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst
@@ -0,0 +1,6 @@
+CMAKE_UNITY_BUILD_BATCH_SIZE
+----------------------------
+
+Default value for :prop_tgt:`UNITY_BUILD_BATCH_SIZE` of targets.
+
+By default ``CMAKE_UNITY_BUILD_BATCH_SIZE`` is set to ``8``.