Merge topic 'add_unity_mode_examples'

caf5d3f71b Help: Add an example for each UNITY_BUILD_MODE setting

Acked-by: Kitware Robot <[email protected]>
Merge-request: !4733

Help/prop_tgt/UNITY_BUILD_MODE.rst

@@ -5,12 +5,27 @@ 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``
+``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``
+  Example usage:
+
+  .. code-block:: cmake
+
+    add_library(example_library
+                source1.cxx
+                source2.cxx
+                source3.cxx
+                source4.cxx)
+
+    set_target_properties(example_library PROPERTIES
+                          UNITY_BUILD_MODE BATCH
+                          UNITY_BUILD_BATCH_SIZE 2
+                          )
+
+``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
@@ -18,5 +33,26 @@ which has the following acceptable values:
   :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property is ignored when using
   this mode.
 
+  Example usage:
+
+  .. code-block:: cmake
+
+    add_library(example_library
+                source1.cxx
+                source2.cxx
+                source3.cxx
+                source4.cxx)
+
+    set_target_properties(example_library PROPERTIES
+                          UNITY_BUILD_MODE GROUP
+                          )
+
+    set_source_files_properties(source1.cxx source2.cxx source3.cxx
+                                PROPERTIES UNITY_GROUP "bucket1"
+                                )
+    set_source_files_properties(source4.cxx
+                                PROPERTIES UNITY_GROUP "bucket2"
+                                )
+
 If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will
 default to ``BATCH``.