Merge topic 'restore-CPACK_PACKAGEMAKER_CHOICES' into release-3.23

d099136add productbuild: Restore CPACK_PACKAGEMAKER_CHOICES variable

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7220

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.

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.

Source/CPack/cmCPackPKGGenerator.cxx

@@ -123,7 +123,9 @@ void cmCPackPKGGenerator::WriteDistributionFile(const char* metapackageFile,
   std::ostringstream xContents;
   cmXMLWriter xout(xContents, 1);
 
-  // Installer-wide options
+  // Installer-wide options and domains. These need to be separate from the
+  // choices and background elements added further below so that we can
+  // preserve backward compatibility.
   xout.StartElement("options");
   xout.Attribute("allow-external-scripts", "no");
   xout.Attribute("customize", "allow");
@@ -131,55 +133,69 @@ void cmCPackPKGGenerator::WriteDistributionFile(const char* metapackageFile,
     xout.Attribute("rootVolumeOnly", "false");
   }
   xout.EndElement();
+  this->CreateDomains(xout);
+
+  // In order to preserve backward compatibility, all elements added below
+  // here need to be made available in a variable named
+  // CPACK_PACKAGEMAKER_CHOICES. The above elements are new and only appear
+  // in the CPACK_APPLE_PKG_INSTALLER_CONTENT variable, which is a superset
+  // of what CPACK_PACKAGEMAKER_CHOICES used to provide. The renaming reflects
+  // the fact that CMake has deprecated the PackageMaker generator.
 
   // Create the choice outline, which provides a tree-based view of
   // the components in their groups.
-  xout.StartElement("choices-outline");
+  std::ostringstream choiceOut;
+  cmXMLWriter xChoiceOut(choiceOut, 1);
+  xChoiceOut.StartElement("choices-outline");
 
   // Emit the outline for the groups
   for (auto const& group : this->ComponentGroups) {
     if (group.second.ParentGroup == nullptr) {
-      CreateChoiceOutline(group.second, xout);
+      CreateChoiceOutline(group.second, xChoiceOut);
     }
   }
 
   // Emit the outline for the non-grouped components
   for (auto const& comp : this->Components) {
     if (!comp.second.Group) {
-      xout.StartElement("line");
-      xout.Attribute("choice", comp.first + "Choice");
-      xout.Content(""); // Avoid self-closing tag.
-      xout.EndElement();
+      xChoiceOut.StartElement("line");
+      xChoiceOut.Attribute("choice", comp.first + "Choice");
+      xChoiceOut.Content(""); // Avoid self-closing tag.
+      xChoiceOut.EndElement();
     }
   }
   if (!this->PostFlightComponent.Name.empty()) {
-    xout.StartElement("line");
-    xout.Attribute("choice", PostFlightComponent.Name + "Choice");
-    xout.Content(""); // Avoid self-closing tag.
-    xout.EndElement();
+    xChoiceOut.StartElement("line");
+    xChoiceOut.Attribute("choice", PostFlightComponent.Name + "Choice");
+    xChoiceOut.Content(""); // Avoid self-closing tag.
+    xChoiceOut.EndElement();
   }
-  xout.EndElement(); // choices-outline>
+  xChoiceOut.EndElement(); // choices-outline>
 
   // Create the actual choices
   for (auto const& group : this->ComponentGroups) {
-    CreateChoice(group.second, xout);
+    CreateChoice(group.second, xChoiceOut);
   }
   for (auto const& comp : this->Components) {
-    CreateChoice(comp.second, xout);
+    CreateChoice(comp.second, xChoiceOut);
   }
 
   if (!this->PostFlightComponent.Name.empty()) {
-    CreateChoice(PostFlightComponent, xout);
+    CreateChoice(PostFlightComponent, xChoiceOut);
   }
 
-  this->CreateDomains(xout);
-
-  // default background
-  this->CreateBackground(nullptr, metapackageFile, genName, xout);
+  // default background. These are not strictly part of the choices, but they
+  // must be included in CPACK_PACKAGEMAKER_CHOICES to preserve backward
+  // compatibility.
+  this->CreateBackground(nullptr, metapackageFile, genName, xChoiceOut);
   // Dark Aqua
-  this->CreateBackground("darkAqua", metapackageFile, genName, xout);
+  this->CreateBackground("darkAqua", metapackageFile, genName, xChoiceOut);
 
-  this->SetOption("CPACK_APPLE_PKG_INSTALLER_CONTENT", xContents.str());
+  // Provide the content for substitution into the template. Support both the
+  // old and new variables.
+  this->SetOption("CPACK_PACKAGEMAKER_CHOICES", choiceOut.str());
+  this->SetOption("CPACK_APPLE_PKG_INSTALLER_CONTENT",
+                  cmStrCat(xContents.str(), "    ", choiceOut.str()));
 
   // Create the distribution.dist file in the metapackage to turn it
   // into a distribution package.