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.
This commit is contained in:
Brad King
parent
7c92c84302
commit
5d17e99580
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue