7 files changed, 114 insertions, 29 deletions
diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst
index 26e0782..48a9b44 100644
--- a/Help/cpack_gen/productbuild.rst
+++ b/Help/cpack_gen/productbuild.rst
@@ -203,3 +203,47 @@ installer.
 
  Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option,
  but for the dark theme.
+
+Distribution XML Template
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CPack uses a template file to generate the ``distribution.dist`` file used
+internally by this package generator. Ordinarily, CMake provides the template
+file, but projects may supply their own by placing a file called
+``CPack.distribution.dist.in`` in one of the directories listed in the
+:variable:`CMAKE_MODULE_PATH` variable. CPack will then pick up the project's
+template file instead of using its own.
+
+The ``distribution.dist`` file is generated by performing substitutions
+similar to the :command:`configure_file` command. Any variable set when
+CPack runs will be available for substitution using the usual ``@...@``
+form. The following variables are also set internally and made available for
+substitution:
+
+``CPACK_RESOURCE_FILE_LICENSE_NOPATH``
+  Same as :variable:`CPACK_RESOURCE_FILE_LICENSE` except without the path.
+  The named file will be available in the same directory as the generated
+  ``distribution.dist`` file.
+
+``CPACK_RESOURCE_FILE_README_NOPATH``
+  Same as :variable:`CPACK_RESOURCE_FILE_README` except without the path.
+  The named file will be available in the same directory as the generated
+  ``distribution.dist`` file.
+
+``CPACK_RESOURCE_FILE_WELCOME_NOPATH``
+  Same as :variable:`CPACK_RESOURCE_FILE_WELCOME` except without the path.
+  The named file will be available in the same directory as the generated
+  ``distribution.dist`` file.
+
+``CPACK_APPLE_PKG_INSTALLER_CONTENT``
+  .. versionadded:: 3.23
+
+  This contains all the XML elements that specify installer-wide options
+  (including domain details), default backgrounds and the choices outline.
+
+``CPACK_PACKAGEMAKER_CHOICES``
+  .. deprecated:: 3.23
+
+  This contains only the XML elements that specify the default backgrounds
+  and the choices outline. It does not include the installer-wide options or
+  any domain details. Use ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead.
diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst
index 2380de4..7638d22 100644
--- a/Help/dev/experimental.rst
+++ b/Help/dev/experimental.rst
@@ -36,7 +36,14 @@ For example, add code like the following to a test project:
 The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is
 expected to process the translation unit, write preprocessor dependencies
 to the file specified by the ``<DEP_FILE>`` placeholder, and write module
-dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder.
+dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
+``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
+for scandep rules which use ``msvc``-style dependency reporting.
+
+For tools which need to know the file set the source belongs to, the
+``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may
+be provided so that different source types can be distinguished prior to
+scanning.
 
 The module dependencies should be written in the format described
 by the `P1689r4`_ paper.
diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst
index 8b20a2d..09553cb 100644
--- a/Help/guide/tutorial/index.rst
+++ b/Help/guide/tutorial/index.rst
@@ -11,8 +11,9 @@ work together in an example project can be very helpful.
 Steps
 =====
 
-The tutorial documentation and source code for examples can be found in
-the ``Help/guide/tutorial`` directory of the CMake source code tree.
+.. include:: source.txt
+
+|tutorial_source|
 Each step has its own subdirectory containing code that may be used as a
 starting point. The tutorial examples are progressive so that each step
 provides the complete solution for the previous step.
diff --git a/Help/guide/tutorial/source.txt b/Help/guide/tutorial/source.txt
new file mode 100644
index 0000000..bb45e86
--- /dev/null
+++ b/Help/guide/tutorial/source.txt
@@ -0,0 +1,3 @@
+.. |tutorial_source| replace::
+  The tutorial documentation and source code examples can be found in
+  the ``Help/guide/tutorial`` directory of the CMake source code tree.
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index f48313a..bceff2d 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -1040,24 +1040,26 @@ Additionally, IDEs will show the source files as part of the target for
 interactive reading and editing.
 
 A primary use-case for ``INTERFACE`` libraries is header-only libraries.
+Since CMake 3.23, header files may be associated with a library by adding
+them to a header set using the :command:`target_sources` command:
 
 .. code-block:: cmake
 
-  add_library(Eigen INTERFACE
-    src/eigen.h
-    src/vector.h
-    src/matrix.h
-    )
-  target_include_directories(Eigen INTERFACE
-    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
-    $<INSTALL_INTERFACE:include/Eigen>
+  add_library(Eigen INTERFACE)
+
+  target_sources(Eigen INTERFACE
+    FILE_SET HEADERS
+      BASE_DIRS src
+      FILES src/eigen.h src/vector.h src/matrix.h
   )
 
   add_executable(exe1 exe1.cpp)
   target_link_libraries(exe1 Eigen)
 
-Here, the usage requirements from the ``Eigen`` target are consumed and used
-when compiling, but it has no effect on linking.
+When we specify the ``FILE_SET`` here, the ``BASE_DIRS`` we define automatically
+become include directories in the usage requirements for the target ``Eigen``.
+The usage requirements from the target are consumed and used when compiling, but
+have no effect on linking.
 
 Another use-case is to employ an entirely target-focussed design for usage
 requirements:
@@ -1081,26 +1083,25 @@ This way, the build specification of ``exe1`` is expressed entirely as linked
 targets, and the complexity of compiler-specific flags is encapsulated in an
 ``INTERFACE`` library target.
 
-``INTERFACE`` libraries may be installed and exported.  Any content they refer
-to must be installed separately:
+``INTERFACE`` libraries may be installed and exported. We can install the
+default header set along with the target:
 
 .. code-block:: cmake
 
-  set(Eigen_headers
-    src/eigen.h
-    src/vector.h
-    src/matrix.h
-    )
-  add_library(Eigen INTERFACE ${Eigen_headers})
-  target_include_directories(Eigen INTERFACE
-    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
-    $<INSTALL_INTERFACE:include/Eigen>
+  add_library(Eigen INTERFACE)
+
+  target_sources(Eigen INTERFACE
+    FILE_SET HEADERS
+      BASE_DIRS src
+      FILES src/eigen.h src/vector.h src/matrix.h
   )
 
-  install(TARGETS Eigen EXPORT eigenExport)
+  install(TARGETS Eigen EXPORT eigenExport
+    FILE_SET HEADERS DESTINATION include/Eigen)
   install(EXPORT eigenExport NAMESPACE Upstream::
     DESTINATION lib/cmake/Eigen
   )
-  install(FILES ${Eigen_headers}
-    DESTINATION include/Eigen
-  )
+
+Here, the headers defined in the header set are installed to ``include/Eigen``.
+The install destination automatically becomes an include directory that is a
+usage requirement for consumers.
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 1ef1ec8..22c14df 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -599,7 +599,9 @@ String Transformations
 
   .. versionadded:: 3.15
 
-  Removes duplicated items in the given ``list``.
+  Removes duplicated items in the given ``list``. The relative order of items
+  is preserved, but if duplicates are encountered, only the first instance is
+  preserved.
 
 .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex>
 
diff --git a/Help/release/3.23.rst b/Help/release/3.23.rst
index 2febbec..47c4243 100644
--- a/Help/release/3.23.rst
+++ b/Help/release/3.23.rst
@@ -185,6 +185,13 @@ CPack
   :variable:`CPACK_PRODUCTBUILD_IDENTIFIER`, used to customize the unique
   product identifier associated with the product.
 
+* The ``CPack.distribution.dist.in`` template used by the
+  :cpack_gen:`CPack productbuild Generator` and
+  :cpack_gen:`CPack PackageMaker Generator` was updated to use a new
+  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable for its main content.
+  This replaced the previously undocumented and now deprecated
+  ``CPACK_PACKAGEMAKER_CHOICES`` variable.
+
 * The :cpack_gen:`CPack IFW Generator` gained the new
   :variable:`CPACK_IFW_ARCHIVE_FORMAT` and
   :variable:`CPACK_IFW_ARCHIVE_COMPRESSION` variables for setting the
@@ -230,6 +237,15 @@ Deprecated and Removed Features
 
 * The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed.
 
+* The previously undocumented ``CPACK_PACKAGEMAKER_CHOICES`` variable used in
+  the ``CPack.distribution.dist.in`` template has been replaced by a new
+  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable. This only affects projects
+  that were providing their own custom ``CPack.distribution.dist.in`` template
+  file, but still relied on ``CPACK_PACKAGEMAKER_CHOICES`` being set. Those
+  custom template files should be updated to use
+  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead, or to fully define all the
+  template file's contents without relying on substitution of either variable.
+
 Other Changes
 =============
 
@@ -282,3 +298,14 @@ Changes made since CMake 3.23.0 include the following.
 * The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` target
   properties added in CMake 3.23.0 are now read-only records of the header
   sets created by the :command:`target_sources` command.
+
+3.23.2
+------
+
+* The ``CPACK_PACKAGEMAKER_CHOICES`` variable used in the
+  ``CPack.distribution.dist.in`` template file was replaced by a new
+  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable in CMake 3.23.0.
+  This broke projects that provided their own template file but still
+  expected the ``CPACK_PACKAGEMAKER_CHOICES`` variable to be defined.
+  The old ``CPACK_PACKAGEMAKER_CHOICES`` variable is now also set to the
+  same content as it was before, but it is formally deprecated.