summaryrefslogtreecommitdiffstats
path: root/Modules/FeatureSummary.cmake
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2016-09-15 13:50:32 (GMT)
committerBrad King <brad.king@kitware.com>2016-09-15 13:50:32 (GMT)
commit5d17e995801dd916446c232eb36f1b330106578f (patch)
tree9953de4ebeb4a1f98d528dbdde1bf97297f65d8f /Modules/FeatureSummary.cmake
parent7c92c84302827b33ea47f7fb6ca5b2ff98451d44 (diff)
downloadCMake-5d17e995801dd916446c232eb36f1b330106578f.zip
CMake-5d17e995801dd916446c232eb36f1b330106578f.tar.gz
CMake-5d17e995801dd916446c232eb36f1b330106578f.tar.bz2
FeatureSummary: Convert docs to a bracket comment
Use a bracket comment to hold the documentation instead of a block of line comments. This will make further updates easier.
Diffstat (limited to 'Modules/FeatureSummary.cmake')
-rw-r--r--Modules/FeatureSummary.cmake531
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.