Merge topic 'unity-relative-paths' into release-4.0

f706d8064b Help: Clarify wording of UNITY_BUILD_RELOCATABLE path alternatives
20412690fb Help: Add 4.0 release note for UNITY_BUILD_RELOCATABLE
89cea1c642 Help: Document CMAKE_UNITY_BUILD_RELOCATABLE variable

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

Help/manual/cmake-variables.7.rst

@@ -563,6 +563,7 @@ Variables that Control the Build
    /variable/CMAKE_TRY_COMPILE_TARGET_TYPE
    /variable/CMAKE_UNITY_BUILD
    /variable/CMAKE_UNITY_BUILD_BATCH_SIZE
+   /variable/CMAKE_UNITY_BUILD_RELOCATABLE
    /variable/CMAKE_UNITY_BUILD_UNIQUE_ID
    /variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS
    /variable/CMAKE_VISIBILITY_INLINES_HIDDEN

Help/prop_tgt/UNITY_BUILD_RELOCATABLE.rst

@@ -12,16 +12,15 @@ When this property is set to true, the ``#include`` lines inside the generated
 unity source files will attempt to use relative paths to the original source
 files if possible in order to standardize the output of the unity file.
 
-The unity file's path to the original source file will use the following
-priority:
+The unity file's path to an original source file uses the following priority:
 
-* relative path to the generated unity file if the source file exists
-  directly or in subfolder under the :variable:`CMAKE_BINARY_DIR`
+* a path relative to the generated unity file if the source file exists
+  directly in :variable:`CMAKE_BINARY_DIR`, or in a subfolder under it.
 
-* relative path to :variable:`CMAKE_SOURCE_DIR` if the source file exists
-  directly or in subfolder under the :variable:`CMAKE_SOURCE_DIR`
+* a path relative to :variable:`CMAKE_SOURCE_DIR` if the source file exists
+  directly in :variable:`CMAKE_SOURCE_DIR`, or in a subfolder under it.
 
-* absolute path to the source file.
+* an absolute path to the source file.
 
 This target property *does not* guarantee a consistent unity file across
 different environments as the final priority is an absolute path.

Help/release/4.0.rst

@@ -78,6 +78,11 @@ Variables
   The :envvar:`CMAKE_POLICY_VERSION_MINIMUM` environment variable was
   added to initialize it.
 
+* The :variable:`CMAKE_UNITY_BUILD_RELOCATABLE` variable and corresponding
+  :prop_tgt:`UNITY_BUILD_RELOCATABLE` target property were added to make
+  sources generated for :variable:`CMAKE_UNITY_BUILD` to ``#include`` the
+  original source files using relative paths where possible.
+
 * The :variable:`CMAKE_XCODE_SCHEME_LLDB_INIT_FILE` variable and corresponding
   :prop_tgt:`XCODE_SCHEME_LLDB_INIT_FILE` target property were added to tell
   the :generator:`Xcode` generator what to put in the scheme's "LLDB Init File"

Help/variable/CMAKE_UNITY_BUILD_RELOCATABLE.rst

@@ -0,0 +1,9 @@
+CMAKE_UNITY_BUILD_RELOCATABLE
+-----------------------------
+
+.. versionadded:: 4.0
+
+This variable is used to initialize the :prop_tgt:`UNITY_BUILD_RELOCATABLE`
+property of targets when they are created.  Setting it to true causes
+sources generated for :variable:`CMAKE_UNITY_BUILD` to ``#include`` the
+original source files using relative paths where possible.