Unity Builds: Support explicit specification of sources to groups

Instead of having CMake determine which files should go into each
unity file, the user can now use explicitly state the mapping.

1 files changed, 22 insertions, 0 deletions

diff --git a/Help/prop_tgt/UNITY_BUILD_MODE.rst b/Help/prop_tgt/UNITY_BUILD_MODE.rst
new file mode 100644
index 0000000..cbc4989
--- /dev/null
+++ b/Help/prop_tgt/UNITY_BUILD_MODE.rst
@@ -0,0 +1,22 @@
+UNITY_BUILD_MODE
+----------------
+
+CMake provides different algorithms for selecting which sources are grouped
+together into a *bucket*. Selection is decided by this property,
+which has the following acceptable values:
+
+* ``BATCH``
+  When in this mode CMake determines which files are grouped together.
+  The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper limit on
+  how many sources can be combined per unity source file.
+
+* ``GROUP``
+  When in this mode each target explicitly specifies how to group
+  source files. Each source file that has the same
+  :prop_sf:`UNITY_GROUP` value will be grouped together. Any sources
+  that don't have this property will be compiled individually. The
+  :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property is ignored when using
+  this mode.
+
+If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will
+default to ``BATCH``.