Merge topic 'FindPackageLogVersion'

88e6447 Add macro ADD_FEATURE_INFO() and improve docs.
b353524 Improve wording of the documentation.
6fc88b2 Improve documentation.
3333878 Log the required package version and major improvement to FeatureSummary

2 files changed, 194 insertions, 29 deletions

diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake
index c4a97d5..594e2e7 100644
--- a/Modules/FeatureSummary.cmake
+++ b/Modules/FeatureSummary.cmake
@@ -1,23 +1,100 @@
 # - Macros for generating a summary of enabled/disabled features
 #
-# PRINT_ENABLED_FEATURES()
-#   Print a summary of all enabled features. By default all successfull
-#   FIND_PACKAGE() calls will appear here, except the ones which used the
-#   QUIET keyword. Additional features can be added by appending an entry
-#   to the global ENABLED_FEATURES property. If SET_FEATURE_INFO() is
-#   used for that feature, the output will be much more informative.
+# This module provides the macros feature_summary(), set_package_info() and
+# add_feature_info().
+# For compatiblity it also still provides set_feature_info(),
+# print_enabled_features() and print_disabled_features.
 #
-# PRINT_DISABLED_FEATURES()
-#   Same as PRINT_ENABLED_FEATURES(), but for disabled features. It can
-#   be extended the same way by adding to the global property 
-#   DISABLED_FEATURES.
+# These macros can be used to generate a summary of enabled and disabled
+# packages and/or feature for a build tree:
 #
-# SET_FEATURE_INFO(NAME DESCRIPTION [URL [COMMENT] ] )
-#    Use this macro to set up information about the named feature, which will
-#    then be displayed by PRINT_ENABLED/DISABLED_FEATURES().
-#    Example: SET_FEATURE_INFO(LibXml2 "XML processing library." 
-#    "http://xmlsoft.org/")
+#    -- Enabled features:
+#    LibXml2 (required version >= 2.4) , XML processing library. , <http://xmlsoft.org>
+#    PNG , A PNG image library. , <http://www.libpng.org/pub/png/>
+#    -- Disabled features:
+#    Lua51 , The Lua scripting language. , <http://www.lua.org>
+#    Foo , Foo provides cool stuff.
 #
+#
+#    FEATURE_SUMMARY( [FILENAME <file>]
+#                     [APPEND]
+#                     [VAR <variable_name>]
+#                     [DESCRIPTION "Found packages:"]
+#                     WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
+#                          | ENABLED_FEATURES | DISABLED_FEATURES]
+#                   )
+#
+# The FEATURE_SUMMARY() macro can be used to print information about enabled
+# or disabled features or packages of a project.
+# By default, only the names of the features/packages will be printed and their
+# required version when one was specified. Use SET_FEATURE_INFO() to add more
+# useful information, like e.g. a download URL for the respective package.
+#
+# The WHAT option is the only mandatory option. Here you specify what information
+# will be printed:
+#    ENABLED_FEATURES: the list of all features and packages which are enabled,
+#                      excluding the QUIET packages
+#    DISABLED_FEATURES: the list of all features and packages which are disabled,
+#                       excluding the QUIET packages
+#    PACKAGES_FOUND: the list of all packages which have been found
+#    PACKAGES_NOT_FOUND: the list of all packages which have not been found
+#    ALL: this will give all packages which have or have not been found
+#
+# If a FILENAME is given, the information is printed into this file. If APPEND
+# is used, it is appended to this file, otherwise the file is overwritten if
+# it already existed.
+# If the VAR option is used, the 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.
+#
+# Example 1, append everything to a file:
+#   feature_summary(WHAT ALL
+#                   FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
+#
+# Example 2, print the enabled features into the variable enabledFeaturesText:
+#   feature_summary(WHAT ENABLED_FEATURES
+#                   DESCRIPTION "Enabled Features:"
+#                   VAR enabledFeaturesText)
+#   message(STATUS "${enabledFeaturesText}")
+#
+#
+#    SET_PACKAGE_INFO(<name> <description> [<url> [<comment>] ] )
+# Use this macro to set up information about the named package, which can
+# then be displayed via FEATURE_SUMMARY().
+# This can be done either directly in the Find-module or in the project
+# which uses the module after the FIND_PACKAGE() call.
+# The features for which information can be set are added automatically by the
+# find_package() command.
+#
+# Example for setting the info for a package:
+#   find_package(LibXml2)
+#   set_package_info(LibXml2 "XML processing library." "http://xmlsoft.org/")
+#
+#
+#    ADD_FEATURE_INFO(<name> <enabled> <description>)
+# Use this macro to add information about a feature with the given <name>.
+# <enabled> contains whether this feature is enabled or not, <description>
+# is a text descibing the feature.
+# The information can be displayed using feature_summary() for ENABLED_FEATURES
+# and DISABLED_FEATURES respectively.
+#
+# Example for setting the info for a feature:
+#   option(WITH_FOO "Help for foo" ON)
+#   add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
+#
+#
+# The following macros are provided for compatibility with previous CMake versions:
+#
+#    PRINT_ENABLED_FEATURES()
+# Does the same as FEATURE_SUMMARY(WHAT ENABLED_FEATURES  DESCRIPTION "Enabled features:")
+#
+#    PRINT_DISABLED_FEATURES()
+# Does the same as FEATURE_SUMMARY(WHAT DISABLED_FEATURES  DESCRIPTION "Disabled features:")
+#
+#    SET_FEATURE_INFO(<name> <description> [<url> [<comment>] ] )
+# Does the same as SET_PACKAGE_INFO(<name> <description> <url> <comment> )
 
 #=============================================================================
 # Copyright 2007-2009 Kitware, Inc.
@@ -32,47 +109,121 @@
 # (To distribute this file outside of CMake, substitute the full
 #  License text for the above reference.)
 
-FUNCTION(SET_FEATURE_INFO _name _desc)
+INCLUDE(CMakeParseArguments)
+
+
+FUNCTION(ADD_FEATURE_INFO _name _enabled _desc)
+  IF (${_enabled})
+    SET_PROPERTY(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
+  ELSE ()
+    SET_PROPERTY(GLOBAL APPEND PROPERTY DISABLED_FEATURES "${_name}")
+  ENDIF ()
+
+  SET_PROPERTY(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
+ENDFUNCTION(SET_FEATURE_INFO)
+
+
+FUNCTION(SET_FEATURE_INFO)
+  SET_PACKAGE_INFO(${ARGN})
+ENDFUNCTION(SET_FEATURE_INFO)
+
+
+FUNCTION(SET_PACKAGE_INFO _name _desc)
   SET(_url "${ARGV2}")
   SET(_comment "${ARGV3}")
-  SET_PROPERTY(GLOBAL PROPERTY ${_name}_DESCRIPTION "${_desc}" )
+  SET_PROPERTY(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
   IF(_url MATCHES ".+")
-    SET_PROPERTY(GLOBAL PROPERTY ${_name}_URL "${_url}" )
+    SET_PROPERTY(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_url}" )
   ENDIF(_url MATCHES ".+")
   IF(_comment MATCHES ".+")
-    SET_PROPERTY(GLOBAL PROPERTY ${_name}_COMMENT "${_comment}" )
+    SET_PROPERTY(GLOBAL PROPERTY _CMAKE_${_name}_COMMENT "${_comment}" )
   ENDIF(_comment MATCHES ".+")
-ENDFUNCTION(SET_FEATURE_INFO)
+ENDFUNCTION(SET_PACKAGE_INFO)
 
 
-FUNCTION(_PRINT_FEATURES _property _text)
-  SET(_currentFeatureText "${_text}")
+FUNCTION(_FS_GET_FEATURE_SUMMARY _property _var)
+  SET(_currentFeatureText "")
   GET_PROPERTY(_EnabledFeatures  GLOBAL PROPERTY ${_property})
   FOREACH(_currentFeature ${_EnabledFeatures})
     SET(_currentFeatureText "${_currentFeatureText}\n${_currentFeature}")
-    GET_PROPERTY(_info  GLOBAL PROPERTY ${_currentFeature}_DESCRIPTION)
+    GET_PROPERTY(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_REQUIRED_VERSION)
+    IF(_info)
+      SET(_currentFeatureText "${_currentFeatureText} (required version ${_info})")
+    ENDIF(_info)
+    GET_PROPERTY(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_DESCRIPTION)
     IF(_info)
       SET(_currentFeatureText "${_currentFeatureText} , ${_info}")
     ENDIF(_info)
-    GET_PROPERTY(_info  GLOBAL PROPERTY ${_currentFeature}_URL)
+    GET_PROPERTY(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_URL)
     IF(_info)
       SET(_currentFeatureText "${_currentFeatureText} , <${_info}>")
     ENDIF(_info)
-    GET_PROPERTY(_info  GLOBAL PROPERTY ${_currentFeature}_COMMENT)
+    GET_PROPERTY(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_COMMENT)
     IF(_info)
       SET(_currentFeatureText "${_currentFeatureText} , ${_info}")
     ENDIF(_info)
   ENDFOREACH(_currentFeature)
-  MESSAGE(STATUS "${_currentFeatureText}\n")
-ENDFUNCTION(_PRINT_FEATURES)
+  SET(${_var} "${_currentFeatureText}" PARENT_SCOPE)
+ENDFUNCTION(_FS_GET_FEATURE_SUMMARY)
 
 
 FUNCTION(PRINT_ENABLED_FEATURES)
-   _PRINT_FEATURES( ENABLED_FEATURES "Enabled features:")
+  FEATURE_SUMMARY(WHAT ENABLED_FEATURES  DESCRIPTION "Enabled features:")
 ENDFUNCTION(PRINT_ENABLED_FEATURES)
 
 
 FUNCTION(PRINT_DISABLED_FEATURES)
-   _PRINT_FEATURES( DISABLED_FEATURES "Disabled features:")
+  FEATURE_SUMMARY(WHAT DISABLED_FEATURES  DESCRIPTION "Disabled features:")
 ENDFUNCTION(PRINT_DISABLED_FEATURES)
 
+
+
+FUNCTION(FEATURE_SUMMARY)
+# CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
+  SET(options APPEND)
+  SET(oneValueArgs FILENAME VAR DESCRIPTION WHAT)
+  SET(multiValueArgs ) # none
+
+  CMAKE_PARSE_ARGUMENTS(_FS "${options}" "${oneValueArgs}" "${multiValueArgs}"  ${_FIRST_ARG} ${ARGN})
+
+  IF(_FS_UNPARSED_ARGUMENTS)
+    MESSAGE(FATAL_ERROR "Unknown keywords given to FEATURE_SUMMARY(): \"${_FS_UNPARSED_ARGUMENTS}\"")
+  ENDIF(_FS_UNPARSED_ARGUMENTS)
+
+  IF(NOT _FS_WHAT)
+    MESSAGE(FATAL_ERROR "The call to FEATURE_SUMMAY() doesn't set the required WHAT argument.")
+  ENDIF(NOT _FS_WHAT)
+
+  IF(   "${_FS_WHAT}" STREQUAL "ENABLED_FEATURES"
+     OR "${_FS_WHAT}" STREQUAL "DISABLED_FEATURES"
+     OR "${_FS_WHAT}" STREQUAL "PACKAGES_FOUND"
+     OR "${_FS_WHAT}" STREQUAL "PACKAGES_NOT_FOUND")
+    _FS_GET_FEATURE_SUMMARY( ${_FS_WHAT} _featureSummary)
+  ELSEIF("${_FS_WHAT}" STREQUAL "ALL")
+    _FS_GET_FEATURE_SUMMARY( PACKAGES_FOUND _tmp1)
+    _FS_GET_FEATURE_SUMMARY( PACKAGES_NOT_FOUND _tmp2)
+    SET(_featureSummary "${_tmp1}${_tmp2}")
+  ELSE()
+    MESSAGE(FATAL_ERROR "The WHAT argument of FEATURE_SUMMARY() is set to ${_FS_WHAT}, which is not a valid value.")
+  ENDIF()
+
+  SET(_fullText "${_FS_DESCRIPTION}${_featureSummary}\n")
+
+  IF(_FS_FILENAME)
+    IF(_FS_APPEND)
+      FILE(WRITE  "${_FS_FILENAME}" "${_fullText}")
+    ELSE(_FS_APPEND)
+      FILE(APPEND "${_FS_FILENAME}" "${_fullText}")
+    ENDIF(_FS_APPEND)
+
+  ELSE(_FS_FILENAME)
+    IF(NOT _FS_VAR)
+      MESSAGE(STATUS "${_fullText}")
+    ENDIF(NOT _FS_VAR)
+  ENDIF(_FS_FILENAME)
+
+  IF(_FS_VAR)
+    SET(${_FS_VAR} "${_fullText}" PARENT_SCOPE)
+  ENDIF(_FS_VAR)
+
+ENDFUNCTION(FEATURE_SUMMARY)
diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index eb86014..5c05ecb 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -1083,6 +1083,20 @@ void cmFindPackageCommand::AppendSuccessInformation()
       }
     }
 
+  // set a global property to record the required version of this package
+  std::string versionInfoPropName = "_CMAKE_";
+  versionInfoPropName += this->Name;
+  versionInfoPropName += "_REQUIRED_VERSION";
+  std::string versionInfo;
+  if(!this->Version.empty())
+    {
+    versionInfo = this->VersionExact ? "==" : ">=";
+    versionInfo += " ";
+    versionInfo += this->Version;
+    }
+  this->Makefile->GetCMakeInstance()->SetProperty(versionInfoPropName.c_str(),
+                                                  versionInfo.c_str());
+
   // Restore original state of "_FIND_" variables we set.
   this->RestoreFindDefinitions();
 }