mirrors/cmake
2
0 Fork 0
mirror of https://gitlab.kitware.com/cmake/cmake.git synced 2026-10-09 23:44:00 +03:00
Code Activity

FeatureSummary: Update documentation

Browse Source 
- Refactored and synced module documentation.
- Moved all documentation to the top header comment to make it easier to
  manage and adjust.
- Added table of contents.
- Added intro code block showing how to use this module.
- Described arguments of commands as a list.
- Used word "commands" instead of "functions".
- Added separate examples section with more examples.
This commit is contained in:
Peter Kokot committed 2025-08-11 10:32:40 +02:00
1 parent 1443123892
commit 361af2b480
2 files changed
+545 -393
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Help/policy/CMP0183.rst
+1 -1
View File
@@ -5,7 +5,7 @@ CMP0183
:command:`add_feature_info` supports full :ref:`Condition Syntax`.
The ``<enabled>`` parameter accepts a :ref:`semicolon-separated list <CMake
The ``<condition>`` parameter accepts a :ref:`semicolon-separated list <CMake
Language Lists>` of conditions. CMake 3.31 and lower evaluate each
``condition`` as ``if(${condition})``, which does not properly handle
conditions with nested paren groups. CMake 4.0 and above instead prefer
Modules/FeatureSummary.cmake
+544 -392
View File
@@ -7,32 +7,45 @@ include_guard(GLOBAL)
FeatureSummary
--------------
Functions for generating a summary of enabled/disabled features.
.. only:: html
These functions can be used to generate a summary of enabled and disabled
packages and/or features for a build tree such as::
.. contents::
-- The following features have been enabled:
This module provides commands for generating a summary of enabled/disabled
features.
* Example, usage example
Load this module in CMake with:
-- The following OPTIONAL packages have been found:
.. code-block:: cmake
* LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org>
Enables HTML-import in MyWordProcessor
Enables odt-export in MyWordProcessor
* PNG, image library, <http://www.libpng.org/pub/png/>
Enables saving screenshots
include(FeatureSummary)
-- The following OPTIONAL packages have not been found:
Commands provided by this module can be used to generate a summary of enabled
and disabled packages and/or features for a build tree such as::
* Lua, the Lua scripting language, <https://www.lua.org>
Enables macros in MyWordProcessor
* OpenGL, Open Graphics Library
-- The following features have been enabled:
* Example, usage example
-- The following OPTIONAL packages have been found:
* LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org>
Enables HTML-import in MyWordProcessor
Enables odt-export in MyWordProcessor
* PNG, image library, <http://www.libpng.org/pub/png/>
Enables saving screenshots
-- The following OPTIONAL packages have not been found:
* Lua, the Lua scripting language, <https://www.lua.org>
Enables macros in MyWordProcessor
* OpenGL, Open Graphics Library
Global Properties
^^^^^^^^^^^^^^^^^
The following global properties are used by this module:
.. variable:: FeatureSummary_PKG_TYPES
.. versionadded:: 3.8
@@ -69,8 +82,9 @@ Global Properties
This global property defines the default package type.
When the :command:`feature_summary()` command is called, and the user has not
explicitly set a type of some package, its type will be set to this value.
When the :command:`feature_summary()` command is called, and the user has
not explicitly set a type of some package, its type will be set to the
value of this property.
This value must be one of the types defined in the
:variable:`FeatureSummary_PKG_TYPES` global property.
@@ -88,6 +102,519 @@ Global Properties
The following <FeatureSummary_<TYPE>_DESCRIPTION> have been found:
If not set, default string ``<TYPE> packages`` is used.
Commands
^^^^^^^^
This module provides the following commands:
* :command:`feature_summary`
* :command:`set_package_properties`
* :command:`add_feature_info`
Printing Feature Summary
""""""""""""""""""""""""
.. command:: feature_summary
Prints information about enabled or disabled packages and features of a
project:
.. code-block:: cmake
feature_summary(
WHAT (ALL
| PACKAGES_FOUND | PACKAGES_NOT_FOUND
| <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
| ENABLED_FEATURES | DISABLED_FEATURES)
[FILENAME <file>]
[APPEND]
[VAR <variable-name>]
[INCLUDE_QUIET_PACKAGES]
[FATAL_ON_MISSING_REQUIRED_PACKAGES]
[DESCRIPTION <description> | DEFAULT_DESCRIPTION]
[QUIET_ON_EMPTY]
)
This command can be used to print information about enabled or disabled
packages and 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 :command:`set_package_properties()` to add more useful
information, e.g., a homepage URL for the respective package or their
purpose in the project.
.. rubric:: The arguments are:
``WHAT``
This is the only mandatory option. It specifies 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.
For each package type ``<TYPE>`` defined by the
:variable:`FeatureSummary_PKG_TYPES` global property, the following
information can also be used:
``<TYPE>_PACKAGES_FOUND``
The list of only packages of type ``<TYPE>`` which have been found.
``<TYPE>_PACKAGES_NOT_FOUND``
The list of only packages of type ``<TYPE>`` which have not been found.
.. versionchanged:: 3.1
The ``WHAT`` option is now a multi-value keyword, so that these values can
be combined, with the exception of the ``ALL`` value, in order to
customize the output. For example:
.. code-block:: cmake
feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
``FILENAME <file>``
If this option is given, the information is printed into this file instead
of the terminal. Relative ``<file>`` path is interpreted as being relative
to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
``APPEND``
If this option is given, the output is appended to the ``<file>`` provided
by the ``FILENAME`` option, otherwise the file is overwritten if it already
exists.
``VAR <variable-name>``
If this option is given, the information is stored into the specified
variable ``<variable-name>`` instead of the terminal.
``INCLUDE_QUIET_PACKAGES``
If this option is given, packages which have been searched with
:command:`find_package(... QUIET)` will also be listed. By default they are
skipped.
``FATAL_ON_MISSING_REQUIRED_PACKAGES``
If this option is given, CMake will abort with fatal error if a package
which is marked as one of the package types listed in the
:variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property has not been
found.
``DESCRIPTION <description>``
A description or headline which will be printed above the actual content.
Without this option, if only one package type was requested, no title is
printed, unless a custom string is explicitly set using this option or
``DEFAULT_DESCRIPTION`` option is used that outputs a default title for the
requested type.
``DEFAULT_DESCRIPTION``
.. versionadded:: 3.9
The default description or headline to be printed above the content as
opposed to the customizable ``DESCRIPTION <description>``.
``QUIET_ON_EMPTY``
.. versionadded:: 3.8
If this option is given, when only one package type was requested, and no
packages belonging to that category were found, then no output (including
the ``DESCRIPTION``) is printed nor added to the ``FILENAME``, or the
``VAR`` variable.
Package Properties
""""""""""""""""""
.. command:: set_package_properties
Sets package properties:
.. code-block:: cmake
set_package_properties(
<PackageName>
PROPERTIES
[URL <url>]
[DESCRIPTION <description>]
[TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
[PURPOSE <purpose>]
)
Use this command to configure and provide information about the package
named ``<PackageName>``, which can then be displayed using the
:command:`feature_summary()` command. This command can be called either
directly within the corresponding :ref:`Find module <Find Modules>` or in
the project that uses the module after invoking the :command:`find_package()`
call. The features for which information can be set are determined
automatically after the :command:`find_package()` command.
.. rubric:: The arguments are:
``<PackageName>``
The name of the package. For example, as specified in the
:command:`find_package(<PackageName>)` argument.
``PROPERTIES``
Specifies the properties to set:
``URL <url>``
This should be the homepage of the package, or something similar.
Ideally this is set already directly in the
:ref:`Find module <Find Modules>`.
``DESCRIPTION <description>``
A short description what that package is, at most one sentence.
Ideally this is set already directly in the
:ref:`Find module <Find Modules>`.
``TYPE <type>``
What type of dependency has the using project on that package.
Default ``<type>`` is ``OPTIONAL``. In this case it is a package
which can be used by the project when available at buildtime, but the
project also works without it.
``RECOMMENDED`` package type 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 severely limited. If
a ``REQUIRED`` package is not available at buildtime, the project may
not even build. This can be combined with the
:command:`feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES)` command
option.
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 :ref:`Find module <Find Modules>`, but must be set in
the project.
The accepted types can be changed by setting the
:variable:`FeatureSummary_PKG_TYPES` global property.
``PURPOSE <purpose>``
This describes which features this package enables in the project,
i.e. it tells the user what functionality they get 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 :ref:`Find module <Find Modules>`, but must be set in the
project.
Adding Feature Info
"""""""""""""""""""
.. command:: add_feature_info
Adds feature information:
.. code-block:: cmake
add_feature_info(<name> <condition> <description>)
Use this command to add information about a feature identified with a given
``<name>``.
.. rubric:: The arguments are:
``<name>``
Identification name for a feature being added.
``<condition>``
Specifies the conditions that determine whether this feature is enabled
or disabled.
The ``<condition>`` argument can be:
* A single condition (such as a variable name).
* .. versionadded:: 3.8
A :ref:`semicolon-separated list <CMake Language Lists>` of multiple
conditions.
* .. versionadded:: 4.0
A full :ref:`Condition Syntax` as used in an ``if(<condition>)``
clause. See policy :policy:`CMP0183`. This enables using entire
condition syntax (such as grouping conditions with parens and
similar).
``<description>``
A text describing the feature. This information can be displayed using
:command:`feature_summary()` for ``ENABLED_FEATURES`` and
``DISABLED_FEATURES`` respectively.
Deprecated Commands
"""""""""""""""""""
The following legacy and deprecated commands are provided for backward
compatibility with previous CMake versions:
.. command:: set_package_info
.. deprecated:: 3.8
Use the :command:`set_package_properties`, and :command:`add_feature_info`
commands instead.
Sets up information about the specified package, which can then be displayed
via :command:`feature_summary()`:
.. code-block:: cmake
set_package_info(<PackageName> <description> [<url> [<purpose>]])
``<PackageName>``
Name of the package.
``<description>``
A short description of the package.
``<url>``
Homepage of the package.
``<purpose>``
The purpose of the package.
This command can be used either directly in the
:ref:`Find module <Find Modules>` or in the project which uses the
``FeatureSummary`` module after the :command:`find_package()` call. The
features for which information can be set are added automatically by the
``find_package()`` command.
.. command:: set_feature_info
.. deprecated:: 3.8
Sets feature info for a package:
.. code-block:: cmake
set_feature_info(<name> <description> [<url>])
Does the same as:
.. code-block:: cmake
set_package_info(<name> <description> [<url>])
.. command:: print_enabled_features
.. deprecated:: 3.8
Prints enabled features:
.. code-block:: cmake
print_enabled_features()
Does the same as:
.. code-block:: cmake
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
.. command:: print_disabled_features
.. deprecated:: 3.8
Prints disabled features:
.. code-block:: cmake
print_disabled_features()
Does the same as:
.. code-block:: cmake
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
Examples
^^^^^^^^
Example: Appending Feature Summary to a File
""""""""""""""""""""""""""""""""""""""""""""
In the following example, the feature summary output will be appended to
a specified file instead of printing:
.. code-block:: cmake
include(FeatureSummary)
feature_summary(WHAT ALL FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
Example: Storing Feature Summary in a Variable
""""""""""""""""""""""""""""""""""""""""""""""
In the following example, the feature summary of enabled features is stored
in a specified variable ``enabledFeaturesText``, including the ``QUIET``
packages:
.. code-block:: cmake
include(FeatureSummary)
feature_summary(
WHAT ENABLED_FEATURES
INCLUDE_QUIET_PACKAGES
DESCRIPTION "Enabled Features:"
VAR enabledFeaturesText
)
message(STATUS "${enabledFeaturesText}")
Example: Adding a Custom Package Type
"""""""""""""""""""""""""""""""""""""
In the following example a custom package type is added and printed only
the categories that are not empty:
.. code-block:: cmake
include(FeatureSummary)
set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
find_package(FOO)
set_package_properties(FOO PROPERTIES TYPE BUILD)
feature_summary(
WHAT BUILD_PACKAGES_FOUND
DESCRIPTION "Build tools found:"
QUIET_ON_EMPTY
)
feature_summary(
WHAT BUILD_PACKAGES_NOT_FOUND
DESCRIPTION "Build tools not found:"
QUIET_ON_EMPTY
)
Example: Setting Package Info
"""""""""""""""""""""""""""""
Example for setting the info for a package:
.. code-block:: cmake
include(FeatureSummary)
find_package(LibXml2)
set_package_properties(
LibXml2
PROPERTIES
DESCRIPTION "XML 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"
)
Example: Printing Feature Summary
"""""""""""""""""""""""""""""""""
In the following example, this module is used to output feature summary at
the end of the configuration. If any required package is not found,
processing stops with an error message at the end of the configuration
phase.
.. code-block:: cmake
cmake_minimum_required(VERSION 3.15)
project(Example)
add_library(example example.c)
include(FeatureSummary)
find_package(CURL)
set_package_properties(CURL PROPERTIES TYPE REQUIRED)
target_link_libraries(example PRIVATE CURL::libcurl)
find_package(LibXml2 QUIET)
set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED)
if(LibXml2_FOUND)
target_link_libraries(example PRIVATE LibXml2::LibXml2)
endif()
feature_summary(
WHAT ALL
INCLUDE_QUIET_PACKAGES
DESCRIPTION "Feature summary:"
FATAL_ON_MISSING_REQUIRED_PACKAGES
)
Examples: Setting Feature Info
""""""""""""""""""""""""""""""
Example for setting the info for a feature:
.. code-block:: cmake
include(FeatureSummary)
option(WITH_FOO "Help for foo" ON)
add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")
Example for setting feature info based on a list of conditions:
.. code-block:: cmake
include(FeatureSummary)
option(WITH_FOO "Help for foo" ON)
option(WITH_BAR "Help for bar" OFF)
add_feature_info(
FooBar
"WITH_FOO;NOT WITH_BAR"
"this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF"
)
In the next example feature info are set depending on a full condition
syntax. Unlike semicolon-separated list of conditions, this enables using
entire condition syntax as being the ``if`` clause argument:
.. code-block:: cmake
include(FeatureSummary)
option(WITH_FOO "Help for foo" ON)
option(WITH_BAR "Help for bar" ON)
option(WITH_BAZ "Help for baz" OFF)
add_feature_info(
FooBarBaz
"WITH_FOO AND (WITH_BAR OR WITH_BAZ)"
"this feature is enabled when the entire condition is true"
)
#]=======================================================================]
get_property(_fsPkgTypeIsSet GLOBAL PROPERTY FeatureSummary_PKG_TYPES SET)
@@ -105,15 +632,7 @@ if(NOT _fsDefaultPkgTypeIsSet)
set_property(GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE OPTIONAL)
endif()
#[=======================================================================[.rst:
Functions
^^^^^^^^^
#]=======================================================================]
function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
get_property(_fsPkgTypes GLOBAL PROPERTY FeatureSummary_PKG_TYPES)
get_property(_fsDefaultPkgType GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE)
@@ -208,155 +727,6 @@ function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
set(${_var} "${_currentFeatureText}" PARENT_SCOPE)
endfunction()
#[=======================================================================[.rst:
.. command:: feature_summary
.. code-block:: cmake
feature_summary([FILENAME <file>]
[APPEND]
[VAR <variable_name>]
[INCLUDE_QUIET_PACKAGES]
[FATAL_ON_MISSING_REQUIRED_PACKAGES]
[DESCRIPTION <description> | DEFAULT_DESCRIPTION]
[QUIET_ON_EMPTY]
WHAT (ALL
| PACKAGES_FOUND | PACKAGES_NOT_FOUND
| <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
| ENABLED_FEATURES | DISABLED_FEATURES)
)
This function can be used to print information about
enabled or disabled packages and 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
:command:`set_package_properties()` to add more useful information, like e.g.
a homepage URL for the respective package or their purpose in the project.
The options are:
``WHAT``
This is the only mandatory option. It specifies 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.
For each package type ``<TYPE>`` defined by the
:variable:`FeatureSummary_PKG_TYPES` global property, the following
information can also be used:
``<TYPE>_PACKAGES_FOUND``
The list of only packages of type ``<TYPE>`` which have been found.
``<TYPE>_PACKAGES_NOT_FOUND``
The list of only packages of type ``<TYPE>`` which have not been found.
.. versionchanged:: 3.1
The ``WHAT`` option is now a multi-value keyword, so that these values can
be combined, with the exception of the ``ALL`` value, in order to
customize the output. For example:
.. code-block:: cmake
feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
``FILENAME <file>``
If this option is given, the information is printed into this file instead
of the terminal. Relative ``<file>`` path is interpreted as being relative
to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
``APPEND``
If this option is given, the output is appended to the ``<file>`` provided
by the ``FILENAME`` option, otherwise the file is overwritten if it already
exists.
``VAR <variable_name>``
If this option is given, the information is stored into the specified
variable ``<variable_name>`` instead of the terminal.
``DESCRIPTION <description>``
A description or headline which will be printed above the actual content.
Without this option, if only one package type was requested, no title is
printed, unless a custom string is explicitly set using this option or
``DEFAULT_DESCRIPTION`` option is used that outputs a default title for the
requested type.
``DEFAULT_DESCRIPTION``
.. versionadded:: 3.9
The default description or headline to be printed above the content as
opposed to the customizable ``DESCRIPTION <description>``.
``INCLUDE_QUIET_PACKAGES``
If this option is given, packages which have been searched with
:command:`find_package(... QUIET)` will also be listed. By default they are
skipped.
``FATAL_ON_MISSING_REQUIRED_PACKAGES``
If this option is given, CMake will abort with fatal error if a package
which is marked as one of the package types listed in the
:variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property has not been
found.
The :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global property can be
modified to change the default package type assigned when not explicitly
assigned by the user.
``QUIET_ON_EMPTY``
.. versionadded:: 3.8
If this option is given, when only one package type was requested, and no
packages belonging to that category were found, then no output (including
the ``DESCRIPTION``) is printed nor added to the ``FILENAME``, or the
``VAR`` variable.
Example 1, append everything to a file:
.. code-block:: cmake
include(FeatureSummary)
feature_summary(WHAT ALL
FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
Example 2, print the enabled features into the variable
``enabledFeaturesText``, including the ``QUIET`` packages:
.. code-block:: cmake
include(FeatureSummary)
feature_summary(WHAT ENABLED_FEATURES
INCLUDE_QUIET_PACKAGES
DESCRIPTION "Enabled Features:"
VAR enabledFeaturesText)
message(STATUS "${enabledFeaturesText}")
Example 3, add custom package type and print only the categories that are not
empty:
.. code-block:: cmake
include(FeatureSummary)
set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
find_package(FOO)
set_package_properties(FOO PROPERTIES TYPE BUILD)
feature_summary(WHAT BUILD_PACKAGES_FOUND
DESCRIPTION "Build tools found:"
QUIET_ON_EMPTY)
feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
DESCRIPTION "Build tools not found:"
QUIET_ON_EMPTY)
#]=======================================================================]
function(FEATURE_SUMMARY)
# cmake_parse_arguments(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
set(options APPEND
@@ -498,93 +868,8 @@ function(FEATURE_SUMMARY)
if(requiredPackagesNotFound AND _FS_FATAL_ON_MISSING_REQUIRED_PACKAGES)
message(FATAL_ERROR "feature_summary() Error: REQUIRED package(s) are missing, aborting CMake run.")
endif()
endfunction()
#[=======================================================================[.rst:
.. command:: set_package_properties
.. code-block:: cmake
set_package_properties(<name> PROPERTIES
[URL <url>]
[DESCRIPTION <description>]
[TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
[PURPOSE <purpose>]
)
Use this function to configure and provide information about the package named
``<name>``, which can then be displayed using the
:command:`feature_summary()` command. This can be performed either directly
within the corresponding :ref:`Find module <Find Modules>` or in the project
that uses the module after invoking the :command:`find_package()` call. The
features for which information can be set are determined automatically after
the :command:`find_package()` command.
``URL <url>``
This should be the homepage of the package, or something similar.
Ideally this is set already directly in the
:ref:`Find module <Find Modules>`.
``DESCRIPTION <description>``
A short description what that package is, at most one sentence.
Ideally this is set already directly in the
:ref:`Find module <Find Modules>`.
``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 severely limited. If a ``REQUIRED`` package is not
available at buildtime, the project may not even build. This can be
combined with the
:command:`feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES)` command
option. 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 :ref:`Find module <Find Modules>`, but must be set in the project.
The accepted types can be changed by setting the
:variable:`FeatureSummary_PKG_TYPES` global property.
``PURPOSE <purpose>``
This describes which features this package enables in the
project, i.e. it tells the user what functionality they get 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
:ref:`Find module <Find Modules>`, but must be set in the project.
Example for setting the info for a package:
.. code-block:: cmake
include(FeatureSummary)
find_package(LibXml2)
set_package_properties(LibXml2 PROPERTIES
DESCRIPTION "XML 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)
if(NOT "${_props}" STREQUAL "PROPERTIES")
message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
@@ -609,7 +894,6 @@ function(SET_PACKAGE_PROPERTIES _name _props)
set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_SPP_DESCRIPTION}" )
endif()
if(_SPP_URL)
get_property(_info GLOBAL PROPERTY _CMAKE_${_name}_URL)
if(_info AND NOT "${_info}" STREQUAL "${_SPP_URL}")
@@ -619,7 +903,6 @@ function(SET_PACKAGE_PROPERTIES _name _props)
set_property(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_SPP_URL}" )
endif()
# handle the PURPOSE: use APPEND, since there can be multiple purposes for one package inside a project
if(_SPP_PURPOSE)
set_property(GLOBAL APPEND PROPERTY _CMAKE_${_name}_PURPOSE "${_SPP_PURPOSE}" )
@@ -648,68 +931,8 @@ function(SET_PACKAGE_PROPERTIES _name _props)
set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" )
endif()
endif()
endfunction()
#[=======================================================================[.rst:
.. command:: add_feature_info
.. code-block:: cmake
add_feature_info(<name> <enabled> <description>)
Use this function to add information about a feature identified with a given
``<name>``. The ``<enabled>`` contains whether this feature is enabled or
not. It can be a variable or a list of conditions.
``<description>`` is a text describing the feature. The information can
be displayed using :command:`feature_summary()` for ``ENABLED_FEATURES`` and
``DISABLED_FEATURES`` respectively.
.. versionchanged:: 3.8
``<enabled>`` can be a list of conditions.
.. versionchanged:: 4.0
Full :ref:`Condition Syntax` is now supported for ``<enabled>``.
See policy :policy:`CMP0183`.
Example for setting the info for a feature:
.. code-block:: cmake
include(FeatureSummary)
option(WITH_FOO "Help for foo" ON)
add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")
Example for setting feature info based on a list of conditions:
.. code-block:: cmake
option(WITH_FOO "Help for foo" ON)
option(WITH_BAR "Help for bar" OFF)
add_feature_info(
FooBar
"WITH_FOO;NOT WITH_BAR"
"this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF"
)
Example for setting feature info depending on a full condition syntax:
Unlike semicolon-separated list of conditions, this enables using entire
condition syntax as being the ``if`` clause argument, such as grouping
conditions with parens and similar.
.. code-block:: cmake
option(WITH_FOO "Help for foo" ON)
option(WITH_BAR "Help for bar" ON)
option(WITH_BAZ "Help for baz" OFF)
add_feature_info(
FooBarBaz
"WITH_FOO AND (WITH_BAR OR WITH_BAZ)"
"this feature is enabled when the entire condition is true"
)
#]=======================================================================]
function(ADD_FEATURE_INFO _name _depends _desc)
cmake_policy(GET CMP0183 _CDO_CMP0183
PARENT_SCOPE # undocumented, do not use outside of CMake
@@ -749,34 +972,8 @@ function(ADD_FEATURE_INFO _name _depends _desc)
unset(_CDO_CMP0183)
endfunction()
# The stuff below is only kept for compatibility
#[=======================================================================[.rst:
Deprecated Functions
^^^^^^^^^^^^^^^^^^^^
The following legacy and deprecated functions are provided for backward
compatibility with previous CMake versions:
.. command:: set_package_info
.. deprecated:: 3.8
.. code-block:: cmake
set_package_info(<name> <description> [ <url> [<purpose>] ])
Set up information about the package ``<name>``, which can then be displayed
via :command:`feature_summary()`. This can be done either directly in the
:ref:`Find module <Find Modules>` or in the project which uses the
``FeatureSummary`` module after the :command:`find_package()` call. The
features for which information can be set are added automatically by the
``find_package()`` command.
This function is deprecated. Use the :command:`set_package_properties()`, and
:command:`add_feature_info()` functions instead.
#]=======================================================================]
function(SET_PACKAGE_INFO _name _desc)
message(DEPRECATION "SET_PACKAGE_INFO is deprecated. Use SET_PACKAGE_PROPERTIES instead.")
unset(_url)
@@ -796,62 +993,17 @@ function(SET_PACKAGE_INFO _name _desc)
endif()
endfunction()
#[=======================================================================[.rst:
.. command:: set_feature_info
.. deprecated:: 3.8
.. code-block:: cmake
set_feature_info(<name> <description> [<url>])
Does the same as:
.. code-block:: cmake
set_package_info(<name> <description> [<url>])
#]=======================================================================]
function(SET_FEATURE_INFO)
message(DEPRECATION "SET_FEATURE_INFO is deprecated. Use ADD_FEATURE_INFO instead.")
set_package_info(${ARGN})
endfunction()
#[=======================================================================[.rst:
.. command:: print_enabled_features
.. deprecated:: 3.8
.. code-block:: cmake
print_enabled_features()
Does the same as:
.. code-block:: cmake
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
#]=======================================================================]
function(PRINT_ENABLED_FEATURES)
message(DEPRECATION "PRINT_ENABLED_FEATURES is deprecated. Use
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION \"Enabled features:\")")
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
endfunction()
#[=======================================================================[.rst:
.. command:: print_disabled_features
.. deprecated:: 3.8
.. code-block:: cmake
print_disabled_features()
Does the same as:
.. code-block:: cmake
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
#]=======================================================================]
function(PRINT_DISABLED_FEATURES)
message(DEPRECATION "PRINT_DISABLED_FEATURES is deprecated. Use
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION \"Disabled features:\")")