FeatureSummary.cmake: update documentation

Alex
This commit is contained in:
Alex Neundorf 2011-07-17 21:23:13 +02:00
parent f366cf8a86
commit b62349cc60
1 changed files with 81 additions and 18 deletions

View File

@ -1,18 +1,22 @@
# - Macros for generating a summary of enabled/disabled features # - 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(). # add_feature_info().
# For compatiblity it also still provides set_feature_info(), # For compatiblity it also still provides set_package_info(), set_feature_info(),
# print_enabled_features() and print_disabled_features. # print_enabled_features() and print_disabled_features().
# #
# These macros can be used to generate a summary of enabled and disabled # These macros can be used to generate a summary of enabled and disabled
# packages and/or feature for a build tree: # 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. , <http://xmlsoft.org> # LibXml2 (required version >= 2.4) , XML processing library. , <http://xmlsoft.org>
# * Enables HTML-import in MyWordProcessor
# * Enables odt-export in MyWordProcessor
# PNG , A PNG image library. , <http://www.libpng.org/pub/png/> # PNG , A PNG image library. , <http://www.libpng.org/pub/png/>
# -- Disabled features: # * Enables saving screenshots
# -- The following OPTIONAL packages have not been found:
# Lua51 , The Lua scripting language. , <http://www.lua.org> # Lua51 , The Lua scripting language. , <http://www.lua.org>
# * Enables macros in MyWordProcessor
# Foo , Foo provides cool stuff. # Foo , Foo provides cool stuff.
# #
# #
@ -20,24 +24,34 @@
# [APPEND] # [APPEND]
# [VAR <variable_name>] # [VAR <variable_name>]
# [INCLUDE_QUIET_PACKAGES] # [INCLUDE_QUIET_PACKAGES]
# [FATAL_ON_MISSING_REQUIRED_PACKAGES]
# [DESCRIPTION "Found packages:"] # [DESCRIPTION "Found packages:"]
# WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND # WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
# | ENABLED_FEATURES | DISABLED_FEATURES] # | ENABLED_FEATURES | DISABLED_FEATURES]
# ) # )
# #
# The FEATURE_SUMMARY() macro can be used to print information about enabled # 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 # 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 # 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. # 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 # The WHAT option is the only mandatory option. Here you specify what information
# will be printed: # will be printed:
# ALL: print everything
# ENABLED_FEATURES: the list of all features which are enabled # ENABLED_FEATURES: the list of all features which are enabled
# DISABLED_FEATURES: the list of all features which are disabled # DISABLED_FEATURES: the list of all features which are disabled
# PACKAGES_FOUND: the list of all packages which have been found # PACKAGES_FOUND: the list of all packages which have been found
# PACKAGES_NOT_FOUND: the list of all packages which have not 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 # 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 # 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. # 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 # Using the DESCRIPTION option a description or headline can be set which will
# be printed above the actual content. # 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: # Example 1, append everything to a file:
# feature_summary(WHAT ALL # feature_summary(WHAT ALL
# FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND) # 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 # feature_summary(WHAT ENABLED_FEATURES
# INCLUDE_QUIET_PACKAGES
# DESCRIPTION "Enabled Features:" # DESCRIPTION "Enabled Features:"
# VAR enabledFeaturesText) # VAR enabledFeaturesText)
# message(STATUS "${enabledFeaturesText}") # message(STATUS "${enabledFeaturesText}")
# #
# #
# SET_PACKAGE_INFO(<name> <description> [<url> [<purpose>] ] ) # 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 # Use this macro to set up information about the named package, which can
# then be displayed via FEATURE_SUMMARY(). # then be displayed via FEATURE_SUMMARY().
# This can be done either directly in the Find-module or in the project # 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 # The features for which information can be set are added automatically by the
# find_package() command. # 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: # Example for setting the info for a package:
# find_package(LibXml2) # 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(<name> PROPERTIES <description> [<url> [<purpose> [<type>] ] ] ) # 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 # find_package(DBUS)
# DESCRIPTION: short description of the package itself # set_package_properties(LibXml2 PROPERTIES TYPE RUNTIME
# PURPOSE: what is the purpopse of using the package in the current project, always appended # PURPOSE "Necessary to disable the screensaver during a presentation" )
# TYPE: OPTIONAL (default), RECOMMENDED, REQUIRED, RUNTIME
# #
# ADD_FEATURE_INFO(<name> <enabled> <description>) # ADD_FEATURE_INFO(<name> <enabled> <description>)
# Use this macro to add information about a feature with the given <name>. # Use this macro to add information about a feature with the given <name>.
@ -92,6 +147,14 @@
# #
# The following macros are provided for compatibility with previous CMake versions: # 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() # PRINT_ENABLED_FEATURES()
# Does the same as FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:") # Does the same as FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
# #
@ -336,7 +399,7 @@ FUNCTION(FEATURE_SUMMARY)
SET(_tmp) SET(_tmp)
_FS_GET_FEATURE_SUMMARY( ${part} _tmp ${_FS_INCLUDE_QUIET_PACKAGES}) _FS_GET_FEATURE_SUMMARY( ${part} _tmp ${_FS_INCLUDE_QUIET_PACKAGES})
IF(_tmp) 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") IF("${part}" STREQUAL "REQUIRED_PACKAGES_NOT_FOUND")
SET(requiredPackagesNotFound TRUE) SET(requiredPackagesNotFound TRUE)
ENDIF() ENDIF()