diff options
Diffstat (limited to 'Modules/FeatureSummary.cmake')
| -rw-r--r-- | Modules/FeatureSummary.cmake | 488 |
1 files changed, 241 insertions, 247 deletions
diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake index 9afdcd9..9a60587 100644 --- a/Modules/FeatureSummary.cmake +++ b/Modules/FeatureSummary.cmake @@ -2,19 +2,10 @@ FeatureSummary -------------- -Macros for generating a summary of enabled/disabled features +Functions 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: - -:: +These functions can be used to generate a summary of enabled and disabled +packages and/or feature for a build tree such as:: -- The following OPTIONAL packages have been found: LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org> @@ -27,242 +18,9 @@ packages and/or feature for a build tree: * Enables macros in MyWordProcessor Foo , Foo provides cool stuff. +Functions +^^^^^^^^^ - - - -:: - - 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> ) #]=======================================================================] #============================================================================= @@ -363,6 +121,95 @@ function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet) endfunction() +#[=======================================================================[.rst: +.. command:: feature_summary + + :: + + 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: + + .. code-block:: cmake + + 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: + + .. code-block:: cmake + + feature_summary(WHAT ALL + FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND) + + Example 2, print the enabled features into the variable + enabledFeaturesText, including QUIET packages: + + .. code-block:: cmake + + feature_summary(WHAT ENABLED_FEATURES + INCLUDE_QUIET_PACKAGES + DESCRIPTION "Enabled Features:" + VAR enabledFeaturesText) + message(STATUS "${enabledFeaturesText}") +#]=======================================================================] function(FEATURE_SUMMARY) # CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...) @@ -482,6 +329,83 @@ function(FEATURE_SUMMARY) endfunction() +#[=======================================================================[.rst: +.. command:: set_package_properties + + :: + + 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 <url>`` + This should be the homepage of the package, or something similar. + Ideally this is set already directly in the Find-module. + + ``DESCRIPTION <description>`` + A short description what that package is, at most one sentence. + Ideally this is set already directly in the Find-module. + + ``TYPE <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 <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: + + .. code-block:: cmake + + find_package(LibXml2) + set_package_properties(LibXml2 PROPERTIES + DESCRIPTION "A XML processing library." + URL "http://xmlsoft.org/") + # or + set_package_properties(LibXml2 PROPERTIES + TYPE RECOMMENDED + PURPOSE "Enables HTML-import in MyWordProcessor") + # or + 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") +#]=======================================================================] function(SET_PACKAGE_PROPERTIES _name _props) if(NOT "${_props}" STREQUAL "PROPERTIES") message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.") @@ -545,6 +469,26 @@ function(SET_PACKAGE_PROPERTIES _name _props) endfunction() +#[=======================================================================[.rst: +.. command:: add_feature_info + + :: + + 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: + + .. code-block:: cmake + + option(WITH_FOO "Help for foo" ON) + add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.") +#]=======================================================================] function(ADD_FEATURE_INFO _name _enabled _desc) if (${_enabled}) set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}") @@ -558,6 +502,25 @@ endfunction() # The stuff below is only kept for compatibility +#[=======================================================================[.rst: +Legacy Macros +^^^^^^^^^^^^^ + +The following macros are provided for compatibility with previous +CMake versions: + +.. command:: set_package_info + + :: + + 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 :command:`find_package` call. The features for which information + can be set are added automatically by the ``find_package()`` command. +#]=======================================================================] function(SET_PACKAGE_INFO _name _desc) unset(_url) unset(_purpose) @@ -576,20 +539,51 @@ function(SET_PACKAGE_INFO _name _desc) endif() endfunction() +#[=======================================================================[.rst: +.. command:: set_feature_info + + :: + + set_feature_info(<name> <description> [<url>]) + Does the same as:: + set_package_info(<name> <description> <url>) +#]=======================================================================] function(SET_FEATURE_INFO) SET_PACKAGE_INFO(${ARGN}) endfunction() +#[=======================================================================[.rst: +.. command:: print_enabled_features + :: + print_enabled_features() + + Does the same as + + .. code-block:: cmake + + feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:") +#]=======================================================================] function(PRINT_ENABLED_FEATURES) FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:") endfunction() +#[=======================================================================[.rst: +.. command:: print_disabled_features + :: + print_disabled_features() + + Does the same as + + .. code-block:: cmake + + feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:") +#]=======================================================================] function(PRINT_DISABLED_FEATURES) FEATURE_SUMMARY(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:") endfunction() |