FeatureSummary: Format documentation
Revise the documentation using reStructuredText inline markup and explicit blocks so that it formats well.
This commit is contained in:
Brad King
parent
5d17e99580
commit
46ded385c0
|
|
@ -2,19 +2,10 @@
|
||||||
FeatureSummary
|
FeatureSummary
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
Macros for generating a summary of enabled/disabled features
|
Functions for generating a summary of enabled/disabled features.
|
||||||
|
|
||||||
|
These functions can be used to generate a summary of enabled and disabled
|
||||||
|
packages and/or feature for a build tree such as::
|
||||||
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:
|
-- The following OPTIONAL packages have been found:
|
||||||
LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
|
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
|
* Enables macros in MyWordProcessor
|
||||||
Foo , Foo provides cool stuff.
|
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()
|
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)
|
function(FEATURE_SUMMARY)
|
||||||
# CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
|
# CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
|
||||||
|
|
@ -482,6 +329,83 @@ function(FEATURE_SUMMARY)
|
||||||
|
|
||||||
endfunction()
|
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)
|
function(SET_PACKAGE_PROPERTIES _name _props)
|
||||||
if(NOT "${_props}" STREQUAL "PROPERTIES")
|
if(NOT "${_props}" STREQUAL "PROPERTIES")
|
||||||
message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
|
message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
|
||||||
|
|
@ -545,6 +469,26 @@ function(SET_PACKAGE_PROPERTIES _name _props)
|
||||||
|
|
||||||
endfunction()
|
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)
|
function(ADD_FEATURE_INFO _name _enabled _desc)
|
||||||
if (${_enabled})
|
if (${_enabled})
|
||||||
set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
|
set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
|
||||||
|
|
@ -558,6 +502,25 @@ endfunction()
|
||||||
|
|
||||||
# The stuff below is only kept for compatibility
|
# 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)
|
function(SET_PACKAGE_INFO _name _desc)
|
||||||
unset(_url)
|
unset(_url)
|
||||||
unset(_purpose)
|
unset(_purpose)
|
||||||
|
|
@ -576,20 +539,51 @@ function(SET_PACKAGE_INFO _name _desc)
|
||||||
endif()
|
endif()
|
||||||
endfunction()
|
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)
|
function(SET_FEATURE_INFO)
|
||||||
SET_PACKAGE_INFO(${ARGN})
|
SET_PACKAGE_INFO(${ARGN})
|
||||||
endfunction()
|
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)
|
function(PRINT_ENABLED_FEATURES)
|
||||||
FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
|
FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
|
||||||
endfunction()
|
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)
|
function(PRINT_DISABLED_FEATURES)
|
||||||
FEATURE_SUMMARY(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
|
FEATURE_SUMMARY(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
|
||||||
endfunction()
|
endfunction()
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue