Imported Upstream version 3.20.0upstream/3.20.0

20 files changed, 227 insertions, 20 deletions

diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst
index 42210696b..677e06df0 100644
--- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst
+++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst
@@ -3,7 +3,7 @@ ARCHIVE_OUTPUT_DIRECTORY
 
 .. |XXX| replace:: :ref:`ARCHIVE <Archive Output Artifacts>`
 .. |xxx| replace:: archive
-.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_ARCHIVE_OUTPUT_DIRECTORY
+.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`
 .. include:: XXX_OUTPUT_DIRECTORY.txt
 
 See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property.
diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst
index c18859b56..52d96e02f 100644
--- a/Help/prop_tgt/AUTOMOC.rst
+++ b/Help/prop_tgt/AUTOMOC.rst
@@ -137,7 +137,8 @@ parent directory path of the ``moc`` input file.  This scheme allows to have
 All not included ``moc`` output files will be included automatically by the
 CMake generated file
 
-- ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp``,
+- ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp``, or
+- ``<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp``,
 
 which is added to the target's sources.
 
diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst
index fcc472568..6517035a2 100644
--- a/Help/prop_tgt/CUDA_STANDARD.rst
+++ b/Help/prop_tgt/CUDA_STANDARD.rst
@@ -9,7 +9,7 @@ This property specifies the CUDA/C++ standard whose features are requested
 to build this target.  For some compilers, this results in adding a
 flag such as ``-std=gnu++11`` to the compile line.
 
-Supported values are ``98``, ``03``, ``11``, ``14``, ``17``, ``20``.
+Supported values are ``98``, ``03``, ``11``, ``14``, ``17``, ``20``, ``23``.
 
 If the value requested does not result in a compile flag being added for
 the compiler in use, a previous standard flag will be added instead.  This
diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst
index f322ffe1f..be0dab565 100644
--- a/Help/prop_tgt/CXX_STANDARD.rst
+++ b/Help/prop_tgt/CXX_STANDARD.rst
@@ -11,7 +11,7 @@ flag such as ``-std=gnu++11`` to the compile line.  For compilers that
 have no notion of a standard level, such as Microsoft Visual C++ before
 2015 Update 3, this has no effect.
 
-Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``.
+Supported values are ``98``, ``11``, ``14``, ``17``, ``20``, ``23``.
 
 If the value requested does not result in a compile flag being added for
 the compiler in use, a previous standard flag will be added instead.  This
diff --git a/Help/prop_tgt/EXPORT_COMPILE_COMMANDS.rst b/Help/prop_tgt/EXPORT_COMPILE_COMMANDS.rst
new file mode 100644
index 000000000..0b1145c4e
--- /dev/null
+++ b/Help/prop_tgt/EXPORT_COMPILE_COMMANDS.rst
@@ -0,0 +1,9 @@
+EXPORT_COMPILE_COMMANDS
+-----------------------
+
+.. versionadded:: 3.20
+
+Enable/Disable output of compile commands during generation for a target.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_EXPORT_COMPILE_COMMANDS` if it is set when a target is created.
diff --git a/Help/prop_tgt/IMPORTED_OBJECTS.rst b/Help/prop_tgt/IMPORTED_OBJECTS.rst
index bbbcd866d..f3577eb99 100644
--- a/Help/prop_tgt/IMPORTED_OBJECTS.rst
+++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst
@@ -3,11 +3,91 @@ IMPORTED_OBJECTS
 
 .. versionadded:: 3.9
 
-A :ref:`semicolon-separated list <CMake Language Lists>` of absolute paths to the object
-files on disk for an :ref:`imported <Imported targets>`
+A :ref:`semicolon-separated list <CMake Language Lists>` of absolute paths
+to the object files on disk for an :ref:`imported <Imported targets>`
 :ref:`object library <object libraries>`.
 
 Ignored for non-imported targets.
 
 Projects may skip ``IMPORTED_OBJECTS`` if the configuration-specific
-property :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` is set instead.
+property :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` is set instead, except in
+situations as noted in the section below.
+
+
+Xcode Generator Considerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.20
+
+For Apple platforms, a project may be built for more than one architecture.
+This is controlled by the :variable:`CMAKE_OSX_ARCHITECTURES` variable.
+For all but the :generator:`Xcode` generator, CMake invokes compilers once
+per source file and passes multiple ``-arch`` flags, leading to a single
+object file which will be a universal binary.  Such object files work well
+when listed in the ``IMPORTED_OBJECTS`` of a separate CMake build, even for
+the :generator:`Xcode` generator.  But producing such object files with the
+:generator:`Xcode` generator is more difficult, since it invokes the compiler
+once per architecture for each source file.  Unlike the other generators,
+it does not generate universal object file binaries.
+
+A further complication with the :generator:`Xcode` generator is that when
+targeting device platforms (iOS, tvOS or watchOS), the :generator:`Xcode`
+generator has the ability to use either the device or simulator SDK without
+needing CMake to be re-run.  The SDK can be selected at build time.
+But since some architectures can be supported by both the device and the
+simulator SDKs (e.g. ``arm64`` with Xcode 12 or later), not all combinations
+can be represented in a single universal binary.  The only solution in this
+case is to have multiple object files.
+
+``IMPORTED_OBJECTS`` doesn't support generator expressions, so every file
+it lists needs to be valid for every architecture and SDK.  If incorporating
+object files that are not universal binaries, the path and/or file name of
+each object file has to somehow encapsulate the different architectures and
+SDKs.  With the :generator:`Xcode` generator, Xcode variables of the form
+``$(...)`` can be used to represent these aspects and Xcode will substitute
+the appropriate values at build time.  CMake doesn't interpret these
+variables and embeds them unchanged in the Xcode project file.
+``$(CURRENT_ARCH)`` can be used to represent the architecture, while
+``$(EFFECTIVE_PLATFORM_NAME)`` can be used to differentiate between SDKs.
+
+The following shows one example of how these two variables can be used to
+refer to an object file whose location depends on both the SDK and the
+architecture:
+
+.. code-block:: cmake
+
+  add_library(someObjs OBJECT IMPORTED)
+
+  set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS
+    # Quotes are required because of the ()
+    "/path/to/somewhere/objects$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o"
+  )
+
+  # Example paths:
+  #   /path/to/somewhere/objects-iphoneos/arm64/func.o
+  #   /path/to/somewhere/objects-iphonesimulator/x86_64/func.o
+
+In some cases, you may want to have configuration-specific object files
+as well.  The :variable:`CMAKE_CFG_INTDIR` variable can be a convenient
+way of capturing this in combination with the SDK:
+
+.. code-block:: cmake
+
+  add_library(someObjs OBJECT IMPORTED)
+  set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS
+    "/path/to/somewhere/${CMAKE_CFG_INTDIR}/$(CURRENT_ARCH)/func.o"
+  )
+
+  # Example paths:
+  #   /path/to/somewhere/Release-iphoneos/arm64/func.o
+  #   /path/to/somewhere/Debug-iphonesimulator/x86_64/func.o
+
+When any Xcode variable or :variable:`CMAKE_CFG_INTDIR` is used, CMake is
+not able to fully evaluate the path(s) at configure time.  One consequence
+of this is that the configuration-specific
+:prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` properties cannot be used, since
+CMake cannot determine whether an object file exists at a particular
+``<CONFIG>`` location.  The ``IMPORTED_OBJECTS`` property must be used for
+these situations and the configuration-specific aspects of the path must be
+handled by using :variable:`CMAKE_CFG_INTDIR` or with another Xcode variable
+``$(CONFIGURATION)``.
diff --git a/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst
index b12ca3887..238395a23 100644
--- a/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst
+++ b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst
@@ -3,7 +3,18 @@ IMPORTED_OBJECTS_<CONFIG>
 
 .. versionadded:: 3.9
 
-<CONFIG>-specific version of :prop_tgt:`IMPORTED_OBJECTS` property.
+``<CONFIG>``-specific version of :prop_tgt:`IMPORTED_OBJECTS` property.
 
 Configuration names correspond to those provided by the project from
 which the target is imported.
+
+
+Xcode Generator Considerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Do not use this ``<CONFIG>``-specific property if you need to use Xcode
+variables like ``$(CURRENT_ARCH)`` or ``$(EFFECTIVE_PLATFORM_NAME)`` in
+the value.  The ``<CONFIG>``-specific properties will be ignored in such
+cases because CMake cannot determine whether a file exists at the
+configuration-specific path at configuration time.  For such cases, use
+:prop_tgt:`IMPORTED_OBJECTS` instead.
diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst
index 747615ac8..8faefb71c 100644
--- a/Help/prop_tgt/INSTALL_NAME_DIR.rst
+++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst
@@ -12,5 +12,5 @@ This property is initialized by the value of the variable
 created.
 
 This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
-In particular, the ``$<INSTALL_PREFIX>`` generator expression can be used to set the
-directory relative to the install-time prefix.
+In particular, the :genex:`$<INSTALL_PREFIX>` generator expression can be
+used to set the directory relative to the install-time prefix.
diff --git a/Help/prop_tgt/LANG_CLANG_TIDY.rst b/Help/prop_tgt/LANG_CLANG_TIDY.rst
index 7fc23721c..af16d3c5b 100644
--- a/Help/prop_tgt/LANG_CLANG_TIDY.rst
+++ b/Help/prop_tgt/LANG_CLANG_TIDY.rst
@@ -3,7 +3,7 @@
 
 .. versionadded:: 3.6
 
-This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``.
+This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, ``OBJC`` or ``OBJCXX``.
 
 Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command
 line for the ``clang-tidy`` tool.  The :ref:`Makefile Generators`
diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst
index 785a57bbf..9fbe90408 100644
--- a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst
+++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst
@@ -3,7 +3,7 @@ LIBRARY_OUTPUT_DIRECTORY
 
 .. |XXX| replace:: :ref:`LIBRARY <Library Output Artifacts>`
 .. |xxx| replace:: library
-.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_LIBRARY_OUTPUT_DIRECTORY
+.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY`
 .. include:: XXX_OUTPUT_DIRECTORY.txt
 
 See also the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` target property.
diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst
index 1067153e6..96088af96 100644
--- a/Help/prop_tgt/OBJCXX_STANDARD.rst
+++ b/Help/prop_tgt/OBJCXX_STANDARD.rst
@@ -9,7 +9,7 @@ This property specifies the ObjC++ standard whose features are requested
 to build this target.  For some compilers, this results in adding a
 flag such as ``-std=gnu++11`` to the compile line.
 
-Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``.
+Supported values are ``98``, ``11``, ``14``, ``17``, ``20``, ``23``.
 
 If the value requested does not result in a compile flag being added for
 the compiler in use, a previous standard flag will be added instead.  This
diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst
index 12390f50a..3c375463c 100644
--- a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst
+++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst
@@ -3,7 +3,7 @@ RUNTIME_OUTPUT_DIRECTORY
 
 .. |XXX| replace:: :ref:`RUNTIME <Runtime Output Artifacts>`
 .. |xxx| replace:: runtime
-.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_RUNTIME_OUTPUT_DIRECTORY
+.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY`
 .. include:: XXX_OUTPUT_DIRECTORY.txt
 
 See also the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` target property.
diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst
index 04cede61e..f827a20a1 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 000000000..2c95e027c
--- /dev/null
+++ b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst
@@ -0,0 +1,55 @@
+UNITY_BUILD_UNIQUE_ID
+---------------------
+
+.. versionadded:: 3.20
+
+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/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst
index 71858c50e..fbe760815 100644
--- a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst
+++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst
@@ -3,9 +3,15 @@ XCODE_ATTRIBUTE_<an-attribute>
 
 Set Xcode target attributes directly.
 
-Tell the :generator:`Xcode` generator to set '<an-attribute>' to a given
+Tell the :generator:`Xcode` generator to set ``<an-attribute>`` to a given
 value in the generated Xcode project.  Ignored on other generators.
 
+This offers low-level control over the generated Xcode project file.
+It is meant as a last resort for specifying settings that CMake does
+not otherwise have a way to control.  Although this can override a
+setting CMake normally produces on its own, doing so bypasses CMake's
+model of the project and can break things.
+
 See the :variable:`CMAKE_XCODE_ATTRIBUTE_<an-attribute>` variable
 to set attributes on all targets in a directory tree.
 
diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst
new file mode 100644
index 000000000..7b6812678
--- /dev/null
+++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst
@@ -0,0 +1,8 @@
+XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY
+----------------------------------------
+
+.. versionadded:: 3.20
+
+Tell the :generator:`Xcode` generator to perform code signing for all the
+frameworks and libraries that are embedded using the
+:prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property.
diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst
new file mode 100644
index 000000000..29f8c5c03
--- /dev/null
+++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst
@@ -0,0 +1,8 @@
+XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY
+---------------------------------------------
+
+.. versionadded:: 3.20
+
+Tell the :generator:`Xcode` generator to remove headers from all the
+frameworks that are embedded using the
+:prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property.
diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst
new file mode 100644
index 000000000..90c5bc787
--- /dev/null
+++ b/Help/prop_tgt/XCODE_EMBED_type.rst
@@ -0,0 +1,14 @@
+XCODE_EMBED_<type>
+------------------
+
+.. versionadded:: 3.20
+
+Tell the :generator:`Xcode` generator to embed the specified list of items into
+the target bundle.  ``<type>`` specifies the embed build phase to use.
+
+Currently, the only supported value for ``<type>`` is ``FRAMEWORKS``.
+The specified items will be added to the ``Embed Frameworks`` build phase.
+The items can be CMake target names or paths to frameworks or libraries.
+See also :prop_tgt:`XCODE_EMBED_<type>_PATH`,
+:prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` and
+:prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`.
diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst
new file mode 100644
index 000000000..887cf5721
--- /dev/null
+++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst
@@ -0,0 +1,9 @@
+XCODE_EMBED_<type>_PATH
+-----------------------
+
+.. versionadded:: 3.20
+
+Tell the :generator:`Xcode` generator the relative path to use when embedding
+the items specified by :prop_tgt:`XCODE_EMBED_<type>`.  The path is relative
+to the base location of the ``Embed XXX`` build phase associated with
+``<type>``.
diff --git a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt
index 3ae54484a..d38a96e8b 100644
--- a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt
+++ b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt
@@ -3,9 +3,10 @@ Output directory in which to build |XXX| target files.
 This property specifies the directory into which |xxx| target files
 should be built.  The property value may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
-Multi-configuration generators (VS, Xcode) append a per-configuration
-subdirectory to the specified directory unless a generator expression
-is used.
+Multi-configuration generators (:ref:`Visual Studio <Visual Studio Generators>`,
+:generator:`Xcode`, :generator:`Ninja Multi-Config`) append a
+per-configuration subdirectory to the specified directory unless a generator
+expression is used.
 
-This property is initialized by the value of the variable
-|CMAKE_XXX_OUTPUT_DIRECTORY| if it is set when a target is created.
+This property is initialized by the value of the
+|CMAKE_XXX_OUTPUT_DIRECTORY| variable if it is set when a target is created.