FeatureSummary: Add DEFAULT_DESCRIPTION option to feature_summary

If enabled and only one package type is selected, it will print the
default title for the selected package type.

4 files changed, 161 insertions, 14 deletions

diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake
index f29a5f0432..2913753712 100644
--- a/Modules/FeatureSummary.cmake
+++ b/Modules/FeatureSummary.cmake
@@ -196,7 +196,7 @@ endfunction()
                      [VAR <variable_name>]
                      [INCLUDE_QUIET_PACKAGES]
                      [FATAL_ON_MISSING_REQUIRED_PACKAGES]
-                     [DESCRIPTION "<description>"]
+                     [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
                      [QUIET_ON_EMPTY]
                      WHAT (ALL
                           | PACKAGES_FOUND | PACKAGES_NOT_FOUND
@@ -247,7 +247,10 @@ endfunction()
   information is "printed" into the specified variable.  If ``FILENAME`` is
   not used, the information is printed to the terminal.  Using the
   ``DESCRIPTION`` option a description or headline can be set which will be
-  printed above the actual content.
+  printed above the actual content.  If only one type of
+  package was requested, no title is printed, unless it is explicitly set using
+  either ``DESCRIPTION`` to use a custom string, or ``DEFAULT_DESCRIPTION`` to
+  use a default title for the requested type.
   If ``INCLUDE_QUIET_PACKAGES`` is given, packages which have been searched with
   ``find_package(... QUIET)`` will also be listed. By default they are skipped.
   If ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` is given, CMake will abort if a
@@ -306,8 +309,14 @@ endfunction()
 
 function(FEATURE_SUMMARY)
 # CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
-  set(options APPEND INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES QUIET_ON_EMPTY)
-  set(oneValueArgs FILENAME VAR DESCRIPTION)
+  set(options APPEND
+              INCLUDE_QUIET_PACKAGES
+              FATAL_ON_MISSING_REQUIRED_PACKAGES
+              QUIET_ON_EMPTY
+              DEFAULT_DESCRIPTION)
+  set(oneValueArgs FILENAME
+                   VAR
+                   DESCRIPTION)
   set(multiValueArgs WHAT)
 
   CMAKE_PARSE_ARGUMENTS(_FS "${options}" "${oneValueArgs}" "${multiValueArgs}"  ${_FIRST_ARG} ${ARGN})
@@ -320,6 +329,11 @@ function(FEATURE_SUMMARY)
     message(FATAL_ERROR "The call to FEATURE_SUMMARY() doesn't set the required WHAT argument.")
   endif()
 
+  if(_FS_DEFAULT_DESCRIPTION AND DEFINED _FS_DESCRIPTION)
+    message(WARNING "DEFAULT_DESCRIPTION option discarded since DESCRIPTION is set.")
+    set(_FS_DEFAULT_DESCRIPTION 0)
+  endif()
+
   set(validWhatParts "ENABLED_FEATURES"
                      "DISABLED_FEATURES"
                      "PACKAGES_FOUND"
@@ -332,11 +346,24 @@ function(FEATURE_SUMMARY)
                                "${_fsPkgType}_PACKAGES_NOT_FOUND")
   endforeach()
 
+  set(title_ENABLED_FEATURES               "The following features have been enabled:")
+  set(title_DISABLED_FEATURES              "The following features have been disabled:")
+  set(title_PACKAGES_FOUND                 "The following packages have been found:")
+  set(title_PACKAGES_NOT_FOUND             "The following packages have not been found:")
+  foreach(_fsPkgType ${_fsPkgTypes})
+    set(title_${_fsPkgType}_PACKAGES_FOUND     "The following ${_fsPkgType} packages have been found:")
+    set(title_${_fsPkgType}_PACKAGES_NOT_FOUND "The following ${_fsPkgType} packages have not been found:")
+  endforeach()
+
   list(FIND validWhatParts "${_FS_WHAT}" indexInList)
   if(NOT "${indexInList}" STREQUAL "-1")
     _FS_GET_FEATURE_SUMMARY( ${_FS_WHAT} _featureSummary ${_FS_INCLUDE_QUIET_PACKAGES} )
     if(_featureSummary OR NOT _FS_QUIET_ON_EMPTY)
-      set(_fullText "${_FS_DESCRIPTION}${_featureSummary}\n")
+      if(_FS_DEFAULT_DESCRIPTION)
+        set(_fullText "${title_${_FS_WHAT}}\n${_featureSummary}\n")
+      else()
+        set(_fullText "${_FS_DESCRIPTION}${_featureSummary}\n")
+      endif()
     endif()
 
     if(_featureSummary)
@@ -375,15 +402,6 @@ function(FEATURE_SUMMARY)
       endforeach()
     endif()
 
-    set(title_ENABLED_FEATURES               "The following features have been enabled:")
-    set(title_DISABLED_FEATURES              "The following features have been disabled:")
-    set(title_PACKAGES_FOUND                 "The following packages have been found:")
-    set(title_PACKAGES_NOT_FOUND             "The following packages have not been found:")
-    foreach(_fsPkgType ${_fsPkgTypes})
-      set(title_${_fsPkgType}_PACKAGES_FOUND     "The following ${_fsPkgType} packages have been found:")
-      set(title_${_fsPkgType}_PACKAGES_NOT_FOUND "The following ${_fsPkgType} packages have not been found:")
-    endforeach()
-
     set(_fullText "${_FS_DESCRIPTION}")
     foreach(part ${allWhatParts})
       set(_tmp)
diff --git a/Tests/RunCMake/FeatureSummary/FeatureSummaryDefaultDescription-stdout.txt b/Tests/RunCMake/FeatureSummary/FeatureSummaryDefaultDescription-stdout.txt
new file mode 100644
index 0000000000..47bdee38e6
--- /dev/null
+++ b/Tests/RunCMake/FeatureSummary/FeatureSummaryDefaultDescription-stdout.txt
@@ -0,0 +1,46 @@
+-- The following RUNTIME packages have been found:
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- The following OPTIONAL packages have not been found:
+
+ \* Bar
+
+-- The following REQUIRED packages have not been found:
+
+ \* Baz
+
+--[ ]
+ \* Foo, The Foo package, <https://foo.example/>
+
+--[ ]
+ \* Bar
+
+--[ ]
+ \* Baz
+
+-- RUNTIME pkgs found
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- OPTIONAL pkgs not found
+
+ \* Bar
+
+-- REQUIRED pkgs not found
+
+ \* Baz
+
+-- The following RUNTIME packages have been found:
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- The following OPTIONAL packages have not been found:
+
+ \* Bar
+
+-- The following REQUIRED packages have not been found:
+
+ \* Baz
+
+-- Configuring done
diff --git a/Tests/RunCMake/FeatureSummary/FeatureSummaryDefaultDescription.cmake b/Tests/RunCMake/FeatureSummary/FeatureSummaryDefaultDescription.cmake
new file mode 100644
index 0000000000..536fe72c8c
--- /dev/null
+++ b/Tests/RunCMake/FeatureSummary/FeatureSummaryDefaultDescription.cmake
@@ -0,0 +1,82 @@
+include(FeatureSummary)
+
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR})
+
+find_package(Foo)
+find_package(Bar)
+find_package(Baz)
+
+set_package_properties(Foo PROPERTIES TYPE RUNTIME)
+set_package_properties(Bar PROPERTIES TYPE OPTIONAL)
+set_package_properties(Baz PROPERTIES TYPE REQUIRED)
+
+feature_summary(WHAT ALL)
+
+feature_summary(WHAT RUNTIME_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT RUNTIME_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT OPTIONAL_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT OPTIONAL_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT REQUIRED_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT REQUIRED_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+
+feature_summary(WHAT RUNTIME_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "RUNTIME pkgs found\n")
+feature_summary(WHAT RUNTIME_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "RUNTIME pkgs not found\n")
+feature_summary(WHAT OPTIONAL_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "OPTIONAL pkgs found\n")
+feature_summary(WHAT OPTIONAL_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "OPTIONAL pkgs not found\n")
+feature_summary(WHAT REQUIRED_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "REQUIRED pkgs found\n")
+feature_summary(WHAT REQUIRED_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "REQUIRED pkgs not found\n")
+
+feature_summary(WHAT RUNTIME_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT RUNTIME_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT OPTIONAL_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT OPTIONAL_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT REQUIRED_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT REQUIRED_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
diff --git a/Tests/RunCMake/FeatureSummary/RunCMakeTest.cmake b/Tests/RunCMake/FeatureSummary/RunCMakeTest.cmake
index 9caee4c0e6..8486487d7a 100644
--- a/Tests/RunCMake/FeatureSummary/RunCMakeTest.cmake
+++ b/Tests/RunCMake/FeatureSummary/RunCMakeTest.cmake
@@ -14,6 +14,7 @@ run_cmake(FeatureSummaryFatalOnMissingRequiredPackages)
 run_cmake(FeatureSummaryIncludeQuietPackages)
 run_cmake(FeatureSummaryQuietOnEmpty)
 run_cmake(FeatureSummaryMultipleDepends)
+run_cmake(FeatureSummaryDefaultDescription)
 run_cmake(FeatureSummaryCustomTypes)
 run_cmake(FeatureSummaryCustomBadDefault)
 run_cmake(FeatureSummaryCustomRequired)