From b62349cc60d71eb2af5648eb6867678d5b05273b Mon Sep 17 00:00:00 2001 From: Alex Neundorf Date: Sun, 17 Jul 2011 21:23:13 +0200 Subject: FeatureSummary.cmake: update documentation Alex --- Modules/FeatureSummary.cmake | 99 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 81 insertions(+), 18 deletions(-) (limited to 'Modules/FeatureSummary.cmake') diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake index 24196335a7..570fb7b034 100644 --- a/Modules/FeatureSummary.cmake +++ b/Modules/FeatureSummary.cmake @@ -1,18 +1,22 @@ # - Macros for generating a summary of enabled/disabled features # -# This module provides the macros feature_summary(), set_package_info() and +# This module provides the macros feature_summary(), set_package_properties() and # add_feature_info(). -# For compatiblity it also still provides set_feature_info(), -# print_enabled_features() and print_disabled_features. +# For compatiblity 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: # -# -- Enabled features: +# -- The following OPTIONAL packages have been found: # LibXml2 (required version >= 2.4) , XML processing library. , +# * Enables HTML-import in MyWordProcessor +# * Enables odt-export in MyWordProcessor # PNG , A PNG image library. , -# -- Disabled features: +# * Enables saving screenshots +# -- The following OPTIONAL packages have not been found: # Lua51 , The Lua scripting language. , +# * Enables macros in MyWordProcessor # Foo , Foo provides cool stuff. # # @@ -20,24 +24,34 @@ # [APPEND] # [VAR ] # [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 features or packages of a project. +# 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_FEATURE_INFO() to add more -# useful information, like e.g. a download URL for the respective package. +# 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 -# ALL: this will give all packages which have or 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 # # 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 @@ -47,19 +61,29 @@ # 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: +# 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_INFO( [ [] ] ) +# SET_PACKAGE_PROPERTIES( PROPERTIES [ URL ] +# [ DESCRIPTION ] +# [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ] +# [ 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 @@ -67,16 +91,47 @@ # 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_info(LibXml2 "XML processing library." "http://xmlsoft.org/") +# set_package_properties(LibXml2 PROPERTIES DESCRIPTION "A XML processing library." +# URL "http://xmlsoft.org/") # -# SET_PACKAGE_PROPERTIES( PROPERTIES [ [ [] ] ] ) +# 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") # -# URL: homepage of the package -# DESCRIPTION: short description of the package itself -# PURPOSE: what is the purpopse of using the package in the current project, always appended -# TYPE: OPTIONAL (default), RECOMMENDED, REQUIRED, RUNTIME +# find_package(DBUS) +# set_package_properties(LibXml2 PROPERTIES TYPE RUNTIME +# PURPOSE "Necessary to disable the screensaver during a presentation" ) # # ADD_FEATURE_INFO( ) # Use this macro to add information about a feature with the given . @@ -92,6 +147,14 @@ # # The following macros are provided for compatibility with previous CMake versions: # +# SET_PACKAGE_INFO( [ [] ] ) +# 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:") # @@ -336,7 +399,7 @@ FUNCTION(FEATURE_SUMMARY) SET(_tmp) _FS_GET_FEATURE_SUMMARY( ${part} _tmp ${_FS_INCLUDE_QUIET_PACKAGES}) IF(_tmp) - SET(_fullText "${_fullText}\n\n${title_${part}}\n${_tmp}") + SET(_fullText "${_fullText}\n\n-- ${title_${part}}\n${_tmp}") IF("${part}" STREQUAL "REQUIRED_PACKAGES_NOT_FOUND") SET(requiredPackagesNotFound TRUE) ENDIF() -- cgit v1.2.1