Merge topic 'FeatureSummary_description'

28e87033 FeatureSummary: Update release notes
6f62c66b FeatureSummary: Add FeatureSummary_<TYPE>_DESCRIPTION global properties
f9bc8cfe FeatureSummary: Add DEFAULT_DESCRIPTION option to feature_summary

Help/release/dev/FeatureSummary_description.rst

@@ -0,0 +1,11 @@
+FeatureSummary_description
+--------------------------
+
+* The :command:`feature_summary` command in the :module:`FeatureSummary` module
+  accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default
+  title for the selected package type.
+
+* The global property :variable:`FeatureSummary_<TYPE>_DESCRIPTION` can be
+  defined for each ``<TYPE>`` to replace the type name with the specified string
+  whenever the package type is used in an output string by the
+  :module:`FeatureSummary` module.

Modules/FeatureSummary.cmake

@@ -63,6 +63,16 @@ is set for all the packages.
 
 The default value for this global property is ``OPTIONAL``.
 
+
+.. variable:: FeatureSummary_<TYPE>_DESCRIPTION
+
+The global property :variable:`FeatureSummary_<TYPE>_DESCRIPTION` can be defined
+for each type to replace the type name with the specified string whenever the
+package type is used in an output string.
+
+If not set, the string "``<TYPE>`` packages" is used.
+
+
 #]=======================================================================]
 
 get_property(_fsPkgTypeIsSet GLOBAL PROPERTY FeatureSummary_PKG_TYPES SET)
@@ -196,7 +206,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 +257,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 +319,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 +339,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 +356,29 @@ 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(_fsPkgTypeDescription "${_fsPkgType} packages")
+    get_property(_fsPkgTypeDescriptionIsSet GLOBAL PROPERTY FeatureSummary_${_fsPkgType}_DESCRIPTION SET)
+    if(_fsPkgTypeDescriptionIsSet)
+      get_property(_fsPkgTypeDescription GLOBAL PROPERTY FeatureSummary_${_fsPkgType}_DESCRIPTION )
+    endif()
+    set(title_${_fsPkgType}_PACKAGES_FOUND     "The following ${_fsPkgTypeDescription} have been found:")
+    set(title_${_fsPkgType}_PACKAGES_NOT_FOUND "The following ${_fsPkgTypeDescription} 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 +417,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)

Tests/RunCMake/FeatureSummary/FeatureSummaryCustomDescription-stdout.txt

@@ -0,0 +1,91 @@
+-- The following TYPE1 packages have been found:
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- The following TYPE2 packages have not been found:
+
+ \* Bar
+
+-- The following TYPE3 packages have not been found:
+
+ \* Baz
+
+--[ ]
+ \* Foo, The Foo package, <https://foo.example/>
+
+--[ ]
+ \* Bar
+
+--[ ]
+ \* Baz
+
+-- TYPE1 pkgs found
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- TYPE2 pkgs not found
+
+ \* Bar
+
+-- TYPE3 pkgs not found
+
+ \* Baz
+
+-- The following TYPE1 packages have been found:
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- The following TYPE2 packages have not been found:
+
+ \* Bar
+
+-- The following TYPE3 packages have not been found:
+
+ \* Baz
+
+-- The following first type packages have been found:
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- The following second type packages have not been found:
+
+ \* Bar
+
+-- The following third type packages have not been found:
+
+ \* Baz
+
+--[ ]
+ \* Foo, The Foo package, <https://foo.example/>
+
+--[ ]
+ \* Bar
+
+--[ ]
+ \* Baz
+
+-- TYPE1 pkgs found
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- TYPE2 pkgs not found
+
+ \* Bar
+
+-- TYPE3 pkgs not found
+
+ \* Baz
+
+-- The following first type packages have been found:
+
+ \* Foo, The Foo package, <https://foo.example/>
+
+-- The following second type packages have not been found:
+
+ \* Bar
+
+-- The following third type packages have not been found:
+
+ \* Baz
+
+-- Configuring done

Tests/RunCMake/FeatureSummary/FeatureSummaryCustomDescription.cmake

@@ -0,0 +1,158 @@
+include(FeatureSummary)
+set_property(GLOBAL PROPERTY FeatureSummary_PKG_TYPES TYPE1 TYPE2 TYPE3)
+
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR})
+
+find_package(Foo)
+find_package(Bar)
+find_package(Baz)
+
+set_package_properties(Foo PROPERTIES TYPE TYPE1)
+set_package_properties(Bar PROPERTIES TYPE TYPE2)
+set_package_properties(Baz PROPERTIES TYPE TYPE3)
+
+feature_summary(WHAT ALL)
+
+feature_summary(WHAT TYPE1_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE1_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE2_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE2_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE3_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE3_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+
+feature_summary(WHAT TYPE1_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE1 pkgs found\n")
+feature_summary(WHAT TYPE1_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE1 pkgs not found\n")
+feature_summary(WHAT TYPE2_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE2 pkgs found\n")
+feature_summary(WHAT TYPE2_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE2 pkgs not found\n")
+feature_summary(WHAT TYPE3_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE3 pkgs found\n")
+feature_summary(WHAT TYPE3_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE3 pkgs not found\n")
+
+feature_summary(WHAT TYPE1_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE1_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE2_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE2_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE3_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE3_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+
+set_property(GLOBAL PROPERTY FeatureSummary_TYPE1_DESCRIPTION "first type packages")
+set_property(GLOBAL PROPERTY FeatureSummary_TYPE2_DESCRIPTION "second type packages")
+set_property(GLOBAL PROPERTY FeatureSummary_TYPE3_DESCRIPTION "third type packages")
+
+feature_summary(WHAT ALL)
+
+feature_summary(WHAT TYPE1_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE1_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE2_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE2_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE3_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+feature_summary(WHAT TYPE3_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY)
+
+feature_summary(WHAT TYPE1_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE1 pkgs found\n")
+feature_summary(WHAT TYPE1_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE1 pkgs not found\n")
+feature_summary(WHAT TYPE2_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE2 pkgs found\n")
+feature_summary(WHAT TYPE2_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE2 pkgs not found\n")
+feature_summary(WHAT TYPE3_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE3 pkgs found\n")
+feature_summary(WHAT TYPE3_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DESCRIPTION "TYPE3 pkgs not found\n")
+
+feature_summary(WHAT TYPE1_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE1_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE2_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE2_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE3_PACKAGES_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)
+feature_summary(WHAT TYPE3_PACKAGES_NOT_FOUND
+                INCLUDE_QUIET_PACKAGES
+                QUIET_ON_EMPTY
+                DEFAULT_DESCRIPTION)

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

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)

Tests/RunCMake/FeatureSummary/RunCMakeTest.cmake

@@ -14,8 +14,10 @@ run_cmake(FeatureSummaryFatalOnMissingRequiredPackages)
 run_cmake(FeatureSummaryIncludeQuietPackages)
 run_cmake(FeatureSummaryQuietOnEmpty)
 run_cmake(FeatureSummaryMultipleDepends)
+run_cmake(FeatureSummaryDefaultDescription)
 run_cmake(FeatureSummaryCustomTypes)
 run_cmake(FeatureSummaryCustomBadDefault)
 run_cmake(FeatureSummaryCustomRequired)
 run_cmake(FeatureSummaryCustomRequiredListA)
 run_cmake(FeatureSummaryCustomRequiredListB)
+run_cmake(FeatureSummaryCustomDescription)