diff options
Diffstat (limited to 'Modules')
| -rw-r--r-- | Modules/FeatureSummary.cmake | 531 |
1 files changed, 266 insertions, 265 deletions
diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake index 3e7ecfd..9afdcd9 100644 --- a/Modules/FeatureSummary.cmake +++ b/Modules/FeatureSummary.cmake @@ -1,268 +1,269 @@ -#.rst: -# FeatureSummary -# -------------- -# -# Macros for generating a summary of enabled/disabled features -# -# -# -# This module provides the macros feature_summary(), -# set_package_properties() and add_feature_info(). For compatibility it -# also still provides set_package_info(), set_feature_info(), -# print_enabled_features() and print_disabled_features(). -# -# These macros can be used to generate a summary of enabled and disabled -# packages and/or feature for a build tree: -# -# :: -# -# -- The following OPTIONAL packages have been found: -# LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org> -# * Enables HTML-import in MyWordProcessor -# * Enables odt-export in MyWordProcessor -# PNG , A PNG image library. , <http://www.libpng.org/pub/png/> -# * Enables saving screenshots -# -- The following OPTIONAL packages have not been found: -# Lua51 , The Lua scripting language. , <http://www.lua.org> -# * Enables macros in MyWordProcessor -# Foo , Foo provides cool stuff. -# -# -# -# -# -# :: -# -# FEATURE_SUMMARY( [FILENAME <file>] -# [APPEND] -# [VAR <variable_name>] -# [INCLUDE_QUIET_PACKAGES] -# [FATAL_ON_MISSING_REQUIRED_PACKAGES] -# [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 packages or features 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_PACKAGE_PROPERTIES() -# to add more useful information, like e.g. a download URL for the -# respective package or their purpose in the project. -# -# The WHAT option is the only mandatory option. Here you specify what -# information will be printed: -# -# ``ALL`` -# print everything -# ``ENABLED_FEATURES`` -# the list of all features which are enabled -# ``DISABLED_FEATURES`` -# the list of all features which are disabled -# ``PACKAGES_FOUND`` -# the list of all packages which have been found -# ``PACKAGES_NOT_FOUND`` -# the list of all packages which have not been found -# ``OPTIONAL_PACKAGES_FOUND`` -# only those packages which have been found which have the type OPTIONAL -# ``OPTIONAL_PACKAGES_NOT_FOUND`` -# only those packages which have not been found which have the type OPTIONAL -# ``RECOMMENDED_PACKAGES_FOUND`` -# only those packages which have been found which have the type RECOMMENDED -# ``RECOMMENDED_PACKAGES_NOT_FOUND`` -# only those packages which have not been found which have the type RECOMMENDED -# ``REQUIRED_PACKAGES_FOUND`` -# only those packages which have been found which have the type REQUIRED -# ``REQUIRED_PACKAGES_NOT_FOUND`` -# only those packages which have not been found which have the type REQUIRED -# ``RUNTIME_PACKAGES_FOUND`` -# only those packages which have been found which have the type RUNTIME -# ``RUNTIME_PACKAGES_NOT_FOUND`` -# only those packages which have not been found which have the type RUNTIME -# -# With the exception of the ``ALL`` value, these values can be combined -# in order to customize the output. For example: -# -# :: -# -# feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES) -# -# -# -# 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. 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 -# package which is marked as REQUIRED has not been found. -# -# 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, including QUIET packages: -# -# :: -# -# feature_summary(WHAT ENABLED_FEATURES -# INCLUDE_QUIET_PACKAGES -# DESCRIPTION "Enabled Features:" -# VAR enabledFeaturesText) -# message(STATUS "${enabledFeaturesText}") -# -# -# -# -# -# :: -# -# SET_PACKAGE_PROPERTIES(<name> PROPERTIES -# [ URL <url> ] -# [ DESCRIPTION <description> ] -# [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ] -# [ PURPOSE <purpose> ] -# ) -# -# -# -# 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. -# -# URL: this should be the homepage of the package, or something similar. -# Ideally this is set already directly in the Find-module. -# -# DESCRIPTION: A short description what that package is, at most one -# sentence. Ideally this is set already directly in the Find-module. -# -# TYPE: What type of dependency has the using project on that package. -# Default is OPTIONAL. In this case it is a package which can be used -# by the project when available at buildtime, but it also work without. -# RECOMMENDED is similar to OPTIONAL, i.e. the project will build if -# the package is not present, but the functionality of the resulting -# binaries will be severly limited. If a REQUIRED package is not -# available at buildtime, the project may not even build. This can be -# combined with the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for -# feature_summary(). Last, a RUNTIME package is a package which is -# actually not used at all during the build, but which is required for -# actually running the resulting binaries. So if such a package is -# missing, the project can still be built, but it may not work later on. -# If set_package_properties() is called multiple times for the same -# package with different TYPEs, the TYPE is only changed to higher TYPEs -# ( RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED ), lower TYPEs are -# ignored. The TYPE property is project-specific, so it cannot be set -# by the Find-module, but must be set in the project. -# -# PURPOSE: This describes which features this package enables in the -# project, i.e. it tells the user what functionality he gets in the -# resulting binaries. If set_package_properties() is called multiple -# times for a package, all PURPOSE properties are appended to a list of -# purposes of the package in the project. As the TYPE property, also -# the PURPOSE property is project-specific, so it cannot be set by the -# Find-module, but must be set in the project. -# -# -# -# Example for setting the info for a package: -# -# :: -# -# find_package(LibXml2) -# set_package_properties(LibXml2 PROPERTIES -# DESCRIPTION "A XML processing library." -# URL "http://xmlsoft.org/") -# -# -# -# :: -# -# set_package_properties(LibXml2 PROPERTIES -# TYPE RECOMMENDED -# PURPOSE "Enables HTML-import in MyWordProcessor") -# ... -# set_package_properties(LibXml2 PROPERTIES -# TYPE OPTIONAL -# PURPOSE "Enables odt-export in MyWordProcessor") -# -# -# -# :: -# -# find_package(DBUS) -# set_package_properties(DBUS PROPERTIES -# TYPE RUNTIME -# PURPOSE "Necessary to disable the screensaver during a presentation" ) -# -# -# -# :: -# -# 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 describing 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: -# -# :: -# -# SET_PACKAGE_INFO(<name> <description> [<url> [<purpose>] ] ) -# -# 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. -# -# :: -# -# 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>] ) -# -# Does the same as SET_PACKAGE_INFO(<name> <description> <url> ) +#[=======================================================================[.rst: +FeatureSummary +-------------- + +Macros for generating a summary of enabled/disabled features + + + +This module provides the macros feature_summary(), +set_package_properties() and add_feature_info(). For compatibility it +also still provides set_package_info(), set_feature_info(), +print_enabled_features() and print_disabled_features(). + +These macros can be used to generate a summary of enabled and disabled +packages and/or feature for a build tree: + +:: + + -- The following OPTIONAL packages have been found: + LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org> + * Enables HTML-import in MyWordProcessor + * Enables odt-export in MyWordProcessor + PNG , A PNG image library. , <http://www.libpng.org/pub/png/> + * Enables saving screenshots + -- The following OPTIONAL packages have not been found: + Lua51 , The Lua scripting language. , <http://www.lua.org> + * Enables macros in MyWordProcessor + Foo , Foo provides cool stuff. + + + + + +:: + + FEATURE_SUMMARY( [FILENAME <file>] + [APPEND] + [VAR <variable_name>] + [INCLUDE_QUIET_PACKAGES] + [FATAL_ON_MISSING_REQUIRED_PACKAGES] + [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 packages or features 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_PACKAGE_PROPERTIES() +to add more useful information, like e.g. a download URL for the +respective package or their purpose in the project. + +The WHAT option is the only mandatory option. Here you specify what +information will be printed: + +``ALL`` + print everything +``ENABLED_FEATURES`` + the list of all features which are enabled +``DISABLED_FEATURES`` + the list of all features which are disabled +``PACKAGES_FOUND`` + the list of all packages which have been found +``PACKAGES_NOT_FOUND`` + the list of all packages which have not been found +``OPTIONAL_PACKAGES_FOUND`` + only those packages which have been found which have the type OPTIONAL +``OPTIONAL_PACKAGES_NOT_FOUND`` + only those packages which have not been found which have the type OPTIONAL +``RECOMMENDED_PACKAGES_FOUND`` + only those packages which have been found which have the type RECOMMENDED +``RECOMMENDED_PACKAGES_NOT_FOUND`` + only those packages which have not been found which have the type RECOMMENDED +``REQUIRED_PACKAGES_FOUND`` + only those packages which have been found which have the type REQUIRED +``REQUIRED_PACKAGES_NOT_FOUND`` + only those packages which have not been found which have the type REQUIRED +``RUNTIME_PACKAGES_FOUND`` + only those packages which have been found which have the type RUNTIME +``RUNTIME_PACKAGES_NOT_FOUND`` + only those packages which have not been found which have the type RUNTIME + +With the exception of the ``ALL`` value, these values can be combined +in order to customize the output. For example: + +:: + + feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES) + + + +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. 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 +package which is marked as REQUIRED has not been found. + +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, including QUIET packages: + +:: + + feature_summary(WHAT ENABLED_FEATURES + INCLUDE_QUIET_PACKAGES + DESCRIPTION "Enabled Features:" + VAR enabledFeaturesText) + message(STATUS "${enabledFeaturesText}") + + + + + +:: + + SET_PACKAGE_PROPERTIES(<name> PROPERTIES + [ URL <url> ] + [ DESCRIPTION <description> ] + [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ] + [ PURPOSE <purpose> ] + ) + + + +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. + +URL: this should be the homepage of the package, or something similar. +Ideally this is set already directly in the Find-module. + +DESCRIPTION: A short description what that package is, at most one +sentence. Ideally this is set already directly in the Find-module. + +TYPE: What type of dependency has the using project on that package. +Default is OPTIONAL. In this case it is a package which can be used +by the project when available at buildtime, but it also work without. +RECOMMENDED is similar to OPTIONAL, i.e. the project will build if +the package is not present, but the functionality of the resulting +binaries will be severly limited. If a REQUIRED package is not +available at buildtime, the project may not even build. This can be +combined with the FATAL_ON_MISSING_REQUIRED_PACKAGES argument for +feature_summary(). Last, a RUNTIME package is a package which is +actually not used at all during the build, but which is required for +actually running the resulting binaries. So if such a package is +missing, the project can still be built, but it may not work later on. +If set_package_properties() is called multiple times for the same +package with different TYPEs, the TYPE is only changed to higher TYPEs +( RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED ), lower TYPEs are +ignored. The TYPE property is project-specific, so it cannot be set +by the Find-module, but must be set in the project. + +PURPOSE: This describes which features this package enables in the +project, i.e. it tells the user what functionality he gets in the +resulting binaries. If set_package_properties() is called multiple +times for a package, all PURPOSE properties are appended to a list of +purposes of the package in the project. As the TYPE property, also +the PURPOSE property is project-specific, so it cannot be set by the +Find-module, but must be set in the project. + + + +Example for setting the info for a package: + +:: + + find_package(LibXml2) + set_package_properties(LibXml2 PROPERTIES + DESCRIPTION "A XML processing library." + URL "http://xmlsoft.org/") + + + +:: + + set_package_properties(LibXml2 PROPERTIES + TYPE RECOMMENDED + PURPOSE "Enables HTML-import in MyWordProcessor") + ... + set_package_properties(LibXml2 PROPERTIES + TYPE OPTIONAL + PURPOSE "Enables odt-export in MyWordProcessor") + + + +:: + + find_package(DBUS) + set_package_properties(DBUS PROPERTIES + TYPE RUNTIME + PURPOSE "Necessary to disable the screensaver during a presentation" ) + + + +:: + + 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 describing 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: + +:: + + SET_PACKAGE_INFO(<name> <description> [<url> [<purpose>] ] ) + +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. + +:: + + 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>] ) + +Does the same as SET_PACKAGE_INFO(<name> <description> <url> ) +#]=======================================================================] #============================================================================= # Copyright 2007-2015 Kitware, Inc. |