CPack: Set background image in macOS installer

Now you can set a background image and it's parameters in
productbuild and PackageMaker based installers.

Help/cpack_gen/packagemaker.rst

@@ -15,9 +15,60 @@ macOS using PackageMaker:
  compatible with. Different versions of macOS support different
  features. For example, CPack can only build component-based installers for
  macOS 10.4 or newer, and can only build installers that download
- component son-the-fly for macOS 10.5 or newer. If left blank, this value
+ components on-the-fly for macOS 10.5 or newer. If left blank, this value
  will be set to the minimum version of macOS that supports the requested
  features. Set this variable to some value (e.g., 10.4) only if you want to
  guarantee that your installer will work on that version of macOS, and
  don't mind missing extra features available in the installer shipping with
  later versions of macOS.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND
+
+ Adds a background to Distribtion XML if specified. The value contains the
+ path to image in ``Resources`` directory.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT
+
+ Adds an ``alignment`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING
+
+ Adds a ``scaling`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE
+
+ Adds a ``mime-type`` attribute to the background in Distribution XML.
+ The option contains MIME type of an image.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI
+
+ Adds an ``uti`` attribute to the background in Distribution XML.
+ The option contains UTI type of an image.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA
+
+ Adds a background for the Dark Aqua theme to Distribution XML if
+ specified. The value contains the path to image in ``Resources``
+ directory.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option,
+ but for the dark theme.

Help/cpack_gen/productbuild.rst

@@ -58,7 +58,6 @@ macOS using ProductBuild:
  component name.  No ``postinstall`` script is added if this variable is not
  defined for a given component.
 
-
 .. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR
 
  If specified the productbuild generator copies files from this directory
@@ -66,3 +65,54 @@ macOS using ProductBuild:
  before the :variable:`CPACK_RESOURCE_FILE_WELCOME`,
  :variable:`CPACK_RESOURCE_FILE_README`, and
  :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND
+
+ Adds a background to Distribtion XML if specified. The value contains the
+ path to image in ``Resources`` directory.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT
+
+ Adds an ``alignment`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING
+
+ Adds a ``scaling`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE
+
+ Adds a ``mime-type`` attribute to the background in Distribution XML.
+ The option contains MIME type of an image.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI
+
+ Adds an ``uti`` attribute to the background in Distribution XML.
+ The option contains UTI type of an image.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA
+
+ Adds a background for the Dark Aqua theme to Distribution XML if
+ specified. The value contains the path to image in ``Resources``
+ directory.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option,
+ but for the dark theme.

Help/release/dev/cpack-pkg-background.rst

+cpack-pkg-background
+--------------------
+
+* The :cpack_gen:`CPack productbuild Generator` and
+  :cpack_gen:`CPack PackageMaker Generator` gained options
+  :variable:`CPACK_PRODUCTBUILD_BACKGROUND` and
+  :variable:`CPACK_PACKAGEMAKER_BACKGROUND`, respectively,
+  to specify a background image for the macOS installer.

Source/CPack/cmCPackPKGGenerator.cxx

@@ -46,7 +46,66 @@ std::string cmCPackPKGGenerator::GetPackageName(
   return component.ArchiveFile + ".pkg";
 }
 
-void cmCPackPKGGenerator::WriteDistributionFile(const char* metapackageFile)
+void cmCPackPKGGenerator::CreateBackground(const char* themeName,
+                                           const char* metapackageFile,
+                                           cm::string_view genName,
+                                           cmXMLWriter& xout)
+{
+  std::string paramSuffix =
+    (themeName == nullptr) ? "" : cmSystemTools::UpperCase(themeName);
+  std::string opt = (themeName == nullptr)
+    ? cmStrCat("CPACK_", genName, "_BACKGROUND")
+    : cmStrCat("CPACK_", genName, "_BACKGROUND_", paramSuffix);
+  const char* bgFileName = this->GetOption(opt);
+  if (bgFileName == nullptr) {
+    return;
+  }
+
+  std::string bgFilePath = cmStrCat(metapackageFile, "/Contents/", bgFileName);
+
+  if (!cmSystemTools::FileExists(bgFilePath)) {
+    cmCPackLogger(cmCPackLog::LOG_ERROR,
+                  "Background image doesn't exist in the resource directory: "
+                    << bgFileName << std::endl);
+    return;
+  }
+
+  if (themeName == nullptr) {
+    xout.StartElement("background");
+  } else {
+    xout.StartElement(cmStrCat("background-", themeName));
+  }
+
+  xout.Attribute("file", bgFileName);
+
+  const char* param = this->GetOption(cmStrCat(opt, "_ALIGNMENT"));
+  if (param != nullptr) {
+    xout.Attribute("alignment", param);
+  }
+
+  param = this->GetOption(cmStrCat(opt, "_SCALING"));
+  if (param != nullptr) {
+    xout.Attribute("scaling", param);
+  }
+
+  // Apple docs say that you must provide either mime-type or uti
+  // attribute for the background, but I've seen examples that
+  // doesn't have them, so don't make them mandatory.
+  param = this->GetOption(cmStrCat(opt, "_MIME_TYPE"));
+  if (param != nullptr) {
+    xout.Attribute("mime-type", param);
+  }
+
+  param = this->GetOption(cmStrCat(opt, "_UTI"));
+  if (param != nullptr) {
+    xout.Attribute("uti", param);
+  }
+
+  xout.EndElement();
+}
+
+void cmCPackPKGGenerator::WriteDistributionFile(const char* metapackageFile,
+                                                const char* genName)
 {
   std::string distributionTemplate =
     this->FindTemplate("Internal/CPack/CPack.distribution.dist.in");
@@ -102,6 +161,11 @@ void cmCPackPKGGenerator::WriteDistributionFile(const char* metapackageFile)
     CreateChoice(PostFlightComponent, xout);
   }
 
+  // default background
+  this->CreateBackground(nullptr, metapackageFile, genName, xout);
+  // Dark Aqua
+  this->CreateBackground("darkAqua", metapackageFile, genName, xout);
+
   this->SetOption("CPACK_PACKAGEMAKER_CHOICES", choiceOut.str().c_str());
 
   // Create the distribution.dist file in the metapackage to turn it

Source/CPack/cmCPackPKGGenerator.h

@@ -9,6 +9,8 @@
 #include <sstream>
 #include <string>
 
+#include <cm/string_view>
+
 #include "cmCPackComponentGroup.h"
 #include "cmCPackGenerator.h"
 
@@ -57,7 +59,7 @@ protected:
   // inter-component dependencies. metapackageFile is the name of the
   // metapackage for the distribution. Only valid for a
   // component-based install.
-  void WriteDistributionFile(const char* metapackageFile);
+  void WriteDistributionFile(const char* metapackageFile, const char* genName);
 
   // Subroutine of WriteDistributionFile that writes out the
   // dependency attributes for inter-component dependencies.
@@ -85,6 +87,10 @@ protected:
   /// installer GUI.
   void CreateChoice(const cmCPackComponent& component, cmXMLWriter& xout);
 
+  /// Creates a background in the distribution XML.
+  void CreateBackground(const char* themeName, const char* metapackageFile,
+                        cm::string_view genName, cmXMLWriter& xout);
+
   // The PostFlight component when creating a metapackage
   cmCPackComponent PostFlightComponent;
 };

Source/CPack/cmCPackPackageMakerGenerator.cxx

@@ -279,7 +279,7 @@ int cmCPackPackageMakerGenerator::PackageFiles()
   } else {
     // We have built the package in place. Generate the
     // distribution.dist file to describe it for the installer.
-    WriteDistributionFile(packageDirFileName.c_str());
+    WriteDistributionFile(packageDirFileName.c_str(), "PACKAGEMAKER");
   }
 
   std::string tmpFile = cmStrCat(this->GetOption("CPACK_TOPLEVEL_DIRECTORY"),

Source/CPack/cmCPackProductBuildGenerator.cxx

@@ -81,7 +81,7 @@ int cmCPackProductBuildGenerator::PackageFiles()
   }
 
   // combine package(s) into a distribution
-  WriteDistributionFile(packageDirFileName.c_str());
+  WriteDistributionFile(packageDirFileName.c_str(), "PRODUCTBUILD");
   std::ostringstream pkgCmd;
 
   std::string version = this->GetOption("CPACK_PACKAGE_VERSION");