diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD.rst | 5 | ||||
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst | 53 | ||||
| -rw-r--r-- | Help/release/dev/unity-build-anonymous-macros.rst | 7 | ||||
| -rw-r--r-- | Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst | 6 |
6 files changed, 73 insertions, 0 deletions
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 33af9f7..96c186f 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -353,6 +353,7 @@ Properties on Targets /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/UNITY_BUILD_MODE + /prop_tgt/UNITY_BUILD_UNIQUE_ID /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index f898ae9..838aa31 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -470,6 +470,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_UNIQUE_ID /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_GLOBALS diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index 04cede6..f827a20 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -70,6 +70,11 @@ a number of measures to help address such problems: problems with specific files than disabling unity builds for an entire target. +* Projects can set :prop_tgt:`UNITY_BUILD_UNIQUE_ID` to cause a valid + C-identifier to be generated which is unique per file in a unity + build. This can be used to avoid problems with anonymous namespaces + in unity builds. + * The :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` target properties can be used to inject code into the unity source files before and after every diff --git a/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst new file mode 100644 index 0000000..e0ee30e --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst @@ -0,0 +1,53 @@ +UNITY_BUILD_UNIQUE_ID +--------------------- + +The name of a valid C-identifier which is set to a unique per-file +value during unity builds. + +When this property is populated and when :prop_tgt:`UNITY_BUILD` +is true, the property value is used to define a compiler definition +of the specified name. The value of the defined symbol is unspecified, +but it is unique per file path. + +Given: + +.. code-block:: cmake + + set_target_properties(myTarget PROPERTIES + UNITY_BUILD "ON" + UNITY_BUILD_UNIQUE_ID "MY_UNITY_ID" + ) + +the ``MY_UNITY_ID`` symbol is defined to a unique per-file value. + +One known use case for this identifier is to disambiguate the +variables in an anonymous namespace in a limited scope. +Anonymous namespaces present a problem for unity builds because +they are used to ensure that certain variables and declarations +are scoped to a translation unit which is approximated by a +single source file. When source files are combined in a unity +build file, those variables in different files are combined in +a single translation unit and the names clash. This property can +be used to avoid that with code like the following: + +.. code-block:: cpp + + // Needed for when unity builds are disabled + #ifndef MY_UNITY_ID + #define MY_UNITY_ID + #endif + + namespace { namespace MY_UNITY_ID { + // The name 'i' clashes (or could clash) with other + // variables in other anonymous namespaces + int i = 42; + }} + + int use_var() + { + return MY_UNITY_ID::i; + } + +The pseudononymous namespace is used within a truly anonymous namespace. +On many platforms, this maintains the invariant that the symbols within +do not get external linkage when performing a unity build. diff --git a/Help/release/dev/unity-build-anonymous-macros.rst b/Help/release/dev/unity-build-anonymous-macros.rst new file mode 100644 index 0000000..ed8fb1a --- /dev/null +++ b/Help/release/dev/unity-build-anonymous-macros.rst @@ -0,0 +1,7 @@ +unity-build-anonymous-macros +---------------------------- + +* The :prop_tgt:`UNITY_BUILD_UNIQUE_ID` target property + was added to support generation of an identifier that is + unique per source file in unity builds. It can help to + resolve duplicate symbol problems with anonymous namespaces. diff --git a/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst b/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst new file mode 100644 index 0000000..b30e443 --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst @@ -0,0 +1,6 @@ +CMAKE_UNITY_BUILD_UNIQUE_ID +--------------------------- + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_UNIQUE_ID` +property of targets when they are created. It specifies the name of the +unique identifier generated per file in a unity build. |