Modules/FeatureSummary.cmake

   1 # - Macros for generating a summary of enabled/disabled features
   2 #
   3 # This module provides the macros feature_summary(), set_package_properties() and
   4 # add_feature_info().
   5 # For compatibility it also still provides set_package_info(), set_feature_info(),
   6 # print_enabled_features() and print_disabled_features().
   7 #
   8 # These macros can be used to generate a summary of enabled and disabled
   9 # packages and/or feature for a build tree:
  10 #
  11 #    -- The following OPTIONAL packages have been found:
  12 #    LibXml2 (required version >= 2.4) , XML processing library. , <http://xmlsoft.org>
  13 #       * Enables HTML-import in MyWordProcessor
  14 #       * Enables odt-export in MyWordProcessor
  15 #    PNG , A PNG image library. , <http://www.libpng.org/pub/png/>
  16 #       * Enables saving screenshots
  17 #    -- The following OPTIONAL packages have not been found:
  18 #    Lua51 , The Lua scripting language. , <http://www.lua.org>
  19 #       * Enables macros in MyWordProcessor
  20 #    Foo , Foo provides cool stuff.
  21 #
  22 #
  23 #    FEATURE_SUMMARY( [FILENAME <file>]
  24 #                     [APPEND]
  25 #                     [VAR <variable_name>]
  26 #                     [INCLUDE_QUIET_PACKAGES]
  27 #                     [FATAL_ON_MISSING_REQUIRED_PACKAGES]
  28 #                     [DESCRIPTION "Found packages:"]
  29 #                     WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
  30 #                          | ENABLED_FEATURES | DISABLED_FEATURES]
  31 #                   )
  32 #
  33 # The FEATURE_SUMMARY() macro can be used to print information about enabled
  34 # or disabled packages or features of a project.
  35 # By default, only the names of the features/packages will be printed and their
  36 # required version when one was specified. Use SET_PACKAGE_PROPERTIES() to add more
  37 # useful information, like e.g. a download URL for the respective package or their
  38 # purpose in the project.
  39 #
  40 # The WHAT option is the only mandatory option. Here you specify what information
  41 # will be printed:
  42 #    ALL: print everything
  43 #    ENABLED_FEATURES: the list of all features which are enabled
  44 #    DISABLED_FEATURES: the list of all features which are disabled
  45 #    PACKAGES_FOUND: the list of all packages which have been found
  46 #    PACKAGES_NOT_FOUND: the list of all packages which have not been found
  47 #    OPTIONAL_PACKAGES_FOUND: only those packages which have been found which have the type OPTIONAL
  48 #    OPTIONAL_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type OPTIONAL
  49 #    RECOMMENDED_PACKAGES_FOUND: only those packages which have been found which have the type RECOMMENDED
  50 #    RECOMMENDED_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type RECOMMENDED
  51 #    REQUIRED_PACKAGES_FOUND: only those packages which have been found which have the type REQUIRED
  52 #    REQUIRED_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type REQUIRED
  53 #    RUNTIME_PACKAGES_FOUND: only those packages which have been found which have the type RUNTIME
  54 #    RUNTIME_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type RUNTIME
  55 #
  56 # If a FILENAME is given, the information is printed into this file. If APPEND
  57 # is used, it is appended to this file, otherwise the file is overwritten if
  58 # it already existed.
  59 # If the VAR option is used, the information is "printed" into the specified
  60 # variable.
  61 # If FILENAME is not used, the information is printed to the terminal.
  62 # Using the DESCRIPTION option a description or headline can be set which will
  63 # be printed above the actual content.
  64 # If INCLUDE_QUIET_PACKAGES is given, packages which have been searched with find_package(... QUIET) will
  65 # also be listed. By default they are skipped.
  66 # If FATAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a package which is marked as REQUIRED
  67 # has not been found.
  68 #
  69 # Example 1, append everything to a file:
  70 #   feature_summary(WHAT ALL
  71 #                   FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
  72 #
  73 # Example 2, print the enabled features into the variable enabledFeaturesText, including QUIET packages:
  74 #   feature_summary(WHAT ENABLED_FEATURES
  75 #                   INCLUDE_QUIET_PACKAGES
  76 #                   DESCRIPTION "Enabled Features:"
  77 #                   VAR enabledFeaturesText)
  78 #   message(STATUS "${enabledFeaturesText}")
  79 #
  80 #
  81 #    SET_PACKAGE_PROPERTIES(<name> PROPERTIES [ URL <url> ]
  82 #                                             [ DESCRIPTION <description> ]
  83 #                                             [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
  84 #                                             [ PURPOSE <purpose> ]
  85 #                          )
  86 #
  87 # Use this macro to set up information about the named package, which can
  88 # then be displayed via FEATURE_SUMMARY().
  89 # This can be done either directly in the Find-module or in the project
  90 # which uses the module after the find_package() call.
  91 # The features for which information can be set are added automatically by the
  92 # find_package() command.
  93 #
  94 # URL: this should be the homepage of the package, or something similar. Ideally this is set
  95 # already directly in the Find-module.
  96 #
  97 # DESCRIPTION: A short description what that package is, at most one sentence.
  98 # Ideally this is set already directly in the Find-module.
  99 #
 100 # TYPE: What type of dependency has the using project on that package. Default is OPTIONAL.
 101 # In this case it is a package which can be used by the project when available at buildtime,
 102 # but it also work without. RECOMMENDED is similar to OPTIONAL, i.e. the project will build
 103 # if the package is not present, but the functionality of the resulting binaries will be severly
 104 # limited. If a REQUIRED package is not available at buildtime, the project may not even build. This
 105 # can be combined with the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for feature_summary().
 106 # Last, a RUNTIME package is a package which is actually not used at all during the build, but
 107 # which is required for actually running the resulting binaries. So if such a package is missing,
 108 # the project can still be built, but it may not work later on. If set_package_properties() is called
 109 # multiple times for the same package with different TYPEs, the TYPE is only changed to higher
 110 # TYPEs ( RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED ), lower TYPEs are ignored.
 111 # The TYPE property is project-specific, so it cannot be set by the Find-module, but must be set in the project.
 112 #
 113 # PURPOSE: This describes which features this package enables in the project, i.e. it tells the user
 114 # what functionality he gets in the resulting binaries.
 115 # If set_package_properties() is called multiple times for a package, all PURPOSE properties are appended
 116 # to a list of purposes of the package in the project.
 117 # As the TYPE property, also the PURPOSE property
 118 # is project-specific, so it cannot be set by the Find-module, but must be set in the project.
 119 #
 120 #
 121 # Example for setting the info for a package:
 122 #   find_package(LibXml2)
 123 #   set_package_properties(LibXml2 PROPERTIES DESCRIPTION "A XML processing library."
 124 #                                             URL "http://xmlsoft.org/")
 125 #
 126 #   set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED
 127 #                                             PURPOSE "Enables HTML-import in MyWordProcessor")
 128 #   ...
 129 #   set_package_properties(LibXml2 PROPERTIES TYPE OPTIONAL
 130 #                                             PURPOSE "Enables odt-export in MyWordProcessor")
 131 #
 132 #   find_package(DBUS)
 133 #   set_package_properties(DBUS PROPERTIES TYPE RUNTIME
 134 #                                             PURPOSE "Necessary to disable the screensaver during a presentation" )
 135 #
 136 #    ADD_FEATURE_INFO(<name> <enabled> <description>)
 137 # Use this macro to add information about a feature with the given <name>.
 138 # <enabled> contains whether this feature is enabled or not, <description>
 139 # is a text describing the feature.
 140 # The information can be displayed using feature_summary() for ENABLED_FEATURES
 141 # and DISABLED_FEATURES respectively.
 142 #
 143 # Example for setting the info for a feature:
 144 #   option(WITH_FOO "Help for foo" ON)
 145 #   add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
 146 #
 147 #
 148 # The following macros are provided for compatibility with previous CMake versions:
 149 #
 150 #    SET_PACKAGE_INFO(<name> <description> [<url> [<purpose>] ] )
 151 # Use this macro to set up information about the named package, which can
 152 # then be displayed via FEATURE_SUMMARY().
 153 # This can be done either directly in the Find-module or in the project
 154 # which uses the module after the find_package() call.
 155 # The features for which information can be set are added automatically by the
 156 # find_package() command.
 157 #
 158 #    PRINT_ENABLED_FEATURES()
 159 # Does the same as FEATURE_SUMMARY(WHAT ENABLED_FEATURES  DESCRIPTION "Enabled features:")
 160 #
 161 #    PRINT_DISABLED_FEATURES()
 162 # Does the same as FEATURE_SUMMARY(WHAT DISABLED_FEATURES  DESCRIPTION "Disabled features:")
 163 #
 164 #    SET_FEATURE_INFO(<name> <description> [<url>] )
 165 # Does the same as SET_PACKAGE_INFO(<name> <description> <url> )
 166
 167 #=============================================================================
 168 # Copyright 2007-2009 Kitware, Inc.
 169 #
 170 # Distributed under the OSI-approved BSD License (the "License");
 171 # see accompanying file Copyright.txt for details.
 172 #
 173 # This software is distributed WITHOUT ANY WARRANTY; without even the
 174 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 175 # See the License for more information.
 176 #=============================================================================
 177 # (To distribute this file outside of CMake, substitute the full
 178 #  License text for the above reference.)
 179
 180 include(CMakeParseArguments)
 181
 182
 183 function(ADD_FEATURE_INFO _name _enabled _desc)
 184   if (${_enabled})
 185     set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
 186   else ()
 187     set_property(GLOBAL APPEND PROPERTY DISABLED_FEATURES "${_name}")
 188   endif ()
 189
 190   set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
 191 endfunction()
 192
 193
 194
 195 function(SET_PACKAGE_PROPERTIES _name _props)
 196   if(NOT "${_props}" STREQUAL "PROPERTIES")
 197     message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
 198   endif()
 199
 200   set(options ) # none
 201   set(oneValueArgs DESCRIPTION URL TYPE PURPOSE )
 202   set(multiValueArgs ) # none
 203
 204   CMAKE_PARSE_ARGUMENTS(_SPP "${options}" "${oneValueArgs}" "${multiValueArgs}"  ${ARGN})
 205
 206   if(_SPP_UNPARSED_ARGUMENTS)
 207     message(FATAL_ERROR "Unknown keywords given to SET_PACKAGE_PROPERTIES(): \"${_SPP_UNPARSED_ARGUMENTS}\"")
 208   endif()
 209
 210   if(_SPP_DESCRIPTION)
 211     get_property(_info  GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION)
 212     if(_info AND NOT "${_info}" STREQUAL "${_SPP_DESCRIPTION}")
 213       message(STATUS "Warning: Property DESCRIPTION for package ${_name} already set to \"${_info}\", overriding it with \"${_SPP_DESCRIPTION}\"")
 214     endif()
 215
 216     set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_SPP_DESCRIPTION}" )
 217   endif()
 218
 219
 220   if(_SPP_URL)
 221     get_property(_info  GLOBAL PROPERTY _CMAKE_${_name}_URL)
 222     if(_info AND NOT "${_info}" STREQUAL "${_SPP_URL}")
 223       message(STATUS "Warning: Property URL already set to \"${_info}\", overriding it with \"${_SPP_URL}\"")
 224     endif()
 225
 226     set_property(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_SPP_URL}" )
 227   endif()
 228
 229
 230   # handle the PURPOSE: use APPEND, since there can be multiple purposes for one package inside a project
 231   if(_SPP_PURPOSE)
 232     set_property(GLOBAL APPEND PROPERTY _CMAKE_${_name}_PURPOSE "${_SPP_PURPOSE}" )
 233   endif()
 234
 235   # handle the TYPE
 236   if(NOT _SPP_TYPE)
 237     set(_SPP_TYPE OPTIONAL)
 238   endif()
 239
 240   # List the supported types, according to their priority
 241   set(validTypes "RUNTIME" "OPTIONAL" "RECOMMENDED" "REQUIRED" )
 242   list(FIND validTypes ${_SPP_TYPE} _typeIndexInList)
 243   if("${_typeIndexInList}" STREQUAL "-1" )
 244     message(FATAL_ERROR "Bad package property type ${_SPP_TYPE} used in SET_PACKAGE_PROPERTIES(). "
 245                         "Valid types are OPTIONAL, RECOMMENDED, REQUIRED and RUNTIME." )
 246   endif()
 247
 248   get_property(_previousType  GLOBAL PROPERTY _CMAKE_${_name}_TYPE)
 249   list(FIND validTypes "${_previousType}" _prevTypeIndexInList)
 250
 251   # make sure a previously set TYPE is not overridden with a lower new TYPE:
 252   if("${_typeIndexInList}" GREATER "${_prevTypeIndexInList}")
 253     set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" )
 254   endif()
 255
 256 endfunction()
 257
 258
 259
 260 function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
 261
 262   set(_type "ANY")
 263   if("${_property}" MATCHES "REQUIRED_")
 264     set(_type "REQUIRED")
 265   elseif("${_property}" MATCHES "RECOMMENDED_")
 266     set(_type "RECOMMENDED")
 267   elseif("${_property}" MATCHES "RUNTIME_")
 268     set(_type "RUNTIME")
 269   elseif("${_property}" MATCHES "OPTIONAL_")
 270     set(_type "OPTIONAL")
 271   endif()
 272
 273   if("${_property}" MATCHES "PACKAGES_FOUND")
 274     set(_property "PACKAGES_FOUND")
 275   elseif("${_property}" MATCHES "PACKAGES_NOT_FOUND")
 276     set(_property "PACKAGES_NOT_FOUND")
 277   endif()
 278
 279
 280   set(_currentFeatureText "")
 281   get_property(_EnabledFeatures  GLOBAL PROPERTY ${_property})
 282
 283   foreach(_currentFeature ${_EnabledFeatures})
 284
 285     # does this package belong to the type we currently want to list ?
 286     get_property(_currentType  GLOBAL PROPERTY _CMAKE_${_currentFeature}_TYPE)
 287     if(NOT _currentType)
 288       set(_currentType OPTIONAL)
 289     endif()
 290
 291     if("${_type}" STREQUAL ANY  OR  "${_type}" STREQUAL "${_currentType}")
 292
 293       # check whether the current feature/package should be in the output depending on whether it was QUIET or not
 294       set(includeThisOne TRUE)
 295       # skip QUIET packages, except if they are REQUIRED or INCLUDE_QUIET_PACKAGES has been set
 296       if((NOT "${_currentType}" STREQUAL "REQUIRED") AND NOT _includeQuiet)
 297         get_property(_isQuiet  GLOBAL PROPERTY _CMAKE_${_currentFeature}_QUIET)
 298         if(_isQuiet)
 299           set(includeThisOne FALSE)
 300         endif()
 301       endif()
 302
 303       if(includeThisOne)
 304
 305         set(_currentFeatureText "${_currentFeatureText}\n * ${_currentFeature}")
 306         get_property(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_REQUIRED_VERSION)
 307         if(_info)
 308           set(_currentFeatureText "${_currentFeatureText} (required version ${_info})")
 309         endif()
 310         get_property(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_DESCRIPTION)
 311         if(_info)
 312           set(_currentFeatureText "${_currentFeatureText} , ${_info}")
 313         endif()
 314         get_property(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_URL)
 315         if(_info)
 316           set(_currentFeatureText "${_currentFeatureText} , <${_info}>")
 317         endif()
 318
 319         get_property(_info  GLOBAL PROPERTY _CMAKE_${_currentFeature}_PURPOSE)
 320         foreach(_purpose ${_info})
 321           set(_currentFeatureText "${_currentFeatureText}\n   ${_purpose}")
 322         endforeach()
 323
 324       endif()
 325
 326     endif()
 327
 328   endforeach()
 329   set(${_var} "${_currentFeatureText}" PARENT_SCOPE)
 330 endfunction()
 331
 332
 333
 334 function(FEATURE_SUMMARY)
 335 # CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
 336   set(options APPEND INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)
 337   set(oneValueArgs FILENAME VAR DESCRIPTION WHAT)
 338   set(multiValueArgs ) # none
 339
 340   CMAKE_PARSE_ARGUMENTS(_FS "${options}" "${oneValueArgs}" "${multiValueArgs}"  ${_FIRST_ARG} ${ARGN})
 341
 342   if(_FS_UNPARSED_ARGUMENTS)
 343     message(FATAL_ERROR "Unknown keywords given to FEATURE_SUMMARY(): \"${_FS_UNPARSED_ARGUMENTS}\"")
 344   endif()
 345
 346   if(NOT _FS_WHAT)
 347     message(FATAL_ERROR "The call to FEATURE_SUMMARY() doesn't set the required WHAT argument.")
 348   endif()
 349
 350   set(validWhatParts "ENABLED_FEATURES"
 351                      "DISABLED_FEATURES"
 352                      "PACKAGES_FOUND"
 353                      "PACKAGES_NOT_FOUND"
 354                      "OPTIONAL_PACKAGES_FOUND"
 355                      "OPTIONAL_PACKAGES_NOT_FOUND"
 356                      "RECOMMENDED_PACKAGES_FOUND"
 357                      "RECOMMENDED_PACKAGES_NOT_FOUND"
 358                      "REQUIRED_PACKAGES_FOUND"
 359                      "REQUIRED_PACKAGES_NOT_FOUND"
 360                      "RUNTIME_PACKAGES_FOUND"
 361                      "RUNTIME_PACKAGES_NOT_FOUND")
 362
 363   list(FIND validWhatParts "${_FS_WHAT}" indexInList)
 364   if(NOT "${indexInList}" STREQUAL "-1")
 365     _FS_GET_FEATURE_SUMMARY( ${_FS_WHAT} _featureSummary ${_FS_INCLUDE_QUIET_PACKAGES} )
 366     set(_fullText "${_FS_DESCRIPTION}${_featureSummary}\n")
 367     if (("${_FS_WHAT}" STREQUAL "REQUIRED_PACKAGES_NOT_FOUND") AND _featureSummary)
 368       set(requiredPackagesNotFound TRUE)
 369     endif()
 370
 371   elseif("${_FS_WHAT}" STREQUAL "ALL")
 372
 373     set(allWhatParts "ENABLED_FEATURES"
 374                      "RUNTIME_PACKAGES_FOUND"
 375                      "OPTIONAL_PACKAGES_FOUND"
 376                      "RECOMMENDED_PACKAGES_FOUND"
 377                      "REQUIRED_PACKAGES_FOUND"
 378
 379                      "DISABLED_FEATURES"
 380                      "RUNTIME_PACKAGES_NOT_FOUND"
 381                      "OPTIONAL_PACKAGES_NOT_FOUND"
 382                      "RECOMMENDED_PACKAGES_NOT_FOUND"
 383                      "REQUIRED_PACKAGES_NOT_FOUND"
 384        )
 385
 386     set(title_ENABLED_FEATURES               "The following features have been enabled:")
 387     set(title_DISABLED_FEATURES              "The following features have been disabled:")
 388     set(title_OPTIONAL_PACKAGES_FOUND        "The following OPTIONAL packages have been found:")
 389     set(title_OPTIONAL_PACKAGES_NOT_FOUND    "The following OPTIONAL packages have not been found:")
 390     set(title_RECOMMENDED_PACKAGES_FOUND     "The following RECOMMENDED packages have been found:")
 391     set(title_RECOMMENDED_PACKAGES_NOT_FOUND "The following RECOMMENDED packages have not been found:")
 392     set(title_REQUIRED_PACKAGES_FOUND        "The following REQUIRED packages have been found:")
 393     set(title_REQUIRED_PACKAGES_NOT_FOUND    "The following REQUIRED packages have not been found:")
 394     set(title_RUNTIME_PACKAGES_FOUND         "The following RUNTIME packages have been found:")
 395     set(title_RUNTIME_PACKAGES_NOT_FOUND     "The following RUNTIME packages have not been found:")
 396
 397     set(_fullText "${_FS_DESCRIPTION}")
 398     foreach(part ${allWhatParts})
 399       set(_tmp)
 400       _FS_GET_FEATURE_SUMMARY( ${part} _tmp ${_FS_INCLUDE_QUIET_PACKAGES})
 401       if(_tmp)
 402         set(_fullText "${_fullText}\n-- ${title_${part}}\n${_tmp}\n")
 403         if("${part}" STREQUAL "REQUIRED_PACKAGES_NOT_FOUND")
 404           set(requiredPackagesNotFound TRUE)
 405         endif()
 406       endif()
 407     endforeach()
 408   else()
 409     message(FATAL_ERROR "The WHAT argument of FEATURE_SUMMARY() is set to ${_FS_WHAT}, which is not a valid value.")
 410   endif()
 411
 412   if(_FS_FILENAME)
 413     if(_FS_APPEND)
 414       file(APPEND "${_FS_FILENAME}" "${_fullText}")
 415     else()
 416       file(WRITE  "${_FS_FILENAME}" "${_fullText}")
 417     endif()
 418
 419   else()
 420     if(NOT _FS_VAR)
 421       message(STATUS "${_fullText}")
 422     endif()
 423   endif()
 424
 425   if(_FS_VAR)
 426     set(${_FS_VAR} "${_fullText}" PARENT_SCOPE)
 427   endif()
 428
 429   if(requiredPackagesNotFound  AND  _FS_FATAL_ON_MISSING_REQUIRED_PACKAGES)
 430     message(FATAL_ERROR "feature_summary() Error: REQUIRED package(s) are missing, aborting CMake run.")
 431   endif()
 432
 433 endfunction()
 434
 435
 436 # The stuff below is only kept for compatibility
 437
 438 function(SET_PACKAGE_INFO _name _desc)
 439   set(_url "${ARGV2}")
 440   set(_purpose "${ARGV3}")
 441   set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
 442   if(_url MATCHES ".+")
 443     set_property(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_url}" )
 444   endif()
 445   if(_purpose MATCHES ".+")
 446     set_property(GLOBAL APPEND PROPERTY _CMAKE_${_name}_PURPOSE "${_purpose}" )
 447   endif()
 448 endfunction()
 449
 450
 451
 452 function(SET_FEATURE_INFO)
 453   SET_PACKAGE_INFO(${ARGN})
 454 endfunction()
 455
 456
 457
 458 function(PRINT_ENABLED_FEATURES)
 459   FEATURE_SUMMARY(WHAT ENABLED_FEATURES  DESCRIPTION "Enabled features:")
 460 endfunction()
 461
 462
 463
 464 function(PRINT_DISABLED_FEATURES)
 465   FEATURE_SUMMARY(WHAT DISABLED_FEATURES  DESCRIPTION "Disabled features:")
 466 endfunction()