From 89cea1c642c24ce3604b06813971f6d301b3887e Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 31 Mar 2025 19:25:05 -0400 Subject: Help: Document CMAKE_UNITY_BUILD_RELOCATABLE variable In commit 84996a65aa (Unity: Add option to use relative paths for unity files, 2024-10-15, v4.0.0-rc1~637^2) we added support for this variable to initialize the `UNITY_BUILD_RELOCATABLE` target property, but forgot to document it. Issue: #26352 --- Help/manual/cmake-variables.7.rst | 1 + Help/variable/CMAKE_UNITY_BUILD_RELOCATABLE.rst | 9 +++++++++ 2 files changed, 10 insertions(+) create mode 100644 Help/variable/CMAKE_UNITY_BUILD_RELOCATABLE.rst diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 07f3cf2..16c072d 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/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 diff --git a/Help/variable/CMAKE_UNITY_BUILD_RELOCATABLE.rst b/Help/variable/CMAKE_UNITY_BUILD_RELOCATABLE.rst new file mode 100644 index 0000000..09bc5cc --- /dev/null +++ b/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. -- cgit v0.12 From 20412690fb0db2694d679475e74ef675cf546900 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 31 Mar 2025 19:30:17 -0400 Subject: Help: Add 4.0 release note for UNITY_BUILD_RELOCATABLE This was left out of commit 84996a65aa (Unity: Add option to use relative paths for unity files, 2024-10-15, v4.0.0-rc1~637^2). Issue: #26352 --- Help/release/4.0.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Help/release/4.0.rst b/Help/release/4.0.rst index a7a3560..f4886f2 100644 --- a/Help/release/4.0.rst +++ b/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" -- cgit v0.12 From f706d8064bd487b8a2f8977bd19577b8b70dc1d1 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 31 Mar 2025 19:35:30 -0400 Subject: Help: Clarify wording of UNITY_BUILD_RELOCATABLE path alternatives --- Help/prop_tgt/UNITY_BUILD_RELOCATABLE.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Help/prop_tgt/UNITY_BUILD_RELOCATABLE.rst b/Help/prop_tgt/UNITY_BUILD_RELOCATABLE.rst index 74ef3b9..8e0f30d 100644 --- a/Help/prop_tgt/UNITY_BUILD_RELOCATABLE.rst +++ b/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. -- cgit v0.12