CPack/DEB: Make package description variable precedence match RPM

Make `CPACK_DEBIAN_PACKAGE_DESCRIPTION` fallback variable precedence
match CPackRPM behavior as much as possible.  This is technically a
breaking change, but the new behavior is more consistent with
expectation anyway.

Closes: #16272

6 files changed, 47 insertions, 28 deletions

diff --git a/Help/release/dev/cpack-deb-package-description-fallback.rst b/Help/release/dev/cpack-deb-package-description-fallback.rst
new file mode 100644
index 0000000..71ca821
--- /dev/null
+++ b/Help/release/dev/cpack-deb-package-description-fallback.rst
@@ -0,0 +1,15 @@
+cpack-deb-package-description-fallback
+--------------------------------------
+
+* The :module:`CPackDeb` module gained a new
+  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DESCRIPTION`
+  variable for component-specific package descriptions.
+
+* The :module:`CPackDeb` module changed its package description
+  override rules to match :module:`CPackRPM` module behavior.
+  If the :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` variable is set to
+  a non-default location then it is preferred to the
+  :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` variable.
+  This is a behavior change from previous versions but produces
+  more consistent and expected behavior.
+  See :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION`.
diff --git a/Modules/CPackDeb.cmake b/Modules/CPackDeb.cmake
index 1a7b923..423bb00 100644
--- a/Modules/CPackDeb.cmake
+++ b/Modules/CPackDeb.cmake
@@ -156,16 +156,18 @@
 #  * Default   : :code:`CPACK_PACKAGE_CONTACT`
 #
 # .. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
-#               CPACK_COMPONENT_<COMPONENT>_DESCRIPTION
+#               CPACK_DEBIAN_<COMPONENT>_PACKAGE_DESCRIPTION
 #
 #  The Debian package description
 #
 #  * Mandatory : YES
 #  * Default   :
 #
-#    - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set or
-#    - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
-#
+#    - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component based installers only) if set,
+#    - :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` if set to non default location,
+#    - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` if set,
+#    - :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` default value if set,
+#    - or "no package description available"
 #
 # .. variable:: CPACK_DEBIAN_PACKAGE_SECTION
 #               CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION
@@ -829,24 +831,23 @@ function(cpack_deb_prepare_package_vars)
   endif()
 
   # Description: (mandatory)
-  if(NOT CPACK_DEB_PACKAGE_COMPONENT)
-    if(NOT CPACK_DEBIAN_PACKAGE_DESCRIPTION)
-      if(NOT CPACK_PACKAGE_DESCRIPTION_SUMMARY)
-        message(FATAL_ERROR "CPackDeb: Debian package requires a summary for a package, set CPACK_PACKAGE_DESCRIPTION_SUMMARY or CPACK_DEBIAN_PACKAGE_DESCRIPTION")
-      endif()
-      set(CPACK_DEBIAN_PACKAGE_DESCRIPTION ${CPACK_PACKAGE_DESCRIPTION_SUMMARY})
+  if(CPACK_DEB_PACKAGE_COMPONENT)
+    if(CPACK_DEBIAN_${_local_component_name}_PACKAGE_DESCRIPTION)
+      set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "${CPACK_DEBIAN_${_local_component_name}_PACKAGE_DESCRIPTION}")
+    elseif(CPACK_COMPONENT_${_local_component_name}_DESCRIPTION)
+      set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "${CPACK_COMPONENT_${_local_component_name}_DESCRIPTION}")
     endif()
-  else()
-    set(component_description_var CPACK_COMPONENT_${_local_component_name}_DESCRIPTION)
-
-    # component description overrides package description
-    if(${component_description_var})
-      set(CPACK_DEBIAN_PACKAGE_DESCRIPTION ${${component_description_var}})
-    elseif(NOT CPACK_DEBIAN_PACKAGE_DESCRIPTION)
-      if(NOT CPACK_PACKAGE_DESCRIPTION_SUMMARY)
-        message(FATAL_ERROR "CPackDeb: Debian package requires a summary for a package, set CPACK_PACKAGE_DESCRIPTION_SUMMARY or CPACK_DEBIAN_PACKAGE_DESCRIPTION or ${component_description_var}")
-      endif()
-      set(CPACK_DEBIAN_PACKAGE_DESCRIPTION ${CPACK_PACKAGE_DESCRIPTION_SUMMARY})
+  endif()
+
+  if(NOT CPACK_DEBIAN_PACKAGE_DESCRIPTION)
+    if(CPACK_PACKAGE_DESCRIPTION_FILE AND NOT "${CPACK_PACKAGE_DESCRIPTION_FILE}" STREQUAL "${CMAKE_ROOT}/Templates/CPack.GenericDescription.txt")
+      file(READ "${CPACK_PACKAGE_DESCRIPTION_FILE}" CPACK_DEBIAN_PACKAGE_DESCRIPTION)
+    elseif(CPACK_PACKAGE_DESCRIPTION_SUMMARY)
+      set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "${CPACK_PACKAGE_DESCRIPTION_SUMMARY}")
+    elseif(CPACK_PACKAGE_DESCRIPTION_FILE) # use default package description file content
+      file(READ "${CPACK_PACKAGE_DESCRIPTION_FILE}" CPACK_DEBIAN_PACKAGE_DESCRIPTION)
+    else()
+      set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "no package description available")
     endif()
   endif()
 
diff --git a/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description1.cmake.in b/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description1.cmake.in
index 74d816c..6c5a655 100644
--- a/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description1.cmake.in
+++ b/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description1.cmake.in
@@ -15,8 +15,8 @@ set(CPACK_COMPONENTS_IGNORE_GROUPS 1)
 #set(CPACK_COMPONENTS_ALL_IN_ONE_PACKAGE 1)
 
 # overriding previous descriptions
-set(CPACK_PACKAGE_DESCRIPTION_SUMMARY           "main description")
-set(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION    "applications_description")
-set(CPACK_COMPONENT_HEADERS_DESCRIPTION         "headers_description")
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY               "main description")
+set(CPACK_DEBIAN_APPLICATIONS_PACKAGE_DESCRIPTION   "applications_description")
+set(CPACK_COMPONENT_HEADERS_DESCRIPTION             "headers_description")
 # libraries does not have any description and should inherit from CPACK_PACKAGE_DESCRIPTION_SUMMARY
 unset(CPACK_COMPONENT_LIBRARIES_DESCRIPTION)
diff --git a/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description2.cmake.in b/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description2.cmake.in
index cda79bc..92226d8 100644
--- a/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description2.cmake.in
+++ b/Tests/CPackComponentsDEB/MyLibCPackConfig-components-description2.cmake.in
@@ -17,10 +17,12 @@ set(CPACK_COMPONENTS_IGNORE_GROUPS 1)
 # overriding previous descriptions
 set(CPACK_PACKAGE_DESCRIPTION_SUMMARY           "main description 2")
 
+# and override CPACK_PACKAGE_DESCRIPTION_SUMMARY because of precedence
+set(CPACK_PACKAGE_DESCRIPTION_FILE
+  "@CPackComponentsDEB_SOURCE_DIR@/pkg_description.txt")
+
 # Components do not have any description
 unset(CPACK_COMPONENT_APPLICATIONS_DESCRIPTION)
 unset(CPACK_COMPONENT_HEADERS_DESCRIPTION)
-unset(CPACK_COMPONENT_LIBRARIES_DESCRIPTION)
-
 
 set(CPACK_COMPONENT_LIBRARIES_DESCRIPTION       "library description")
diff --git a/Tests/CPackComponentsDEB/RunCPackVerifyResult-components-description2.cmake b/Tests/CPackComponentsDEB/RunCPackVerifyResult-components-description2.cmake
index 35ca74c..7b94ca0 100644
--- a/Tests/CPackComponentsDEB/RunCPackVerifyResult-components-description2.cmake
+++ b/Tests/CPackComponentsDEB/RunCPackVerifyResult-components-description2.cmake
@@ -55,12 +55,12 @@ if(DPKGDEB_EXECUTABLE)
     message(STATUS "package='${dpkg_package_name}', description='${dpkg_description}'")
 
     if("${dpkg_package_name}" STREQUAL "mylib-applications")
-      if(NOT "${dpkg_description}" STREQUAL "main description 2")
+      if(NOT "${dpkg_description}" STREQUAL "Debian package description file")
         set(dpkgdeb_output_errors_all ${dpkgdeb_output_errors_all}
                                       "dpkg-deb: ${_f}: Incorrect description for package ${dpkg_package_name}: ${dpkg_description} != applications_description")
       endif()
     elseif("${dpkg_package_name}" STREQUAL "mylib-headers")
-      if(NOT "${dpkg_description}" STREQUAL "main description 2")
+      if(NOT "${dpkg_description}" STREQUAL "Debian package description file")
         set(dpkgdeb_output_errors_all ${dpkgdeb_output_errors_all}
                                       "dpkg-deb: ${_f}: Incorrect description for package ${dpkg_package_name}: ${dpkg_description} != headers_description")
       endif()
diff --git a/Tests/CPackComponentsDEB/pkg_description.txt b/Tests/CPackComponentsDEB/pkg_description.txt
new file mode 100644
index 0000000..99f8f9b
--- /dev/null
+++ b/Tests/CPackComponentsDEB/pkg_description.txt
@@ -0,0 +1 @@
+Debian package description file